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:

Note

The request body must be wrapped in a top-level request{} object.

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 IN, US or CA. zip conditionally required 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, 2027). 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. external_id string (255) The customer's identifier in the merchant's system.

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": "2027"
    },
    "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:

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 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, 2027). 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": 2027,
      "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"
  }
}