Skip to content

Tokenization

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


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
integer 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 order short description.
tracking_id. string (255) The ID of your transaction or order. Please, use unique values in order to get transaction information by query request otherwise you will get first transaction that we will find with tracking_id.
duplicate_check boolean The parameter controls whether the payment gateway will do duplicate check of received requests to tokenize a card. By default, it is true and requests with the same amount and number within 30 seconds 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 notification about a transaction will be posted to. The notification request format equals to a transaction response format.
verification_url string The URL where transaction verification request will be posted to. The verification request format equals to a transaction response format.
return_url * conditionally required
string URL on Merchant's side where eComCharge will send Customer's browser when Customer returns from 3-D Secure verification.

Required, if your merchant account is 3-D Secure enabled.
test boolean The transaction will be a test one if it is true.
credit_card object
number * required
string The card number. The length is from 12 to 19 digits.
verification_value * required
string 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand).
holder * required
string (32) The cardholder name as it appears in the card.
exp_month * required
integer The card expiration month expressed with two digits (for example, 01).
exp_year * required
integer The card expiration year expressed with four digits (for example, 2007).
three_d_secure object A section with the setting 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, false.
additional_data object A section of detailed information about the payment.
receipt_text array Text, that will be added to client's mail. 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 use it in subsequent charges without to enter a 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 one-click payment scheme. It means eComCharge will open a payment page with pre-filled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete payment.

credit - eComCharge returns a card token to use it for a payout.
customer * conditionally required
object A section of the customer information.
Contact Tech Support Team to inquire if 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 billing address.

Contact Tech Support Team to inquire 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 contains airline ticket addendum data.
agency_code string IATA agency code, for example 03.
agency_name string Agency name who sold the ticket, for example Corel 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 left it empty. If the originating airport is 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. Example, C.
passengers array List of passengers where every list item consists of
first_name string First name of passenger, for example KONSTANTIN.
last_name string Last name of 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":"2020"
      },
      "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: visa, master, jcb, discover, dinersclub, amex, belkart and unionpay.
product * required
string The card product: Electron, Classic, Gold, Standard, etc.
last_4 * required
string The last 4 digits of the card.
first_1 * required
string The first digit of the card.
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 allows you to 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 mail.
Example of the response
{
   "transaction":{
      "customer":{
         "ip":"127.0.0.1",
         "email":"john@example.com"
      },
      "credit_card":{
         "holder":"John Doe",
         "stamp":"3709786942408b77017a3aac8390d46d77d181e34554df527a71919a856d0f28",
         "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e",
         "brand":"visa",
         "product":"Gold",
         "last_4":"0000",
         "first_1":"4",
         "exp_month":5,
         "exp_year":2015
      },
      "additional_data":{
         "receipt_text":["First line", "Second line"]
      },
      "billing_address":{
         "first_name":"John",
         "last_name":"Doe",
         "address":"1st Street",
         "country":"US",
         "city":"Denver",
         "zip":"96002",
         "state":"CO",
         "phone":null
      },
      "three_d_secure_verification":{
         "eci":"6",
         "pa_status":"Y",
         "xid":null,
         "cavv":null,
         "cavv_algorithm":null,
         "fail_reason":null,
         "ve_status":"Y",
         "message":"Authentication Successful",
         "status":"successful"
      },
      "tokenization":{
         "message":"The operation was successfully processed.",
         "status":"successful"
      },
      "uid":"4107-310b0da80b",
      "status":"successful",
      "message":"Successfully processed",
      "amount":100,
      "currency":"USD",
      "description":"Test order",
      "type":"tokenization",
      "tracking_id":"your_uniq_number",
      "language":"en"
   }
}