Payment instrument verification

General information

Payment Page allows validating customer payment instrument before using in for processing payments, for instance, for performing payouts to customers. This section covers information about performing payment instrument verification by using Payment Page and extends the information in the Payment models and statuses section.

Payment instrument verification is a payment type in which the customer card or account is validated by either transferring a dummy (zero) amount from customer to merchant or by authorizing a specific amount (non-zero) on the customer card or account and then voiding the transfer or the authorization. Authorization amount can be changed on merchant's request. The authorized amount can be held up to 45 days.

This option may be convenient for validating payment instrument without performing instant withdrawal of funds (in cases when free trial period is needed), for instance, before performing payouts to customers or when registering subscriptions (for more information about COF purchase registration, see COF purchase registration). For performing payment instrument verification, including saving payment information, the Card Verify operation mode of the payment form is used.

Restriction:

Coordinate with your ECommPay Key Account Manager the possibility of using payment instrument verification.

In terms of performing payment instrument verification using Payment Page, the basic steps that the customer performs may be specifying payment information, saving the payment information for subsequent payments processing and waiting for notification about the result.



Workflow

Payment instrument verification by using Payment Page requires the merchant web service to do the following:

  1. Create and send a request for opening Payment Page to the payment platform.
  2. Receive callback with the result of the request processing from the payment platform.

Payment instrument verification may involve auxiliary procedures:

  • 3‑D Secure authentication, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed (while issuer confirms authentication with no customer effort required).
  • Submission of additional payment information, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when performing payment cards verification.

Request format

The format of the request for opening Payment Page to perform payment instrument verification is the same as the request format described in the Payment Page API Description section. When creating request, you should consider the following:

  1. The request body must contain the following and parameters:
    • mode—the indicator of the Payment Page operation mode. The value must be card_verify.
    • project_id — the project ID obtained from ECommPay.
    • payment_id—the payment ID unique within the project.
    • payment_amount—payment amount in minor currency units, the 0 value must be specified.
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format.
    • signature—the signature that is created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  2. In order to register COF purchase, you need to additionally specify in the request the recurring parameter which contains information about COF purchase registration. The value of this parameter is obtained by converting the data into a single string by using the Base64 algorithm. For more information, see COF purchase registration.
  3. To save payment instrument details, you need to additionally specify in the request the customer_id parameter and the customer ID in merchant's web service as its value.
  4. To perform verification on the instrument token, specify in the request the account_token parameter—the token received from ECommPay.
  5. To display Payment Page in a required language, you need to additionally specify in the request the language_code parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified in the request, Payment Page is displayed either in English (for all countries except for Russia) or in Russian (for Russia), according to IP address of the customer.
  6. To add description of the payment, you need to specify in the request the payment_description parameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard (Dashboard Light) and in a callback with information about the payment result.
  7. If needed, you can also add any other additional parameters supported by Payment Page in the Card Verify operation mode. The full list of parameters for opening Payment Page is provided in the Payment Page invocation parameters section.

Thus, a correct request for payment instrument verification must include Payment Page operation mode indicator, project and payment IDs, signature, payment currency and amount. In order to save the payment information, you also need to specify customer_id, and in order to register COF purchase, you also need to specify a string which contains set of corresponding parameters.

{
   "mode": "card_verify",
   "project_id": "874",
   "payment_id": "15538406111",
   "payment_currency": "EUR",
   "payment_amount": "0",
   "signature": "TSzdE5rJpfXriFf82MxF..."

// saving payment information:
    "customer_id": "customer_10"

// verification by card token:
   "account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021"

// registering COF purchase:
   "recurring": {
        "register": "true",
        "type": "R",
        ...
   }

}

Figure: Example of the request for opening Payment Page

https://paymentpage.ecommpay.com/payment?payment_currency=EUR&language_code=ru&mode=card_verify&project_id=874&payment_amount=0&payment_id=15538406111&css_modal_wrap=standart&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...

Callback format

To notify the merchant about the result of payment instrument verification, the standard callback format is used. For more information, see Callbacks.

The following is an example of a callback with information about successful verification of the card with the card number 431422******0056 of the customer customer_10 and successful registration of the card for subsequent COF purchases.

Figure: Example of a callback which contains information about card verification result

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"success",
    "date":"2020-06-10T13:45:59+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"431422******0056",
    "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":8861226,
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "recurring":{
    "register":"true",
    "type":"R"
  },
  "operation":{
    "id":42209000002431,
    "type":"account verification",
    "status":"success",
    "date":"2020-06-10T13:45:59+0000",
    "created_date":"2020-06-10T13:45:57+0000",
    "request_id":"5cb898347e62b2c1-52dac6c8c",
    "sum_initial":{
      "amount":0,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "provider":{
      "id":120,
      "payment_id":"306449667",
      "date":"2020-06-10T13:45:59+0000",
      "auth_code":"188591",
      "endpoint_id":120
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"P9g0U+eF2QWs2A..."
}

The following is an example of a callback with information about declined payment instrument verification with no decline reason specified.

Figure: Example of declined payment card verification callback

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"decline",
    "date":"2020-06-16T06:06:53+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"EUR"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"09",
    "expiry_year":"2021"
  },
  "customer":{
    "id":"customer_10"
  },
  "operation":{
    "id":40975000002863,
    "type":"account verification",
    "status":"decline",
    "date":"2020-06-16T06:06:53+0000",
    "created_date":"2020-06-16T06:06:47+0000",
    "request_id":"9120271eb02-83e0e70fc0a0a3c1b4d",
    "sum_initial":{
      "amount":0,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":0,
      "currency":"EUR"
    },
    "provider":{
      "id":120,
      "payment_id":"308822001",
      "date":"2020-06-16T06:06:49+0000",
      "auth_code":"",
      "endpoint_id":120
    },
    "code":"10100",
    "message":"Declined by external provider"
  },
  "signature":"P9g0U+eaZ9EeNiWiaQWs2A..."
}