Payment instrument verification

Tip: This article covers payment instrument verification via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of payment instrument verification:

  • Payment instrument verification—an article in the section Payment models and statuses that provides a general description of performing payment instrument verification in the ecommpay payment platform and covers information about statuses that can be used in the process.
  • articles of the Payment methods section containing a description of payment instrument verification via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

To find out whether you can use payment instrument verification, refer to your ecommpay account manager.

General information

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 a payment instrument without withdrawing funds instantly, for example, before performing a payout or when registering in a service that offers a free trial period followed by subsequent withdrawals of funds (for more information about such cases, see the article COF purchase registration).

For performing payment instrument verification on Payment Page, the Card Verify operation mode of the payment form is used. During the work with this mode, it is possible to specify card details the customers submitted via the means of communication (Mail Order / Telephone Order; MO/TO) and save the provided card details in the platform.

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 following required parameters must be used:
    • 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 a COF purchase, you need to additionally specify the recurring parameter with information about this COF purchase (for more information, see COF purchase registration).
  3. To save payment instrument details, you need to additionally specify 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 the account_token parameter—the token received from ecommpay.
  5. To display Payment Page in a required language, you need to additionally specify the language_code parameter. If this parameter is not specified, the payment form is displayed in the language selected automatically (by the browser language, by the region, or by default—learn more).
  6. To add description of the payment, you need to specify 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 and in a callback with information about the payment result.
  7. To specify card details submitted by customers via the means of communication, you must use the moto_type parameter with the value 1, for mail communication (Mail Order), or 2, for telephone communication (Telephone Order).
  8. 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 Parameters for opening payment form 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=en&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": "2025"
  },
  "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": "2025"
  },
  "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..."
}