Increase Card Validations API
Card Validations are used to validate a card and its cardholder before sending funds to or pulling funds from a card.
OpenAPI Specification
openapi: 3.1.0
info:
description: Anything that you can achieve with PDFs, presence, and persistence in a bank branch you can do with our API. We've always wanted a fully programmatic bank so we built one. Our API faithfully exposes the data and capabilities of the Federal Reserve, Visa, The Clearing House, depository networks, and accounting tools. It's lovingly boring and exceptionally powerful. If you have any questions or want to get started, don't hesitate to ping us at sales@increase.com. We can't wait to see what you build!
title: Increase Account Numbers Card Validations API
version: 0.0.1
servers:
- url: https://api.increase.com
- url: https://sandbox.increase.com
security:
- bearerAuth: []
tags:
- description: Card Validations are used to validate a card and its cardholder before sending funds to or pulling funds from a card.
name: Card Validations
paths:
/card_validations:
get:
operationId: list_card_validations
parameters:
- in: query
name: cursor
required: false
schema:
description: Return the page of entries after this one.
type: string
x-documentation-priority: low
- in: query
name: limit
required: false
schema:
description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
minimum: 1
type: integer
x-documentation-priority: low
- example: account_in71c4amph0vgo2qllky
in: query
name: account_id
required: false
schema:
description: Filter Card Validations to ones belonging to the specified Account.
type: string
x-documentation-priority: default
x-id-reference-to: Accounts
- in: query
name: created_at.after
required: false
schema:
description: Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.before
required: false
schema:
description: Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_after
required: false
schema:
description: Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_before
required: false
schema:
description: Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: status.in
required: false
schema:
description: Filter Card Validations by status. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
items:
enum:
- requires_attention
- pending_submission
- submitted
- complete
- declined
type: string
x-enum-descriptions:
- The validation requires attention from an Increase operator.
- The validation is queued to be submitted to the card network.
- The validation has been submitted and is pending a response from the card network.
- The validation has been sent successfully and is complete.
- The validation was declined by the network or the recipient's bank.
type: array
x-documentation-priority: default
explode: false
- in: query
name: idempotency_key
required: false
schema:
description: Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).
maxLength: 200
minLength: 1
type: string
x-documentation-priority: default
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_validation_list'
description: Card Validation List
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: List Card Validations
x-sandbox-only: false
x-tag: Card Validations
tags:
- Card Validations
post:
operationId: create_a_card_validation
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_a_card_validation_parameters'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_validation'
description: Card Validation
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Create a Card Validation
x-sandbox-only: false
x-tag: Card Validations
tags:
- Card Validations
/card_validations/{card_validation_id}:
get:
operationId: retrieve_a_card_validation
parameters:
- example: outbound_card_validation_qqlzagpc6v1x2gcdhe24
in: path
name: card_validation_id
required: true
schema:
description: The identifier of the Card Validation.
type: string
x-documentation-priority: default
x-id-reference-to: Card Validations
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_validation'
description: Card Validation
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Retrieve a Card Validation
x-sandbox-only: false
x-tag: Card Validations
tags:
- Card Validations
components:
schemas:
error:
anyOf:
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 404
type: integer
title:
type: string
type:
enum:
- api_method_not_found_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 403
type: integer
title:
type: string
type:
enum:
- environment_mismatch_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
resource_id:
description: ''
type: string
x-documentation-priority: default
status:
enum:
- 409
type: integer
title:
type: string
type:
enum:
- idempotency_key_already_used_error
type: string
required:
- type
- title
- detail
- status
- resource_id
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 403
type: integer
title:
type: string
type:
enum:
- insufficient_permissions_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 500
type: integer
title:
type: string
type:
enum:
- internal_server_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
reason:
description: ''
enum:
- deleted_credential
- expired_credential
- ip_not_allowed
- no_credential
- no_header
- no_api_access
- wrong_environment
type: string
x-documentation-priority: default
x-enum-descriptions:
- deleted_credential
- expired_credential
- ip_not_allowed
- no_credential
- no_header
- no_api_access
- wrong_environment
status:
enum:
- 401
type: integer
title:
type: string
type:
enum:
- invalid_api_key_error
type: string
required:
- type
- title
- detail
- status
- reason
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 409
type: integer
title:
type: string
type:
enum:
- invalid_operation_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
errors:
description: All errors related to parsing the request parameters.
items:
additionalProperties: true
properties: {}
title: ErrorsElement
type: object
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: ErrorsElements
type: array
x-documentation-priority: default
status:
enum:
- 400
type: integer
title:
type: string
type:
enum:
- invalid_parameters_error
type: string
required:
- type
- title
- detail
- status
- errors
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 400
type: integer
title:
type: string
type:
enum:
- malformed_request_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 404
type: integer
title:
type: string
type:
enum:
- object_not_found_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
status:
enum:
- 403
type: integer
title:
type: string
type:
enum:
- private_feature_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
- properties:
detail:
anyOf:
- type: string
- type: 'null'
retry_after:
anyOf:
- description: ''
type: integer
x-documentation-priority: default
- type: 'null'
status:
enum:
- 429
type: integer
title:
type: string
type:
enum:
- rate_limited_error
type: string
required:
- type
- title
- detail
- status
type: object
x-event-categories: []
card_validation:
additionalProperties: true
description: Card Validations are used to validate a card and its cardholder before sending funds to or pulling funds from a card.
example:
acceptance:
accepted_at: '2020-01-31T23:59:59Z'
authorization_identification_response: ABCDEF
card_verification_value2_result: null
cardholder_first_name_result: null
cardholder_full_name_result: null
cardholder_last_name_result: null
cardholder_middle_name_result: null
cardholder_postal_code_result: null
cardholder_street_address_result: null
network_transaction_identifier: '841488484271872'
account_id: account_in71c4amph0vgo2qllky
card_token_id: outbound_card_token_zlt0ml6youq3q7vcdlg0
cardholder_first_name: Dee
cardholder_last_name: Hock
cardholder_middle_name: Ward
cardholder_postal_code: '10045'
cardholder_street_address: 33 Liberty Street
created_at: '2020-01-31T23:59:59Z'
created_by:
category: user
user:
email: user@example.com
decline:
declined_at: '2020-01-31T23:59:59Z'
network_transaction_identifier: '841488484271872'
reason: transaction_not_permitted_to_cardholder
id: outbound_card_validation_qqlzagpc6v1x2gcdhe24
idempotency_key: null
merchant_category_code: '1234'
merchant_city_name: New York
merchant_name: Acme Corp
merchant_postal_code: '10045'
merchant_state: NY
route: visa
status: pending_submission
submission:
retrieval_reference_number: '123456789012'
submitted_at: '2020-01-31T23:59:59Z'
trace_number: '123456'
type: card_validation
properties:
acceptance:
anyOf:
- additionalProperties: false
description: If the validation is accepted by the recipient bank, this will contain supplemental details.
example:
accepted_at: '2020-01-31T23:59:59Z'
authorization_identification_response: ABCDEF
card_verification_value2_result: null
cardholder_first_name_result: null
cardholder_full_name_result: null
cardholder_last_name_result: null
cardholder_middle_name_result: null
cardholder_postal_code_result: null
cardholder_street_address_result: null
network_transaction_identifier: '841488484271872'
properties:
accepted_at:
description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was accepted by the issuing bank.
format: date-time
type: string
x-documentation-priority: default
authorization_identification_response:
description: The authorization identification response from the issuing bank.
type: string
x-documentation-priority: default
card_verification_value2_result:
anyOf:
- description: The result of the Card Verification Value 2 match.
enum:
- match
- no_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The Card Verification Value 2 (CVV2) matches the expected value.
- The Card Verification Value 2 (CVV2) does not match the expected value.
- type: 'null'
cardholder_first_name_result:
anyOf:
- description: The result of the cardholder first name match.
enum:
- match
- no_match
- partial_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder name component matches the expected value.
- The cardholder name component does not match the expected value.
- The cardholder name component partially matches the expected value.
- type: 'null'
cardholder_full_name_result:
anyOf:
- description: The result of the cardholder full name match.
enum:
- match
- no_match
- partial_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder name component matches the expected value.
- The cardholder name component does not match the expected value.
- The cardholder name component partially matches the expected value.
- type: 'null'
cardholder_last_name_result:
anyOf:
- description: The result of the cardholder last name match.
enum:
- match
- no_match
- partial_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder name component matches the expected value.
- The cardholder name component does not match the expected value.
- The cardholder name component partially matches the expected value.
- type: 'null'
cardholder_middle_name_result:
anyOf:
- description: The result of the cardholder middle name match.
enum:
- match
- no_match
- partial_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder name component matches the expected value.
- The cardholder name component does not match the expected value.
- The cardholder name component partially matches the expected value.
- type: 'null'
cardholder_postal_code_result:
anyOf:
- description: The result of the cardholder postal code match.
enum:
- match
- no_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder address component matches the expected value.
- The cardholder address component does not match the expected value.
- type: 'null'
cardholder_street_address_result:
anyOf:
- description: The result of the cardholder street address match.
enum:
- match
- no_match
type: string
x-documentation-priority: default
x-enum-descriptions:
- The cardholder address component matches the expected value.
- The cardholder address component does not match the expected value.
- type: 'null'
network_transaction_identifier:
anyOf:
- description: A unique identifier for the transaction on the card network.
type: string
x-documentation-priority: default
- type: 'null'
required:
- accepted_at
- authorization_identification_response
- network_transaction_identifier
- cardholder_full_name_result
- cardholder_first_name_result
- cardholder_middle_name_result
- cardholder_last_name_result
- cardholder_street_address_result
- cardholder_postal_code_result
- card_verification_value2_result
title: Card Validation Card Validation Acceptance
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Card Validation Acceptances
- type: 'null'
account_id:
description: The identifier of the Account from which to send the validation.
type: string
x-documentation-priority: default
x-id-reference-to: Accounts
card_token_id:
description: The ID of the Card Token that was used to validate the card.
type: string
x-documentation-priority: default
x-id-reference-to: Card Tokens
cardholder_first_name:
anyOf:
- description: The cardholder's first name.
type: string
x-documentation-priority: default
- type: 'null'
cardholder_last_name:
anyOf:
- description: The cardholder's last name.
type: string
x-documentation-priority: default
- type: 'null'
cardholder_middle_name:
anyOf:
- description: The cardholder's middle name.
type: string
x-documentation-priority: default
- type: 'null'
cardholder_postal_code:
anyOf:
- description: The postal code of the cardholder's address.
type: string
x-documentation-priority: default
- type: 'null'
cardholder_street_address:
anyOf:
- description: The cardholder's street address.
type: string
x-documentation-priority: default
- type: 'null'
created_at:
description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was created.
format: date-time
type: string
x-documentation-priority: default
created_by:
anyOf:
- additionalProperties: false
description: What object created the validation, either via the API or the dashboard.
example:
category: user
user:
email: user@example.com
properties:
api_key:
anyOf:
- additionalProperties: false
description: If present, details about the API key that created the transfer.
properties:
description:
anyOf:
- description: The description set for the API key when it was created.
type: string
x-documentation-priority: default
- type: 'null'
required:
- description
title: Card Validation Transfer Creator ApiKey
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: ApiKeys
- type: 'null'
category:
description: The type of object that created this transfer.
enum:
- api_key
- oauth_application
- user
type: string
x-documentation-priority: default
x-enum-descriptions:
- An API key. Details will be under the `api_key` object.
- An OAuth application you connected to Increase. Details will be under the `oauth_application` object.
- A User in the Increase dashboard. Details will be under the `user` object.
oauth_application:
anyOf:
- additionalProperties: false
description: If present, details about the OAuth Application that created the transfer.
properties:
name:
description: The name of the OAuth Application.
type: string
x-documentation-priority: default
required:
- name
title: Card Validation Transfer Creator OAuthApplication
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: OAuthApplications
- type: 'null'
user:
anyOf:
- additionalProperties: false
description: If present, details about the User that created the transfer.
properties:
email:
description: The email address of the User.
type: string
x-documentation-priority: default
required:
- email
title: Card Validation Transfer Creator User
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Users
- type: 'null'
required:
- category
title: Card Validation Transfer Creator
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Transfer Creators
- type: 'null'
decline:
anyOf:
- additionalProperties: false
description: If the validation is rejected by the card network or the destination financial institution, this will contain supplemental details.
example:
declined_at: '2020-01-31T23:59:59Z'
network_transaction_identifier: '841488484271872'
reason: transaction_not_permitted_to_cardholder
properties:
declined_at:
description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was declined.
format: date-time
type: string
x-documentation-priority: default
network_transaction_identifier:
anyOf:
- description: A unique identifier for the transaction on the card network.
type: string
x-documentation-priority: default
- type: 'null'
reason:
description: The reason why the validation was declined.
enum:
- do_not_honor
- activity_count_limit_exceeded
- refer_to_card_issuer
- refer_to_card_issuer_special_condition
- invalid_merchant
- pick_up_card
- error
- pick_up_card_special
- invalid_transaction
- invalid_amount
- invalid_account_number
- no_such_issuer
- re_enter_transaction
- no_credit_account
- pick_up_card_lost
- pick_up_card_stolen
- closed_account
- insufficient_funds
- no_checking_account
- no_savings_account
- expired_card
- transaction_not_permitted_to_cardholder
- transaction_not_allowed_at_terminal
- transaction_not_supported_or_blocked_by_issuer
- suspected_fraud
- activity_amount_limit_exceeded
- restricted_card
- security_violation
- transaction_does_not_fulfill_anti_money_laundering_requirement
- blocked_by_cardholder
- blocked_first_use
- credit_issuer_unavailable
- negative_card_verification_value_results
- issuer_unavailable
- financial_institution_cannot_be_found
- transaction_cannot_be_completed
- duplicate_transaction
- system_malfunction
- additional_customer_authentication_required
- surcharge_amount_not_permitted
- decline_for_cvv2_failure
- stop_payment_order
- revocation_of_authorization_order
- revocation_of_all_authorizations_order
- unable_to_locate_record
- file_is_temporarily_unavailable
- incorrect_pin
- allowable_number_of_pin_entry_tries_exceeded
- unable_to_locate_previous_message
- pin_error_found
- cannot_verify_pin
- verification_data_failed
- surcharge_amount_not_supported_by_debit_network_issuer
- cash_service_not_available
- cashback_request_exceeds_issuer_limit
- transaction_amount_exceeds_pre_authorized_approval_amount
- transaction_does_not_qualify_for_visa_pin
- offline_declined
- unable_to_go_online
- valid_account_but_amount_not_supported
- invalid_use_of_merchant_category_code_correct_and_reattempt
- card_authentication_failed
type: string
x-documentation-priority: default
x-enum-descriptions:
- The card issuer has declined the transaction without providing a specific reason.
- The number of transactions for the card has exceeded the limit set by the issuer.
- The card issuer requires the cardholder to contact them for further information regarding the transaction.
- The card issuer requires the cardholder to contact them due to a special condition related to the transaction.
- The merchant is not valid for this transaction.
- The card should be retained by the terminal.
- An error occurred during processing of the transaction.
- The card should be retained by the terminal due to a special condition.
- The transaction is invalid and cannot be processed.
- The amount of the transaction is invalid.
- The account number provided is invalid.
- The issuer of the card could not be found.
- The transaction should be re-entered for processing.
- There is no credit account associated with the card.
- The card should be retained by the terminal because it has been reported lost.
- The card should be retained by the terminal
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/increase/refs/heads/main/openapi/increase-card-validations-api-openapi.yml