Skip to content

Tokenization

The request is used to get a bank card token along with the 3-D Secure verification details and then to use the token to submit either a payment or an authorization transaction.

As a result of a tokenization transaction, money isn't withdrawn from the card account. Use the received token to send a payment or authorization request.

Request

To get a card tokenized, send a POST request to https://processing.ecomcharge.com/transactions/tokenizations with the following parameters:

Parameter Type Description
amount * required
 bigInteger A transaction amount in minimal currency units, for example, $32.45 must be sent as 3245.
currency * required
 string Currency in ISO-4217 format, for example, USD.
description * required
 string (255) The short description of the order.
tracking_id string (255) The ID of your transaction or order. Please, use unique values in order to get the correct transaction information in the response to the query request. Otherwise, you will get the first transaction that we will find with the matching tracking_id.
duplicate_check boolean The boolean parameter controls whether the payment gateway will do a duplicate check of the received requests to tokenize a card. By default, it is true and duplicate requests with the same amount and number sent within 30 seconds after the original request will be rejected.
dynamic_billing_descriptor string A dynamic billing descriptor.
language string A language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, eComCharge will dispatch those emails in language locale. English (en) is set by default. Possible values of language parameter.
notification_url string The URL where the webhook notification about a transaction will be posted. The notification request format is the same as the transaction response format.
verification_url string The URL where the transaction verification request will be posted. The verification request format is the same as the transaction response format.
return_url * conditionally required
 string The URL on the merchant's website to which eComCharge will redirect the customer once they complete 3-D verification.

Required, if your merchant account is 3-D Secure enabled.
test boolean If set to true, the transaction will be a test one. By default, false.
credit_card object
number * required
 string The card number. The length is between 12 and 19 digits.
verification_value * conditionally required
 string 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand).
The parameter can be required depending on the shop settings and acquirer requirements.
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 * required
 string (2) Card expiration month. Must be one or two digits (for example, 01).
exp_year * required
 string (4) Card expiration year. Must be 4 digits (for example, 2026).
skip_three_d_secure_verification boolean The parameter enables the option for the customer to skip the 3-D Secure verification check.

If true, eComCharge doesn't launch the 3-D Secure verification. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.

Contact the Tech Support Team to check if you can apply this parameter.
Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions.
force_three_d_secure_verification boolean The parameter enables the option to make the 3-D Secure verification check mandatory for the customer.

If true, eComCharge forces the 3-D Secure verification. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.

Contact the Tech Support Team to check if you can apply this parameter.
Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions.
three_d_secure object A section with the settings to apply the advanced scenario of payment processing with 3-D Secure 2.0 verification.
advanced boolean Set to true to apply the advanced scenario. Otherwise, set to false.
additional_data object A section with additional transaction data.
receipt_text array A text that will be added to the customer's email. Submit it as an array of strings, for example, ["First line", "Second line"].
contract array An array, consisting of elements:

recurring - eComCharge returns a card token to be used in subsequent charges without entering the card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification.

oneclick - eComCharge returns a card token to use it in the oneclick payment scheme. It means eComCharge will open a payment page with the prefilled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete the payment.

credit - eComCharge returns a card token to be used for a payout.
customer * conditionally required
 object A section of the customer 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 date of birth in the ISO 8601 format (YYYY-MM-DD).
billing_address object A section of the customer's address details. Contact the Tech Support Team to check if your acquirer requires any of the section parameters.
first_name * conditionally required
 string (30) The customer's first name.
last_name * conditionally required
 string (30) The customer's last name.
country * conditionally required
 string The customer's billing country in ISO 3166-1 Alpha-2 format.
city * conditionally required
 string (60) The customer's billing city.
state * conditionally required
 string The customer's two-letter billing state only if the billing address country is US or CA.
zip * conditionally required
 string The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address * conditionally required
 string (255) The customer's billing address.
phone * conditionally required
 string (100) The customer's phone number.
travel object An optional section with travel related data.
airline object The section with airline ticket data.
agency_code string IATA agency code, for example, 03.
agency_name string Name of the agency that sold the ticket, for example, Coral travel.
ticket_number string 14-digit ticket number. Should contain 3-digit ticketing code, 4-digit form number, 6-digit serial number, and check digit, for example, 390 5241 025377 1.
booking_number string For example, DKZVUA.
restricted_ticked_indicator string If the ticket can be returned, the field value is 0, otherwise it is 1
legs array An optional array of travel legs. Every leg consists of:
airline_code string 2-letter IATA code, for example, B2.
stop_over_code string IATA stopover code. If a traveler stays in the originating city more than 24h, then set the field value to O or leave it empty. If the originating airport is a transit airport, then set the field value to X.
flight_number string For example, A3 971.
departure_date_time string For example, 2014-05-26T05:15:00.
arrival_date_time string For example, 2014-05-26T07:30:00.
originating_country string For example, RU.
originating_city string For example, Moscow.
originating_airport_code string 3-letter IATA code, for example, DME.
destination_country string For example, Greece.
destination_city string For example, Athens.
destination_airport_code string 3-letter IATA code, for example, ATH.
coupon string Coupon number if it was applied.
class string Class flight, 1-letter IATA code. For example, C.
passengers array List of passengers where every list item consists of
first_name string First name of the passenger, for example, KONSTANTIN.
last_name string Last name of the passenger, for example, IVANOV.
Example of the request 
{
   "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "billing_address":{
         "first_name":"John",
         "last_name":"Doe",
         "country":"US",
         "city":"Denver",
         "state":"CO",
         "zip":"96002",
         "address":"1st Street"
      },
      "credit_card":{
         "number":"4200000000000000",
         "verification_value":"123",
         "holder":"John Doe",
         "exp_month":"05",
         "exp_year":"2026"
      },
      "customer":{
         "ip":"127.0.0.1",
         "email":"john@example.com"
      }
   }
}
Response

