Add Card Account

Response Codes

201 - Created, will include a Location response header

200 - Request Succeeded, but entity not created

400 - Bad Request, missing or invalid parameters

404 - Recipient ID not found

409 - Conflict, card number exists

422 - Cannot process due to business constraints or fraud controls

PCI Compliance

Implementation of the Card Account endpoints require PCI compliance. If you are unsure of the requirements around PCI compliance, please contact tech@interchecks.com to discuss implementation options.

Card Eligibility

Currently, only Visa and Mastercard Debit accounts are eligible for INSTANT_DEPOSIT or INSTANT_FUNDING transactions. Custom client configurations can support enabling or disabling Visa Credit cards or Prepaid Debit cards.

Card Account Uniqueness

If the recipient has an active card account matching the card number, a 409 will be returned with the original card account response body.

Card Account Error Codes

Error codes specific to Card Accounts.

Error Code	Details
ERR_TOKENIZING_CARD	Card tokenization failed upstream
ERR_RETRIEVING_CARD_DETAILS	Unable to retrieve card metadata from network providers (Visa/MC)
ERR_ACCOUNT_SHARING_LIMIT_EXCEEDED	Card account matches active accounts under other Recipient(s) - the limit is configured on a per client basis
ERR_BIN_BLOCKED	Card BIN is on the client's block list
ERR_ADDRESS_REQUIRED	Client is enabled for AFT Funding and address request fails field validation.
ERR_INVALID_ADDRESS_PARAMETERS	`address` is present but missing required fields or contains non-ASCII characters
ERR_INVALID_CARD_DETAILS	Card BIN invalid or network detail not available from Visa
ERR_INVALID_EXP_DATE	`exp_date` is in an invalid format or expired
ERR_CARD_INELIGIBLE	Card network does not participate in Instant Deposit or Funding services
ERR_CREDIT_CARD_NOT_SUPPORTED	Credit card block is enabled
ERR_PREPAID_CARD_NOT_SUPPORTED	Prepaid card block is enabled
ERR_CARD_PAV_ERROR	Card Account Verification was unable complete due to system error. These requests can be retried.
ERR_CARD_PAV_FAILURE	Card Account Verification workflow - Error raised when a full match is required. `INSTANT_FUNDING`(AFT) requires a verified account.
ERR_CARD_PAV_PAN_FAILURE	Card Account Verification workflow - PAN (primary account number) is invalid
ERR_CARD_PAV_CVV_FAILURE	Card Account Verification workflow - CVV / Expiration Date combination is invalid

Card Account Verification Requirements for Funding transactions

When configured for INSTANT_FUNDING(AFT) a card account request requires a full address for verification services. Only verified cards are eligible for funding transactions.

Card Account Verification

Verification services are available when adding a Card Account via API or Create Card Widget. Our onboarding team will configure the verification services utilized. Details on how to trigger error scenarios in the Test Sandbox are documented on the Test Data page in the Test Values for Card Account Verification section.

PAN (Primary account number) verification
- A PAN failure results in a 200 with error code ERR_CARD_PAV_PAN_FAILURE
CVV / Expiration Date verification
- If the client account is configured for CVV verification and a CVV code is passed into the API request, the CVV / Expiration Date verification will be invoked. Card Widgets will include a CVV field if the client is configured for CVV verification.
- A CVV / Expiration Date failure results in a 200with error code ERR_CARD_PAV_CVV_FAILURE
Address verification with street address and zip code (AVS)
- Address verification (AVS) uses the Recipient Address
Account name verification (currently supported with Visa cards only)
- Name verification uses the Recipient's name

Verification details are provided with the Card Account response body in the verification_result object. The verification_result is also included in the Payment Account Webhook.

Parameter	Possible Values	Result if no match (non-AFT use case)
network	VISA / MASTERCARD	N/A - Informational
pan	MATCH / NO_MATCH	Card not added, error code in response
cvv	MATCH / NO_MATCH / NOT_PROCESSED / NOT_SUPPORTED	Card not added, error code in response
avs.street	MATCH / NO_MATCH / NOT_PROCESSED / NOT_SUPPORTED	Card added, client can evaluate and delete account or allow account to remain active
avs.zip	MATCH / NO_MATCH / NOT_PROCESSED / NOT_SUPPORTED	Card added, client can evaluate and delete account or allow account to remain active
ani.first_name	MATCH / PARTIAL / NO_MATCH / NOT_PROCESSED / NOT_SUPPORTED	Card added, client can evaluate and delete account or allow account to remain active
ani.last_name	MATCH / PARTIAL / NO_MATCH / NOT_PROCESSED / NOT_SUPPORTED	Card added, client can evaluate and delete account or allow account to remain active

Clients enabled for AFT Funding will receive a verification_status for Add Card Account and Get Card Account endpoints. verification_status indicates if the account is eligible for AFT Funding.

Verification Result	Description
`VERIFIED`	Card information and address have been verified. Name verified when applicable.
`UNVERIFIED`	Account details have not been fully verified. A Verify Card Account process is required.
`FAILED`	Card information, address, or name failed verification. The card account will be ineligible for AFT Funding transactions, but can be used for OCT (`INSTANT_DEPOSIT`).

Request Example

curl --request POST \
     --url https://test.api.interchecks.io/api/v2/payer_id/accounts/recipient_id/cards \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Response Examples

{"status":"200","error":"Failed Creation"}
{"status":"200","error":"Verification Result for No Match"}
{"status":"201","message":"Result"}
{"status":"409","error":"Card Exists"}