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.pay-cross.com/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. Can be multiple values separated with semicolons. For example, "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f". If multiple values are sent in the request, the transaction search in the back office system can be performed by any of them.
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 PayCross 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": "[email protected]"
    }
  }
}
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. The value is returned for Visa, MasterCard, Maestro cards and the corresponding co-branded cards. Otherwise, null is returned.
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": "[email protected]",
      "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"
  }
}