Skip to content

The recipient's card tokenization

The request is used to get a token for the recipient's bank card along with the 3-D Secure verification details to later use them in a payout transaction.

As a result of a tokenization transaction, money isn't transferred to the recipient's card. Use the received token to send a payout request.


Request

To get the recipient's card tokenized, send a POST request to https://gateway.overpay.io/transactions/recipient_tokenizations with the following parameters:

Parameter Type Description
description string (255) The short description of the transaction.
tracking_id string Your internal ID of the recipient's card tokenization transaction. If the tracking_id is not unique per transaction, the system returns an array of up to 10 recent transactions with a matching tracking ID in the response to the query request.
recipient_billing_address object A section of the recipient's billing address.

Ask the Tech Support Team if your acquirer requires any of the section parameters.
first_name * conditionally required
string (30) The recipient's first name.
last_name * conditionally required
string (30) The recipient's last name.
country * conditionally required
string The recipient's billing country in ISO 3166-1 Alpha-2 format.
city * conditionally required
string (60) The recipient's billing city.
state * conditionally required
string The recipient's two-letter billing state only if the billing address country is US or CA.
zip string The recipient's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN
address * conditionally required
string (255) The recipient's billing address.
phone * conditionally required
string (100) The recipient's phone number.
recipient_credit_card object A section of the recipient's card details.
number * required
string (19) Card number.
holder * conditionally required
string (35) The cardholder name as it appears on the card. The parameter is optional in the Overpay system but can be required by the acquirer.
exp_month * conditionally required
string (2) Card expiration month. Must be one or two digits (for example, 01).
exp_year * conditionally required
string (4) Card expiration year. Must be 4 digits (for example, 2026).
recipient object A section of the recipient information.

Ask the Tech Support Team whether your acquirer requires any of the section parameters.
ip * conditionally required
string The customer's IP address.
email * conditionally required
string The customer's email.
device_id * conditionally required
string The customer's device ID (desktop, smartphone, etc.).
birth_date * conditionally required
string The customer's birth date in ISO 8601 format YYYY-MM-DD.
Example of the request
{
  "request": {
    "description": "Test transaction",
    "tracking_id": "your_uniq_number",
    "recipient_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street"
    },
    "recipient_credit_card": {
      "number": "4200000000000000",
      "holder": "John Doe",
      "exp_month": "05",
      "exp_year": "2026"
    },
    "recipient": {
      "ip": "127.0.0.1",
      "email": "john@example.com"
    }
  }
}
Response

The response will contain the same parameters as the request as well as additional parameters:

Parameter Type Description
transaction object
uid * required
string A UID of the processed transaction.
status * required
string A status of the processed transaction.
type * required
string A transaction type.
payment_method_type * required
string A payment method used to complete the transaction.

Possible values:
credit_card.
tracking_id * required
string The tracking_id parameter value sent in the transaction request.
message * required
string A processing result message.
created_at * required
string The transaction creation date.
updated_at * required
string The transaction update date. For example, a status update.
recipient_credit_card object
holder string The recipient's name.
stamp * required
string The card hash. It is constant even if the expiration date or the card holder are changed.
token * required
string The card token. Store the token and charge the returning customers or run recurring charges without the customers' billing details. The token lets you save the customer's details and charge them whenever they make new purchases, or you renew their services.
brand * required
string The detected card brand
last_4 * required
string The last 4 digits of the card.
first_1 * required
string The first digit of the card.
bin * required
string (6) 6-digit bank identification number (BIN). The first 6 digits of the card number.
bin_8 * required
string (8) 8-digit bank identification number (BIN). The first 8 digits of the card number.
issuer_country * required
string (2) The country of the card issuing bank in ISO 3166-1 Alpha-2 format.
issuer_name * required
string The name of the card issuing bank.
product * required
string A card product type code.
exp_month * required
integer The card expiration month, represented with one or two digits (for example, 01).
exp_year * required
integer The card expiration year, represented with four digits (for example, 2026).
token_provider * required
string Not used in this transaction. Always null.
id * required
string A UID of the processed transaction.
Example of the response
{
  "transaction": {
    "uid": "0775f4fe-c4ac-4b55-83c2-d89ef948d84a",
    "status": "successful",
    "description": "Test transaction",
    "type": "recipient_tokenization",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": "Successfully processed",
    "created_at": "2024-04-02T15:52:51.606Z",
    "updated_at": "2024-04-02T15:52:51.687Z",
    "recipient": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "device_id": null,
      "birth_date": null
    },
    "recipient_credit_card": {
      "holder": "John Doe",
      "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
      "brand": "visa",
      "last_4": "0000",
      "first_1": "4",
      "bin": "420000",
      "bin_8": "42000000",
      "issuer_country": "US",
      "issuer_name": "VISA Demo Bank",
      "product": "F",
      "exp_month": 5,
      "exp_year": 2026,
      "token_provider": null,
      "token": "39799863-240f-417e-9f12-5ca713118069"
    },
    "recipient_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    },
    "status_code": null,
    "id": "0775f4fe-c4ac-4b55-83c2-d89ef948d84a"
  }
}