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://processing.ecomcharge.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 eComCharge 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. 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": "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"
}
}