Card Verification

Merchant can use a verification service to check whether a customer’s card is valid and available for purchases. Funds on cardholder’s account are not debited during verification. Funds can be debited only when one of condigtons is met:

• the client confirms recurring payments;
• the client initiates payment transaction for the total amount.

Verification service can be used only with partner form payment. If card verification is passed successfully, a card payment token can be issued for the card.

By default, access to the verification service is disabled. Contact your designated support manager to enable it.

Usage scenario

1. Send card verification API request. Put in the request:
2. Unique verification identifier (requestUid field in the request URL).
3. Card data (cardData in the request body). Required parameters — PAN, card expiration date, and CVV2.

!!! info “” For payment token generation, set tokenizationData.account parameter to unique customer’s identifier in the merchant’s system.

1. Process the server response:
   • the card verification result returns in isValidCard field (true means the card can be charged);
   • the payment token is returned in createdToken object if isValidCard=true and tokenizationData.account was sent in the request.

To make sure that the cardholder themselves entered card number, 3D-Secure (3DS) is used. 3DS is enabled or disabled by the bank that issued the card. If 3DS is enabled, the response to the cerd verification request will contain:

• requirements object with ACS URL for customer redirect;
• WAITING_3DS in the status field.

3DS scenario during card verification is similar to 3DS with payment operation:

1. Redirect customer to the authentication page.
2. Finish 3DS by sending a request to complete 3DS on card verification. Specify the same requestUid from the initial card verification request.
3. If 3DS is finished successfully, isValidCard field contains information about card validity (true means card can be charged). When isValidCard=true and payment token issue requested in the original request, a JSON object createdToken is returned with payment token data.

When verification finishes, the result will be sent in a notification with CHECK_CARD type. If necessary, the current status can be requested separately.

Examples

Request with card verificationSuccessful response body for a card without 3DS authenticationResponse with 3DS authenticationRedirecting for 3DS authenticationResponse with verification errorRequest to finish 3DS in card verificationResponse to the request to finish 3DS

PUT /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
    "cardData": {
        "pan": "1111222233334444",
        "expiryDate": "12/34",
        "cvv2": "123",
        "holderName": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2025-03-25T12:55:12+03:00",
    "cardInfo": {
      "issuingCountry": "643",
      "issuingBank": "Gazprombank",
      "paymentSystem": "MIR",
      "fundingSource": "DEBIT",
      "paymentSystemProduct": "details"
    },
    "createdToken": {
      "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
      "name": "111122******4444",
      "expiredDate": "2034-12-31T00:00:00+03:00",
      "account": "cat_girl"
    }
}

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "WAITING_3DS",
    "requirements": {
        "pareq": "Some string pareq",
        "acsUrl": "http://xxxxxxx"
    }
}

<form name="form" action="{ACSUrl}" method="post" >
    <input type="hidden" name="TermUrl" value="{TermUrl}" >
    <input type="hidden" name="MD" value="{MD}" >
    <input type="hidden" name="PaReq" value="{PaReq}" >
</form>

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "ERROR"
}

POST /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
    "pares": "Some string pares"
}

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2025-03-25T12:55:12+03:00",
    "cardInfo": {
      "issuingCountry": "643",
      "issuingBank": "Gazprombank",
      "paymentSystem": "MIR",
      "fundingSource": "DEBIT",
      "paymentSystemProduct": "details"
    },
    "createdToken": {
      "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
      "name": "111122******4444",
      "expiredDate": "2034-12-31T00:00:00+03:00",
      "account": "cat_girl"
    }
}

Request and response are provided as an example: for the current format and list of parameters, refer to the API documentation.