Payment card verification

Payment card verification is a payment type that is meant to verify that a card can be used for payments. This option may be convenient for validating 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 Credential-on-file (COF) purchases.

This section covers information about how to verify a payment card.

To initiate payment card verification, send a specific request to the payment platform (an example of such a request will be provided later in this section). When processing the request, the payment platform will create 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 Two-step purchase.

Restriction:

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

Payment card verification workflow

To verify a payment card by using Gate you need to:

Send the request with all the required parameters and the signature to the actual URL of the Rocketpay payment platform.
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 Customer authentication by using the 3‑D Secure 1 and 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 figure provides the details of the payment card verification flow (without additional procedures).

Figure: Payment card verification flow

The customer enters the payment card details in your system.
Your system sends the purchase request to Gate.
The Rocketpay payment platform receives the verification request.
The payment platform checks whether the request contains all the required parameters and correct signature.
The payment platform sends you a response in which it acknowledges your request and provides the request validation result. (For more information about the response format, see Response structure.)
The payment platform processes the request and forwards it to the bank service.
The bank service verifies the payment card.
The bank service informs the payment platform about the verification result.
The payment platform sends the callback with the payment result to your system.

The sections that follow discuss in more details the request structure and the parameters to be used in requests for payment card verification, as well as provide information about the callbacks with the verification results.

Request

This section provides the instructions on how to build the request for payment card verification.

HTTP request method	POST
Request body format	JSON
API endpoint	/v2/payment/card/account_verification — API endpoint for card verification by the card number; /v2/payment/card/account_verification/token — API endpoint for card verification by a token associated with the card.
Full API endpoint specification	/v2/payment/card/account_verification — full API endpoint specification for card verification by the card number; /v2/payment/card/account_verification/token — full API endpoint specification for card verification by a token associated with the card.

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

Objects and parameters Description

general
object
strictly required

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

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.

customer
object
strictly required

id
string
strictly required

Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

IP address of the customer's device.

Example: 198.51.100.47

email
string
strictly required

Customer's email.

Example: johndoe@example.com

first_name
string
strictly required

Customer's first name.

Example: John

last_name
string
strictly required

Customer's last name.

Example: Doe

payment
object
strictly required

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.

currency
string
strictly required

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

Example: USD

To verify a card by using complete card credentials

card
object
strictly required

pan
string
strictly required

Card number.

Example: 1122334455667788

year
integer
strictly required

Year of expiration date.

Example: 2025

month
integer
strictly required

Month of expiration date.

Example: 8

card_holder
string
strictly required

Cardholder's first and last name (as indicated on the card).

Example: JOHN DOE

cvv
string
strictly required

Card verification code (as indicated on the card).

Example: 123

To verify a card by using its token

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: f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654

For more information see Tokens

cvv
string
strictly required

Card verification code (as indicated on the card).

Example: 123

To register a COF purchase

recurring
object
strictly required

COF purchase registration flag.

Example: true

The recurring object might also include other parameters. For more information about COF purchase registration, see Credential-on-file (COF) purchases.

You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Figure: Example of the data from a purchase request

{
  "general":{
    "project_id":123,
    "payment_id":"payment_47",
    "signature":"1wR1YgD5PxxTIJfQ=="
  },
  "customer":{
    "ip_address":"185.123.193.224",
    "id":"customer_123"
  },
  "payment":{
    "amount":0,
    "currency":"USD"
  },

//when submitting card credentials:
  "card":{
    "pan":"1122334455667788",
    "year":2025,
    "month":8,
    "card_holder":"John Doe",
    "cvv":"123"
  },

//when submitting the payment card's token:
  "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654",
  "cvv":"123"

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

Callback

The payment platform returns the purchase result in a callback. For the information about the callback structure, see Callbacks in Gate.

The following is the example of a callback with information about the successful verification of the 112233******7788 card of the customer customer_123 in the 123 project. 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":"2019-09-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":{
    "id":10505,
    "currency":"USD",
    "valid_thru":"2022-09-30T00:00:00+0000"
  },
  "operation":{
    "id":42209000002431,
    "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":"USD"
    },
    "sum_converted":{
      "amount":0,
      "currency":"USD"
    },
    "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=="
}

If the card fails the verification, the payment platform sends you a callback of the following example stating 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":"2019-09-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":"2019-09-16T06:06:53+0000",
    "created_date":"2019-09-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":"2019-09-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 card verification payment.

Payment status	Description
`error`	There was an error in the initial request, so the payment platform didn't accept the request and didn't start processing the payment. Final status. The request can be resent with the same payment id.
`processing`	Payment is being processed. Intermediate status
`awaiting 3ds result`	Payment processing is suspended. The payment platform waits for you to submit a request containing the `3ds_result` parameter 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 containing additional information. If the payment platform does not receive this request from you within 30 minutes, the 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 any 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 containing the `3ds_result` parameter 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 containing additional information. If the payment platform does not receive the 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

Payment card verification

Payment card verification workflow

Request

Callback

Payment statuses

Account verification operation statuses

Related links

`Account verification` operation statuses