# Card Validations > Card Validations are used to validate a card and its cardholder before sending funds to or pulling funds from a card. [Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `card_validation.created` and `card_validation.updated`. ## The Card Validation object ### Example ```json { "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. - `acceptance.accepted_at` (string) The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was accepted by the issuing bank. - `acceptance.authorization_identification_response` (string) The authorization identification response from the issuing bank. - `acceptance.card_verification_value2_result` (enum, nullable) The result of the Card Verification Value 2 match. Cases: * `match` (The Card Verification Value 2 (CVV2) matches the expected value.) * `no_match` (The Card Verification Value 2 (CVV2) does not match the expected value.) - `acceptance.cardholder_first_name_result` (enum, nullable) The result of the cardholder first name match. Cases: * `match` (The cardholder name component matches the expected value.) * `no_match` (The cardholder name component does not match the expected value.) * `partial_match` (The cardholder name component partially matches the expected value.) - `acceptance.cardholder_full_name_result` (enum, nullable) The result of the cardholder full name match. Cases: * `match` (The cardholder name component matches the expected value.) * `no_match` (The cardholder name component does not match the expected value.) * `partial_match` (The cardholder name component partially matches the expected value.) - `acceptance.cardholder_last_name_result` (enum, nullable) The result of the cardholder last name match. Cases: * `match` (The cardholder name component matches the expected value.) * `no_match` (The cardholder name component does not match the expected value.) * `partial_match` (The cardholder name component partially matches the expected value.) - `acceptance.cardholder_middle_name_result` (enum, nullable) The result of the cardholder middle name match. Cases: * `match` (The cardholder name component matches the expected value.) * `no_match` (The cardholder name component does not match the expected value.) * `partial_match` (The cardholder name component partially matches the expected value.) - `acceptance.cardholder_postal_code_result` (enum, nullable) The result of the cardholder postal code match. Cases: * `match` (The cardholder address component matches the expected value.) * `no_match` (The cardholder address component does not match the expected value.) - `acceptance.cardholder_street_address_result` (enum, nullable) The result of the cardholder street address match. Cases: * `match` (The cardholder address component matches the expected value.) * `no_match` (The cardholder address component does not match the expected value.) - `acceptance.network_transaction_identifier` (string, nullable) A unique identifier for the transaction on the card network. - `account_id` (string) The identifier of the Account from which to send the validation. - `card_token_id` (string) The ID of the Card Token that was used to validate the card. - `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](https://en.wikipedia.org/wiki/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. - `created_by.api_key` (dictionary, nullable) If present, details about the API key that created the transfer. - `created_by.api_key.description` (string, nullable) The description set for the API key when it was created. - `created_by.category` (enum) The type of object that created this transfer. Cases: * `api_key` (An API key. Details will be under the `api_key` object.) * `oauth_application` (An OAuth application you connected to Increase. Details will be under the `oauth_application` object.) * `user` (A User in the Increase dashboard. Details will be under the `user` object.) - `created_by.oauth_application` (dictionary, nullable) If present, details about the OAuth Application that created the transfer. - `created_by.oauth_application.name` (string) The name of the OAuth Application. - `created_by.user` (dictionary, nullable) If present, details about the User that created the transfer. - `created_by.user.email` (string) The email address of the User. - `decline` (dictionary, nullable) If the validation is rejected by the card network or the destination financial institution, this will contain supplemental details. - `decline.declined_at` (string) The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was declined. - `decline.network_transaction_identifier` (string, nullable) A unique identifier for the transaction on the card network. - `decline.reason` (enum) The reason why the validation was declined. Cases: * `do_not_honor` (The card issuer has declined the transaction without providing a specific reason.) * `activity_count_limit_exceeded` (The number of transactions for the card has exceeded the limit set by the issuer.) * `refer_to_card_issuer` (The card issuer requires the cardholder to contact them for further information regarding the transaction.) * `refer_to_card_issuer_special_condition` (The card issuer requires the cardholder to contact them due to a special condition related to the transaction.) * `invalid_merchant` (The merchant is not valid for this transaction.) * `pick_up_card` (The card should be retained by the terminal.) * `error` (An error occurred during processing of the transaction.) * `pick_up_card_special` (The card should be retained by the terminal due to a special condition.) * `invalid_transaction` (The transaction is invalid and cannot be processed.) * `invalid_amount` (The amount of the transaction is invalid.) * `invalid_account_number` (The account number provided is invalid.) * `no_such_issuer` (The issuer of the card could not be found.) * `re_enter_transaction` (The transaction should be re-entered for processing.) * `no_credit_account` (There is no credit account associated with the card.) * `pick_up_card_lost` (The card should be retained by the terminal because it has been reported lost.) * `pick_up_card_stolen` (The card should be retained by the terminal because it has been reported stolen.) * `closed_account` (The account associated with the card has been closed.) * `insufficient_funds` (There are insufficient funds in the account to complete the transaction.) * `no_checking_account` (There is no checking account associated with the card.) * `no_savings_account` (There is no savings account associated with the card.) * `expired_card` (The card has expired and cannot be used for transactions.) * `transaction_not_permitted_to_cardholder` (The transaction is not permitted for this cardholder.) * `transaction_not_allowed_at_terminal` (The transaction is not allowed at this terminal.) * `transaction_not_supported_or_blocked_by_issuer` (The transaction is not supported or has been blocked by the issuer.) * `suspected_fraud` (The transaction has been flagged as suspected fraud and cannot be processed.) * `activity_amount_limit_exceeded` (The amount of activity on the card has exceeded the limit set by the issuer.) * `restricted_card` (The card has restrictions that prevent it from being used for this transaction.) * `security_violation` (A security violation has occurred, preventing the transaction from being processed.) * `transaction_does_not_fulfill_anti_money_laundering_requirement` (The transaction does not meet the anti-money laundering requirements set by the issuer.) * `blocked_by_cardholder` (The transaction was blocked by the cardholder.) * `blocked_first_use` (The first use of the card has been blocked by the issuer.) * `credit_issuer_unavailable` (The credit issuer is currently unavailable to process the transaction.) * `negative_card_verification_value_results` (The card verification value (CVV) results were negative, indicating a potential issue with the card.) * `issuer_unavailable` (The issuer of the card is currently unavailable to process the transaction.) * `financial_institution_cannot_be_found` (The financial institution associated with the card could not be found.) * `transaction_cannot_be_completed` (The transaction cannot be completed due to an unspecified reason.) * `duplicate_transaction` (The transaction is a duplicate of a previous transaction and cannot be processed again.) * `system_malfunction` (A system malfunction occurred, preventing the transaction from being processed.) * `additional_customer_authentication_required` (Additional customer authentication is required to complete the transaction.) * `surcharge_amount_not_permitted` (The surcharge amount applied to the transaction is not permitted by the issuer.) * `decline_for_cvv2_failure` (The transaction was declined due to a failure in verifying the CVV2 code.) * `stop_payment_order` (A stop payment order has been placed on this transaction.) * `revocation_of_authorization_order` (An order has been placed to revoke authorization for this transaction.) * `revocation_of_all_authorizations_order` (An order has been placed to revoke all authorizations for this cardholder.) * `unable_to_locate_record` (The record associated with the transaction could not be located.) * `file_is_temporarily_unavailable` (The file needed for the transaction is temporarily unavailable.) * `incorrect_pin` (The PIN entered for the transaction is incorrect.) * `allowable_number_of_pin_entry_tries_exceeded` (The allowable number of PIN entry tries has been exceeded.) * `unable_to_locate_previous_message` (The previous message associated with the transaction could not be located.) * `pin_error_found` (An error was found with the PIN associated with the transaction.) * `cannot_verify_pin` (The PIN associated with the transaction could not be verified.) * `verification_data_failed` (The verification data associated with the transaction has failed.) * `surcharge_amount_not_supported_by_debit_network_issuer` (The surcharge amount is not supported by the debit network issuer.) * `cash_service_not_available` (Cash service is not available for this transaction.) * `cashback_request_exceeds_issuer_limit` (The cashback request exceeds the issuer limit.) * `transaction_amount_exceeds_pre_authorized_approval_amount` (The transaction amount exceeds the pre-authorized approval amount.) * `transaction_does_not_qualify_for_visa_pin` (The transaction does not qualify for Visa PIN processing.) * `offline_declined` (The transaction was declined offline.) * `unable_to_go_online` (The terminal was unable to go online to process the transaction.) * `valid_account_but_amount_not_supported` (The account is valid but the transaction amount is not supported.) * `invalid_use_of_merchant_category_code_correct_and_reattempt` (The merchant category code was used incorrectly; correct it and reattempt the transaction.) * `card_authentication_failed` (The card authentication process has failed.) - `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](https://increase.com/documentation/idempotency-keys). - `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. Cases: * `visa` (Visa and Interlink) * `mastercard` (Mastercard and Maestro) - `status` (enum) The lifecycle status of the validation. Cases: * `requires_attention` (The validation requires attention from an Increase operator.) * `pending_submission` (The validation is queued to be submitted to the card network.) * `submitted` (The validation has been submitted and is pending a response from the card network.) * `complete` (The validation has been sent successfully and is complete.) * `declined` (The validation was declined by the network or the recipient's bank.) - `submission` (dictionary, nullable) After the validation is submitted to the card network, this will contain supplemental details. - `submission.retrieval_reference_number` (string) A 12-digit retrieval reference number that identifies the validation. Usually a combination of a timestamp and the trace number. - `submission.submitted_at` (string) The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the validation was submitted to the card network. - `submission.trace_number` (string) A 6-digit trace number that identifies the validation within a short time window. - `type` (string) A constant representing the object's type. For this resource it will always be `card_validation`. ## List Card Validations GET /card_validations ### Example ```curl curl \ --url "${INCREASE_URL}/card_validations?account_id=account_in71c4amph0vgo2qllky" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" ``` ### Query Parameters - `cursor` (string, optional) Return the page of entries after this one. - `limit` (integer, optional) Limit the size of the list that is returned. The default (and maximum) is 100 objects. - `account_id` (string, optional) Filter Card Validations to ones belonging to the specified Account. - `created_at.after` (string, optional) Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp. - `created_at.before` (string, optional) Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp. - `created_at.on_or_after` (string, optional) Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp. - `created_at.on_or_before` (string, optional) Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp. - `status.in` (array of enums, optional) Filter Card Validations by status. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`. Cases: * `requires_attention` (The validation requires attention from an Increase operator.) * `pending_submission` (The validation is queued to be submitted to the card network.) * `submitted` (The validation has been submitted and is pending a response from the card network.) * `complete` (The validation has been sent successfully and is complete.) * `declined` (The validation was declined by the network or the recipient's bank.) - `idempotency_key` (string, optional) 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). ### Returns a Card Validation List object: ```json { "data": [ { "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" } ], "next_cursor": "v57w5d" } ``` ## Create a Card Validation POST /card_validations ### Example ```curl 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" }' ``` ### Body 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, optional) The cardholder's first name. - `cardholder_last_name` (string, optional) The cardholder's last name. - `cardholder_middle_name` (string, optional) The cardholder's middle name. - `cardholder_postal_code` (string, optional) The postal code of the cardholder's address. - `cardholder_street_address` (string, optional) The cardholder's street address. - `merchant_category_code` (string, required) A four-digit code (MCC) identifying the type of business or service provided by the merchant. - `merchant_city_name` (string, required) The city where the merchant (typically your business) is located. - `merchant_name` (string, required) The merchant name that will appear in the cardholder’s statement descriptor. Typically your business name. - `merchant_postal_code` (string, required) The postal code for the merchant’s (typically your business’s) location. - `merchant_state` (string, required) The U.S. state where the merchant (typically your business) is located. ## Retrieve a Card Validation GET /card_validations/{card_validation_id} ### Example ```curl curl \ --url "${INCREASE_URL}/card_validations/outbound_card_validation_qqlzagpc6v1x2gcdhe24" \ -H "Authorization: Bearer ${INCREASE_API_KEY}" ``` ### Path Parameters - `card_validation_id` (string, required) The identifier of the Card Validation.