Docs
Guides
Explanatory and how-to content
API Reference
Technical documentation
Changelog
Release notes
Dashboard
Manage your account
Status
Service status
API Reference
Card Validations

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

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",
  "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",
  "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.

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.

id
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.

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}"
Parameters
cursor
string

Return the page of entries after this one.

limit
integer

Limit the size of the list that is returned. The default (and maximum) is 100 objects.

account_id
string

Filter Card Validations to ones belonging to the specified Account.

created_at.after
string

Return results after this ISO 8601 timestamp.

created_at.before
string

Return results before this ISO 8601 timestamp.

created_at.on_or_after
string

Return results on or after this ISO 8601 timestamp.

created_at.on_or_before
string

Return results on or before this ISO 8601 timestamp.

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.

200 character maximum
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.

card_token_id
string
Required

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

cardholder_first_name
string

The cardholder's first name.

35 character maximum
cardholder_last_name
string

The cardholder's last name.

35 character maximum
cardholder_middle_name
string

The cardholder's middle name.

35 character maximum
cardholder_postal_code
string

The postal code of the cardholder's address.

9 character maximum
cardholder_street_address
string

The cardholder's street address.

40 character maximum
merchant_category_code
string
Required

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

4 character maximum
merchant_city_name
string
Required

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

13 character maximum
merchant_name
string
Required

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

25 character maximum
merchant_postal_code
string
Required

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

10 character maximum
merchant_state
string
Required

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

200 character maximum
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.