Skip to main content

Debit or Credit Card Verification

Introduction​

Embedded Wallet customers can verify a debit or credit card through a card deposit flow. After a card deposit is completed successfully, a 4-digit verification code is printed in the transaction description on the customer's card statement. The customer reads the code from the statement and provides it to complete the card verification.

Card verification is required when the card payment instrument is in VERIFICATION_REQUIRED status.

This process uses public API operations for:

  • Creating a deposit.
  • Retrieving the card verification information.
  • Verifying the card.
note

The examples below are illustrative and focus on the verification flow. Use the API reference for the full request and response schema.

Card Verification Service​

The card verification flow is part of the Embedded Wallet product and is designed to confirm card ownership before the card can be used further. The API provided to the merchant is focused on a deposit-first verification approach:

  • Create a deposit with a debit or credit card.
  • The customer finds the verification code in the transaction description on their card statement.
  • Verify the card by submitting the code through the verification endpoint.
warning

If a deposit above the limit threshold is made, an error indicating that the limit is exceeded will be returned. In that case you have to make at least one successful deposit below the limit threshold.

Card Verification Steps​

  1. The merchant's customer initiates a card deposit.
  2. Merchant creates the card deposit request.
  3. When the deposit is completed successfully, the transaction appears on the customer's card statement with a 4-digit verification code in its description. The merchant can retrieve the exact pattern of the statement description (e.g. Brand-XXXX, where XXXX is the verification code) using the Get Card Verification Information operation and display it to the customer.
GET Get Card Verification Information

Response

{
  "verificationPattern": "Brand-XXXX",
  "verificationType": "VERIFICATION_CODE"
}
  1. The customer reads the verification code from the card statement and enters it in the merchant's application.
  2. Merchant verifies the card by submitting the code to the Verify Card operation.
POST Verify Card

Request

{
  "instrumentId": "123456",
  "verificationCode": "1234",
  "verificationType": "VERIFICATION_CODE"
}

Response

{
  "id": "2cb56b2749af52d6b257054ef3de0",
  "instrumentId": "123456",
  "instrumentType": "CARD",
  "verificationCode": "1234",
  "verificationType": "VERIFICATION_CODE",
  "creationTime": "2021-07-15T17:54:12Z",
  "status": "COMPLETED",
  "remainingAttempts": 0
}
  1. Merchant handles the verification outcome in the wallet experience.

Verification Status and Outcome​

The Verify Card operation is synchronous and the outcome is returned in the response:

  • COMPLETED indicates that the card is verified successfully. The payment instrument status changes to VERIFIED.
  • FAILED indicates that verification did not succeed. The statusReason field contains the reason:
    • INVALID_CODE - the provided code does not match. The customer may retry while remainingAttempts is greater than zero.
    • VERIFICATION_NOT_REQUIRED - the card is not in VERIFICATION_REQUIRED status.
    • VERIFICATION_ATTEMPT_EXCEEDED - the maximum number of verification attempts for the card has been reached.
    • VERIFICATION_ATTEMPT_24H_EXCEEDED - the maximum number of verification attempts within 24 hours has been reached.

Previous verification attempts can be retrieved using the Get Card Verifications and Get Card Verification operations.

API Reference​