In the transaction section response parameters replicate request parameters except the additional ones:

Parameter Type Description
transaction object
uid * required
 string A UID of the processed transaction.
status * required
 string A status of the processed transaction.
message * required
 string A processing result message.
tracking_id * required
 string The tracking_id parameter value sent in the transaction request.
language * required
 string The language parameter value sent in a transaction request or en if the parameter was omitted.
type * required
 string A transaction type.
payment_method_type * required
 string A payment method used to complete the transaction.

Possible values:
credit_card.
credit_card object
brand * required
 string The detected card brand.
product * required
 string A card product type code.
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.
stamp * required
 string The card hash. It is constant even if either the expiration date or the cardholder is changed.
token * required
 string The card token. Store the token and charge returning customers or run recurring charges without 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.
three_d_secure_verification object A section with 3-D Secure verification results.
tokenization object
message * required
 string A tokenization result message.
status * required
 string A tokenization status.

Possible values:
successful,
failed.
additional_data object A section of detailed information about the payment.
receipt_text array A text that will be added to the customer email.
smart_routing_verification object A section of parameters of Smart Routing verification results.
data object Object with the detailed information on the Smart Routing verification results.
matched_actions object Object with the actions that were applied to the transaction.
skip_3ds array An action meaning 3-D Secure verification was skipped for the transaction as a result of Smart Routing rule application; an array of rules that resulted in the action. Each rule is represented by an object with the following parameters:

alias - the rule name; description - the rule description;

account - the name of the account on the level of which the rule was created.
force_3ds array An action meaning 3-D Secure verification was forced for the transaction as a result of Smart Routing rule application; an array of rules that resulted in the action. Each rule is represented by an object with the following parameters:

alias - the rule name;
description - the rule description;
account - the name of the account on the level of which the rule was created. Check with your account manager whether force 3D Secure action is allowed for your shop.
Example of the response 
{
  "transaction": {
    "uid": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
    "status": "successful",
    "amount": 492,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "tokenization",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-04-02T14:32:33.946Z",
    "updated_at": "2024-04-02T14:32:35.000Z",
    "paid_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/e89abc1a-1d18-4d0f-83a1-7009b333dce0",
    "status_code": null,
    "id": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
      "brand": "visa",
      "last_4": "1097",
      "first_1": "4",
      "bin": "401200",
      "bin_8": "40120000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 7,
      "exp_year": 2026,
      "token_provider": null,
      "token": "e3ba5977-8705-4496-bf90-a6a93d3d31cc"
    },
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "smart_routing_verification": {
      "status": "successful"
    },
    "tokenization": {
      "message": null,
      "gateway_id": 3483,
      "status": "successful"
    },
    "customer": {
      "ip": null,
      "email": null,
      "device_id": null,
      "birth_date": null
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}
Example of the response when the Skip 3ds action was applied to the transaction by Smart Routing 
{
  "transaction": {
    "uid": "087b516e-fe96-4571-8b81-09b4055b2197",
    "status": "successful",
    "amount": 492,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "tokenization",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-03-27T08:12:45.947Z",
    "updated_at": "2024-03-27T08:12:47.454Z",
    "paid_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/087b516e-fe96-4571-8b81-09b4055b2197",
    "status_code": null,
    "id": "087b516e-fe96-4571-8b81-09b4055b2197",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
      "brand": "visa",
      "last_4": "1097",
      "first_1": "4",
      "bin": "401200",
      "bin_8": "40120000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 7,
      "exp_year": 2026,
      "token_provider": null,
      "token": "507cd554-d400-455e-b3c2-cba6dc032636"
    },
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "smart_routing_verification": {
      "status": "successful",
      "data": {
        "skip_3ds": true,
        "status": "passed",
        "object": "3483",
        "object_name": "gw_3483",
        "object_flows": [],
        "object_defined_via": "allowed objects",
        "action_rules": {
          "Shop_1673_Good Point 2": {
            "skip 3 ds": {
              "skip 3 ds": "skip_3ds"
            }
          }
        },
        "matched_actions": {
          "skip_3ds": [
            {
              "alias": "skip 3 ds",
              "description": "skip 3 ds",
              "account": "Shop_1673_Good Point 2"
            }
          ]
        },
        "wb_lists": {
          "psp_black_list": "not_matched",
          "psp_white_list": "not_matched"
        }
      }
    },
    "tokenization": {
      "message": null,
      "gateway_id": 3483,
      "status": "successful"
    },
    "customer": {
      "ip": null,
      "email": null,
      "device_id": null,
      "birth_date": null
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}