Payment card verification

General information

Payment card verification is a payment type that is meant to verify that the card can be used for payments. This option may be convenient for verifying cards before making payouts to customers or when registering subscriptions without immediate debiting (for example, for a free trial period). For more information about credential-on-file purchase registration, see COF purchase registration.

This section describes how to verify a payment card when using Payment Page.

To initiate payment card verification, you specify the card_verify mode in the request to open the payment form (an example of such a request is provided later in this section). After that, the customer should confirm their consent to payment card verification. Then, your system sends a request to the payment platform, and the payment platform creates the account verification operation.

There are two verification options:

a dummy (zero amount) payment from customer to your account;
a specific (non-zero) authorization hold on the customer's card followed by the release of funds. Your key account manager can help you set a preferred authorization amount. The authorization amount can be held up to 45 days.

This section covers only the zero amount payment card verification. For more information about authorization hold, see Authorization hold.

Restriction:

Reach out to your Rocketpay key account manager to find out if payment card verification is available in your project.

In the process of payment card verification, Payment Page might ask the customer to take some basic steps: to specify the payment information, to save the payment information for subsequent payments, or to wait for the result notification.

Workflow

To verify a payment card by using Payment Page you need to:

Create and send to the payment platform a request to open Payment Page.
If necessary, complete auxiliary steps initiated by the payment platform. This could involve one of the user authentication options or submitting additional payment information:
- 3‑D Secure authentication This authentication provides security to online card payments. To learn more about the authentication workflow, see Authentication by using 3‑D Secure 2.
- Submission of additional payment information This procedure is used when the initial request did not contain all the necessary information. To learn more about submitting additional information, see Submission of additional payment information.
Receive a callback with the verification result from the payment platform.

The following sections cover information about payment cards verification request and callback with the results.

Request

To open Payment Page and begin card verification, the request must contain the following parameters:

strictly required—the parameter must be in the initial request.

Parameter Description

mode
string, strictly required

Payment Page mode. To verify a card you need to specify card_verify in this parameter.

Example: card_verify

project_id
integer
strictly required

Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

Payment ID unique within your project.

Example: payment_47

customer_id
string
strictly required

Unique ID of the customer within your project.

Example: customer_123

customer_first_name
string
strictly required

Customer's first name.

Example: John

customer_last_name
string
strictly required

Customer's last name.

Example: Doe

customer_email
string
strictly required

Customer's email.

Example: johndoe@example.com

payment_currency
string
strictly required

Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: USD

payment_amount
integer
strictly required

Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 100.00 USD must be sent as 10000

Restriction: To verify a card the payment amount should equal zero.

signature
string
strictly required

Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

To verify a card by using its token

account_token
string, strictly required

A token of the customer's payment card. A token is a unique sequence of 64 characters associated with a specific bank card.

Example: 42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021

Restriction: Available in the Purchase and Card Verify modes.

For more information about tokens, see Tokenization

To register a COF purchase

recurring
string, strictly required

A string containing encoded registration and COF payment parameters. The data is collected into a JSON object and encoded by using URL encoding. The structure of the JSON object is available in the API specification in the recurringinfo scheme.

For more information, see COF purchase registration

You can also add any other optional parameters to the request, if necessary. For the list of all the parameters possible in requests to Payment Page, see Payment Page invocation parameters.

Here is an example of the data from a request to open the checkout page by using EPayWidget:

EPayWidget.run(
    {
   "mode": "card_verify",
   "project_id": "123",
   "payment_id": "payment_47",
   "payment_currency": "USD",
   "payment_amount": "0",
   "signature": "TSzdE5rJpfXriFf82MxF..."

// To save payment information:
    "customer_id": "customer_123"

// To verify the card by its token:
   "account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021"

// To register a COF purchase:
   "recurring": {
        "register": "true",
        "type": "R",
        ...
       }
    }
)

An example of the data from a GET request:

https://paymentpage.rocketpay.kz/payment?language_code=ru&mode=card_verify&project_id=123&payment_amount=0&payment_currency=USD&payment_id=15538406111&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E...

Callback

The payment platform returns the verification result in a callback. For more information about the callback structure, see Callbacks in Payment Page.

The following is an example of a callback with information about successful verification of the card with the number 112233******7788 of the customer customer_123. The card was also successfully registered for subsequent COF purchases.

Figure: Example of the data from a callback with information about successful card verification

{
  "project_id":123,
  "payment":{
    "id":"payment_47",
    "type":"account_verification",
    "status":"success",
    "date":"2020-06-10T13:45:59+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"USD"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"112233******7788",
    "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f",
    "type":"visa",
    "card_holder":"JOHN DOE",
    "id":8861226,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{
    "id":"customer_123"
  },
  "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":"USD"
    },
    "sum_converted":{
      "amount":0,
      "currency":"USD"
    },
    "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..."
}

If the card verification fails , the payment platform sends you a callback with the information that the payment was declined.

Figure: Example of a callback with information that the card verification failed

{
  "project_id":123,
  "payment":{
    "id":"payment_47",
    "type":"account_verification",
    "status":"decline",
    "date":"2020-06-16T06:06:53+0000",
    "method":"card",
    "sum":{
      "amount":0,
      "currency":"USD"
    },
    "description":"Add the card"
  },
  "account":{
    "number":"112233******7788",
    "type":"visa",
    "card_holder":"JOHN DOE",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{
    "id":"customer_123"
  },
  "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":"USD"
    },
    "sum_converted":{
      "amount":0,
      "currency":"USD"
    },
    "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..."
}

Payment statuses

This section provides information about possible statuses of payment and its related operations.

Figure: Diagram for payment statuses

The following table describes the statuses of a card verification payment.

Payment status	Description
`error`	An error occurred when the payment platform started processing the initial request. Payment processing was not initiated. Final status. Payment processing can be re-initiated.
`processing`	Payment is being processed. Intermediate status
`awaiting 3ds result`	Payment processing is suspended. The payment platform waits for you to submit a request with the 3‑D Secure authentication result. If the payment platform does not receive this request from you within 30 minutes, then the payment status is set to `decline`. Intermediate status
`awaiting clarification`	Payment processing is suspended. The payment platform waits for you to submit a request with the additional information from the customer. If the payment platform does not receive this request from you within 30 minutes, then the payment status is set to `decline`. Intermediate status
`decline`	Payment was declined. Final status
`success`	Payment was completed successfully. Final status

`Account verification` operation statuses

The following table describes the statuses of the account verification operation.

Operation status	Description
`processing`	Operation is being processed. Intermediate status
`awaiting 3ds result`	Operation processing is suspended. The payment platform waits for you to submit a request with the 3‑D Secure authentication result. If the payment platform does not receive this request from you within 30 minutes, then the status is set to `decline`. Intermediate status
`awaiting clarification`	Operation processing is suspended. The payment platform waits for you to submit a request with the additional information from the customer. If the payment platform does not receive this request from you within 30 minutes, the status is set to `decline`. Intermediate status
`decline`	Operation was not completed. Final status
`success`	Operation was completed successfully. Final status