Skip to content

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:

Verification service can be used with partner form payment or QIWI 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.

API Usage scenario

  1. Send card verification API request. Put in the request:

    • Unique verification identifier (requestUid field in the request URL).
    • Card data (cardData in the request body). Required parameters — PAN, card expiration date, and CVV2.

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

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

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.

Payment Form Usage scenario

  1. Send invoice request with additional parameter "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]. For payment token generation, set customer.account parameter with unique customer identifier in the merchant’s system. Do not specify invoice amount in the request (amount parameter).
  2. Extract billId parameter from the response — it is used on step 4. Redirect customer to the Payment Form — reference URL taken from payUrl field of the response.
  3. On the Payment Form, customer provides card details and submits it for verification. On the form, 3-D Secure authentication performs for customer. check card
  4. When card verification finishes, you get CHECK_CARD notification with the result, or you can request current status of the verification — put there billId identifier from step 2 as a unique identifier of the card verification. Result includes:
    • information about whether card is accessible for purchases in isValidCard field (true — card can be charged);
    • payment token data in createdToken field: returned when payment token issue requested in step 1 and isValidCard=true.
DOCUMENTATION
DEVELOPERS
FEEDBACK
  • © 2024 QIWI