Card Validations

Card Validations are used to validate a card and its cardholder before sending funds to or pulling funds from a card.

Events

Your application can listen to webhooks about this resource. The events about Card Validations will have the categories "card_validation.created" or "card_validation.updated" .

The Card Validation object

{
  "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"
}

Attributes

acceptance

dictionary

Nullable

If the validation is accepted by the recipient bank, this will contain supplemental details.

account_id

string

The identifier of the Account from which to send the validation.

More about Accounts.

card_token_id

string

The ID of the Card Token that was used to validate the card.

More about Card Tokens.

cardholder_first_name

string

Nullable

The cardholder’s first name.

cardholder_last_name

string

Nullable

The cardholder’s last name.

cardholder_middle_name

string

Nullable

The cardholder’s middle name.

cardholder_postal_code

string

Nullable

The postal code of the cardholder’s address.

cardholder_street_address

string

Nullable

The cardholder’s street address.

created_at

string

The ISO 8601 date and time at which the validation was created.

created_by

dictionary

Nullable

What object created the validation, either via the API or the dashboard.

decline

dictionary

Nullable

If the validation is rejected by the card network or the destination financial institution, this will contain supplemental details.

string

The Card Validation’s identifier.

idempotency_key

string

Nullable

The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

merchant_category_code

string

A four-digit code (MCC) identifying the type of business or service provided by the merchant.

merchant_city_name

string

The city where the merchant (typically your business) is located.

merchant_name

string

The merchant name that will appear in the cardholder’s statement descriptor. Typically your business name.

merchant_postal_code

string

The postal code for the merchant’s (typically your business’s) location.

merchant_state

string

The U.S. state where the merchant (typically your business) is located.

route

enum

The card network route used for the validation.

status

enum

The lifecycle status of the validation.

submission

dictionary

Nullable

After the validation is submitted to the card network, this will contain supplemental details.

type

string

A constant representing the object’s type. For this resource it will always be card_validation.

List Card Validations

curl \
  --url "${INCREASE_URL}/card_validations?account_id=account_in71c4amph0vgo2qllky" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

Returns a list response :

{
  "data": [
    { /* Card Validation object */ },
    { /* Card Validation object */ }
    /* ... */
  ],
  "next_cursor": "v57w5d",
}

Parameters

account_id

string

Filter Card Validations to ones belonging to the specified Account.

More about Accounts.

status.in

array of strings

Filter Card Validations by status. For GET requests, this should be encoded as a comma-delimited string, such as ?in=one,two,three.

idempotency_key

string

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.

Between 1 and 200 characters

cursor

string

limit

integer

created_at.after

string

created_at.before

string

created_at.on_or_after

string

created_at.on_or_before

string

Create a Card Validation

curl -X "POST" \
  --url "${INCREASE_URL}/card_validations" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "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",
    "merchant_category_code": "1234",
    "merchant_city_name": "New York",
    "merchant_name": "Acme Corp",
    "merchant_postal_code": "10045",
    "merchant_state": "NY"
  }'

Parameters

account_id

string

Required

The identifier of the Account from which to send the validation.

More about Accounts.

card_token_id

string

Required

The Increase identifier for the Card Token that represents the card number you’re validating.

More about Card Tokens.

cardholder_first_name

string

The cardholder’s first name.

Between 1 and 35 characters,

cardholder_last_name

string

The cardholder’s last name.

Between 1 and 35 characters,

cardholder_middle_name

string

The cardholder’s middle name.

Between 1 and 35 characters,

cardholder_postal_code

string

The postal code of the cardholder’s address.

Between 1 and 9 characters,

cardholder_street_address

string

The cardholder’s street address.

Between 1 and 40 characters,

merchant_category_code

string

Required

A four-digit code (MCC) identifying the type of business or service provided by the merchant.

Exactly 4 characters,

merchant_city_name

string

Required

The city where the merchant (typically your business) is located.

Between 1 and 13 characters,

merchant_name

string

Required

The merchant name that will appear in the cardholder’s statement descriptor. Typically your business name.

Between 1 and 25 characters,

merchant_postal_code

string

Required

The postal code for the merchant’s (typically your business’s) location.

Between 1 and 10 characters,

merchant_state

string

Required

The U.S. state where the merchant (typically your business) is located.

Between 1 and 200 characters

Retrieve a Card Validation

curl \
  --url "${INCREASE_URL}/card_validations/outbound_card_validation_qqlzagpc6v1x2gcdhe24" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

Parameters

card_validation_id

string

Required

The identifier of the Card Validation.

More about Card Validations.