Payment instrument verification

Notice: This article covers payment instrument verification via Gate 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 Gate 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.

Overview

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. The authorization amount can be changed on merchant's request. Normally, the authorized amount is released shortly after the operation, but in some instances the authorized amount can be held up to 45 days.

You can use verification to register any subscriptions without debiting funds for the first (trial) period or you can use it before perform a payout. For more information about COF purchases, see Credential-on-file (COF) purchases. Payment instrument verification functionality can also be relevant for processing MO/TO (Mail Order/Telephone Order) payments which imply that customers provide payment card details over the phone, by email, or other means of communication. For more information about MO/TO payments, see MO/TO payment processing.

The payment instrument verification workflow

To perform the payment instrument verification by using Gate the web service is required to do the following:

Send the request by using the POST (HTTP) method to the endpoint /v2/payment/{payment method}/account_verification[/token].
If necessary, complete the additional procedures:
- 3‑D Secure authentication. This authentication is intended to provide security to online payments with payment cards. For more information on the authentication workflow, as well as request and callback formats, see 3‑D Secure authentication.
- Additional payment information submission. This procedure is intended for cases, where the initial request did not contain the information necessary for any payment process stakeholders. For more information on this procedure, see Submission of additional payment information.
Receive the callback with verification results from the payment platform.

The following diagram outlines the basic case of verification workflow (without the completion of the additional procedure).

Figure 1. Payment instrument verification

A customer enters the payment instrument details on the web service side.
The web service sends the payment instrument verification request by using Gate to the payment platform.
The payment platform receives the verification request.
The payment platform performs the initial request processing that includes validation of the required parameters and signature.
The payment platform sends to the web service the response with request receipt confirmation and correctness check result.
The payment platform performs the internal payment request processing and sends it to the payment environment. If you process the payment card verification, the payment environment is a bank service. If you process the alternative payment instrument verification, one is the payment system service.
The payment instrument verification is processed.
The payment platform receives the verification result notification.
The payment platform sends the callback to the web service.

The sections that follow discuss in more details the request format and the parameters to be used in requests for payment card verification, as well as provide information about the format of callbacks the verification results. Information about possible statuses of this payment type can be found in the corresponding article.

Request format

There are several things you need to consider when using payment card verification requests:

Send the request by using POST (HTTP) method to one of the following endpoints:
- when performing verification by card number—/v2/payment/card/account_verification
- when performing verification by the token that is associated with payment card details—/v2/payment/card/account_verification/token
The following objects and parameters must be specified in the request:
- Object general—general request identification information:
  - project_id—the project ID obtained from ecommpay
  - payment_id—payment ID unique within the merchant project
  - signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
- Object customer—customer information:
  - ip_address—IP address
  - id—the ID of the customer within the merchant project
- Object payment—payment information:
  - amount—payment amount, the value is 0
  - currency—payment currency in the ISO-4217 alpha-3 format
The request must contain the following customer's payment card information:
- when passing complete card credentials—the following data in the card object:
  - pan—card number
  - year—year of expiration date
  - month—month of expiration date
  - card_holder—cardholder's first and last name (as indicated on the card)
  - cvv—card verification code (as indicated on the card). This parameter is not necessary for processing of MO/TO payments. For more information, see MO/TO payment processing.
- when passing the token—token received from ecommpay in the token parameter and the card verification code in the cvv parameter (this parameter is not necessary for processing of MO/TO payments. For more information, see MO/TO payment processing).
If required, you can also add any other additional parameters and objects Gate supports.

Note: The payment amount must be zero.

Thus, the correct payment card verification request must include project and payment IDs, signature, the customer's payment card details, the ID and IP-address of the customer, as shown in the following example:

Figure 2. Example of payment card verification request with registration of COF purchase

{
  "general":{
    "project_id":874,
    "payment_id":"15538406111",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"185.123.193.224",
    "id":"customer_10"
  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },

//when indicating complete card credentials:
  "card":{
    "pan":"4314220000000056",
    "year":2021,
    "month":9,
    "card_holder":"John Smith",
    "cvv":"123"
  },

//when indicating the token of a stored payment card:
  "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654",
  "cvv":"123"

//when COF payment registration is made:
  "recurring":{
    "register":true
  }
}

Callback format

The standard format for callbacks is used to deliver payout results. For more information, see Callbacks.

The following is the example of a callback with information about the successful verification of the 431422******0056 card of the customer customer_10 in the 874 project. The card is verified and is registered for COF purchases.

Figure 3. Example of a callback which contains card verification results and registration of COF purchase

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"success",
    "date":"2019-09-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":{
    "id":10505,
    "currency":"EUR",
    "valid_thru":"2022-09-30T00:00:00+0000"
  },
  "operation":{
    "id":4314220000000056,
    "type":"account verification",
    "status":"success",
    "date":"2019-09-10T13:45:59+0000",
    "created_date":"2019-09-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":"2019-09-10T13:45:59+0000",
      "auth_code":"188591",
      "endpoint_id":120
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"P9g0U+eF2QWs2A=="
}

The following example of callback is for a card payment verification that is rejected by the payment system without explanation.

Figure 4. Example of declined payment card verification callback

{
  "project_id":874,
  "payment":{
    "id":"15538406111",
    "type":"account_verification",
    "status":"decline",
    "date":"2019-09-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":4314220000000056,
    "type":"account verification",
    "status":"decline",
    "date":"2019-09-16T06:06:53+0000",
    "created_date":"2019-09-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":"2019-09-16T06:06:49+0000",
      "auth_code":"",
      "endpoint_id":120
    },
    "code":"10100",
    "message":"Declined by external provider"
  },
  "signature":"P9g0U+eaZ9EeNiWiaQWs2A=="
}