Create a payment token

Before you use either the eComCharge payment widget or the hosted payment page, you should create a payment token.

Request

Send a POST request to https://checkout.ecomcharge.com/ctp/api/checkouts.

The request must:

use HTTP Basic authentication with Shop ID and Secret Key;
have the headers Content-Type: application/json, Accept: application/json and X-API-Version: 2;
be UTF-8 encoded.

Parameter	Type	Description
checkout	object
transaction_type * required	string	Type of transaction or request that will be sent to gateway. Applicable values are `authorization`, `payment`, `tokenization`, and `charge` (for the charge request).
attempts	integer	A number of payment attempts. The default is `1`.
dynamic_billing_descriptor	string	Dynamic billing descriptor.
test	boolean	The transaction will be a test one if it is `true`. By default, set as `false`.
iframe	boolean	When value is `true`, if possible, open transitions to external services inside the widget. By default, set as `false`.
order	object
amount * required	integer	Payment amount in minimal currency units, for example $32.45 must be sent as 3245.
currency * required	string	A transaction currency in the ISO-4217 alpha-3 code format. For example, `USD`.
description * required	string	Order description.
tracking_id	string	The ID of your transaction or order. Please, use unique values for each transaction.
expired_at	string	Date and time till a payment can be done. By default, a payment must be done within 24 hours upon a payment token creation. Format (ISO 8601): YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm или –hh:mm).
additional_data	object	A section of additional information about the payment.
receipt_text	array	A text that will be added to the customer's mail and will be showed on success result page. Submit it as an array of strings, for example `["First line", "Second line"]`.
contract	array	An array that consists of elements: `recurring` - eComCharge returns a card token to use it for subsequent payments when the customer has no need to enter card data again. As for the initial payment, the customer should provide full card data including a CVC/CVV code, pass the 3-D Secure verification, and give consent to be charged regularly. `oneclick` - eComCharge returns a card token to use it in the one-click payment scheme. eComCharge opens a payment page with pre-filled card data to the customer. To complete a payment, the customer has to enter a CVC/CVV code and to pass the 3-D Secure verification; `credit` - eComCharge returns a card token to use it for a payout operation; `card_on_file` - eComCharge returns a card token to save it to a customer profile and to use the token in time-to-time charges initiated by the customer or by your application. See `card_on_file` section below to understand what cases the contract type covers.
avs_cvc_verification	object	AVS/CVC verification.
card_on_file	object	It sets flags submitted to a payment network why and what you charged a previously saved card for. If no submitted default values of `initiator` and `type` are in use.
initiator	string	`merchant` - (default) merchant initiated a card charge (for instance, for a car ride service). `customer` - customer initiated a card charge (for instance, customer confirmed and order and wanted to pay by a saved card).
type	string	Used only in case `additional_data.card_on_file.initiator` is `merchant`. `delayed_charge` - (default) delayed charge posted to a card `increment` - merchant wants to charge additional amount above initially paid order (for instance, in case of upsale) `resubmission` - merchant wants to resubmit a transaction due to fail with a previous charge (for instance, no money on a card) `reauthorization` - merchant wants to refresh previously authorized amount (for instance, to continue to hold a money reserve on a card for future charges) `no_show` - merchant wants to charge a card when customer didn't come (for instance, no visit to a hotel)
settings	object
auto_pay	boolean	By default `false`. If `true` and the request contains `payment_method.credit_card.token`, the response will contain a link to the checkout page. Opening the link will automatically trigger the transaction that will run using the provided token. As a result, the customer will be redirected to `suсcess_url`, `decline_url`, `fail_url` or `return_url` depending on the transaction result and the URLs provided in the request. The webhook notification with the transaction status will be posted to the `notification_url`.
save_card_toggle	object	A section for configuring the toggle shown on the payment widget. The toggle enables the option to save card data for future payments.
display	boolean	If the parameter is `true`, the save card toggle should be displayed. This parameter has greater priority, than `Display save card toggle on payment page` parameter in shop settings in the Merchant back office. By default, set to `true`.
customer_contract	boolean	`true` - the toggle stands for the customer's consent to provide the merchant with the customer's card data for subsequent payments. When the toggle is on, the system creates the card token and sends it out to the merchant. Otherwise, the card token is not provided. `false` - the toggle stands for the customer's consent to get the card data saved on the payment page. When the toggle is on, the system will autocomplete the card data for subsequent payments in the merchant's shop. Otherwise, the card data are not saved. By default, `false`.
text	string	The parameter replaces the standard toggle name `Save card` to any Merchant text.
hint	string	Hint text, described why the save card option is needed.
another_card_toggle	object	A section for configuring the another card toggle.
display	boolean	If the parameter is `true`, the toggle `Рay with another card` will be displayed on the widget. This parameter has greater priority, than `Hide another card toggle on payment page` parameter in shop settings in the Merchant back office. By default, set to `true`.
return_url	string	URL to return the customer after transaction was complete. If set, then both `success_url` and `decline_url` are ignored.
success_url	string	URL to return the customer to if a transaction was successful.
decline_url	string	URL to return the customer to if a transaction was declined by bank.
fail_url	string	URL to return the customer to if a transaction failed (due to an error, exception, etc.). You can query its status using the payment token and review response `status` and `message` parameters to evaluate why the transaction failed.
cancel_url	string	URL to return the customer to if the customer cancels a transaction.
notification_url	string	URL where notification about a transaction will be posted to. A notification request format is similar to a transaction response format.
verification_url	string	URL where transaction verification request will be posted to. The verification request format equals to a transaction response format.
auto_return	string	After a transaction completes, eComCharge shows a transaction result page for specified number of seconds and then automatically returns the customer to one of your return URLs. If the parameter value is `0`, then the customer will be automatically redirected without showing eComCharge transaction result page.
button_text	string	Customize the payment button text. Note: `{amount}` can be used as a placeholder to show transaction amount within the customized text.
button_next_text	string	Customize the payment result page button text.
card_notification_url	string	A URL for receiving card notifications containing the file with card art. More details.
language	string	Checkout page locale. English (`en`) is set by default. Possible values of `language` parameter.
customer_fields	object	It controls the input fields for the customer details shown at the payment widget.
read_only	array	It is an array which may consist of the values `email`, `first_name`, `last_name`, `address`, `city`, `state`, `zip`, `phone`, `country`, `birth_date`, `taxpayer_id`. Fields for the customer's data indicated in the array will be disabled at the payment widget. If `email` exists in the array then it must present in the customer section below, and it can't be empty.
visible	array	It is an array which may consist of the values `email`, `first_name`, `last_name`, `address`, `city`, `state`, `zip`, `phone`, `country` and `birth_date`, `taxpayer_id`. Fields for the customer's data indicated in the array will be displayed at the payment widget.
credit_card_fields	object	It controls the automatic filling of the cardholder name on the payment widget.
holder	string	Cardholder name for automatic filling on the payment widget.
read_only	array	It is an array which may consist only `holder` value. Blocks editing of the selected field.
customer * conditionally required	object	A section of the customer information. Contact the Tech Support Team to inquire what section parameters are required.
email	string	The customer's email.
first_name	string	The customer's first name.
last_name	string	The customer's last name.
address	string	The customer's billing address.
city	string	The customer's billing city.
state	string	The customer's two-letter billing state only if the billing address country is `US` or `CA`.
zip	string	The customer's billing ZIP or postal code.
country	string	The customer's billing country in ISO 3166-1 alpha-2 format.
phone	string	The customer's phone number.
birth_date	string	The customer's date of birth in the ISO 8601 `YYYY-MM-DD` format.
taxpayer_id	string	The customer's taxpayer ID.
payment_method	object	A section to set payment methods available to the customer and their parameters. By default, all enabled payment methods are available.
types	array	An array of the available and enabled payment methods displayed to the customer on the payment page. Possible values: `credit_card` - a bank card payment Note! Apple Pay, Google Pay, Samsung Pay and Yandex Pay are displayed on the widget depending on the customer's device and browser types. See more here.
excluded_types	array	An array of the payment types that will be excluded from the available payment methods on the payment page. If both `payment_method.types` and `payment_method.excluded_types` are sent in the request, the information from `payment_method.types` will be applied and `payment_method.excluded_types` will be ignored.
credit_card	object
token	string	Card token. The tokenized data will be displayed on the payment page.
travel	object	Travel related data.
airline	object	A 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`.

Request example

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",
      "button_text": "Tie the card",
      "button_next_text": "Back to the shop",
      "language": "en",
      "card_notification_url": "https://your-card-notification-url.com",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      },
      "credit_card_fields": {
        "holder": "Rick Astley",
        "read_only": ["holder"]
      }
    },
    "payment_method": {
      "types": ["credit_card"]
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description"
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}

Request example with additional receipt text and without redirect to result page

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",
      "auto_return": 0,
      "language": "en",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      }
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description",
      "additional_data": {
        "receipt_text": ["First line", "Second line"]
      }
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}

Request example with information about the sale of tickets and tour vouchers

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",
      "auto_return": 3,
      "button_text": "Tie the card",
      "button_next_text": "Back to the shop",
      "language": "en",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      }
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description"
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    },
    "travel": {
      "airline": {
        "agency_code": "03",
        "agency_name": "Corel travel",
        "ticket_number": "390 5241 025377 1",
        "booking_number": "DKZVUA",
        "restricted_ticked_indicator": "0",
        "legs": [
          {
            "airline_code": "B2",
            "stop_over_code": "X",
            "flight_number": "A3 971",
            "departure_date_time": "2014-05-26T05:15:00",
            "arrival_date_time": "2014-05-26T07:30:00",
            "originating_country": "RU",
            "originating_city": "Moscow",
            "originating_airport_code": "DME",
            "destination_country": "Greece",
            "destination_city": "Athens",
            "destination_airport_code": "ATH",
            "coupon": "coupon code",
            "class": "C"
          }
        ],
        "passengers":[
          {
            "first_name": "KONSTANTIN",
            "last_name": "IVANOV"
          },
          {
            "first_name": "JULIA",
            "last_name": "IVANOVA"
          }
        ]
      }
    }
  }
}

Request example with auto_pay: true

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,    
    "iframe": true,
    "settings": {
      "return_url": "https://return-url",
      "auto_pay": true,
      "language": "en"
    },
    "payment_method": {
      "types": [
        "credit_card"
      ],
      "credit_card": {
        "token": "13dded21-ed69-4590-8bcb-db522a89735c"
      }
    },
    "order": {
      "currency": "USD",
      "amount": 700,
      "description": "auto payment"
    },
    "customer": {
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Response

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

Parameter	Type	Description
checkout	object
token * required	string	A payment token.
redirect_url * required	string	An URL of the payment widget where the customer can pay for the order related with the issued payment token.

Response example

{
  "checkout":
  {
    "token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "redirect_url": "https://checkout.ecomcharge.com/v2/checkout?token=3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51"
  }
}

Error response example

{
  "errors": {
    "settings":["is invalid"],
    "order":["is invalid"],
    "settings.fail_url": ["does not appear to be valid"],
    "order.currency":["is invalid"]
  },
  "message":"Settings is invalid. Order is invalid. Settings.fail_url does not appear to be valid. Order.currency is invalid"
}