Создание токена платежа

Для использования страницы оплаты или платежного виджета торговцу требуется создать токен платежа.

Запрос

Отправьте POST запрос на https://checkout.ecomcharge.com/ctp/api/checkouts.

Запрос должен:

• иметь авторизацию типа Basic с ID и Secret key магазина как имя пользователя и пароль соответственно;
• иметь заголовки Content-Type: application/json, Accept: application/json и X-API-Version: 2;
• использовать кодировку UTF-8.

Параметр	Тип	Описание
checkout	object
transaction_type * обязательный	string	Tип транзакции или запроса, который будет отправлен шлюзу. Возможные значения - authorization, payment, tokenization и charge (для запроса на взимание платы).
attempts	integer	Количество попыток для оплаты. По умолчанию - 1.
dynamic_billing_descriptor	string	Динамический идентификатор платежа.
test	boolean	Транзакция будет тестовой, если значение true. По умолчанию, false.
iframe	boolean	При true открывать, по возможности, переходы на внешние сервисы внутри виджета. По умолчанию, false.
order	object
amount * обязательный	integer	Сумма к оплате в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245.
currency * обязательный	string	Валюта транзакции в формате ISO-4217 alpha-3 code. Например, USD.
description * обязательный	string	Описание платежа.
tracking_id	string	ID транзакции или заказа в вашей системе. Рекомендуется использовать уникальное значение для каждой транзакции.
expired_at	string	Дата и время, до которого должна быть сделана оплата. По умолчанию оплата должна быть сделана в течение 24 часов после создания токена на оплату. Формат: ISO 8601 вида YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например, 2019), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – временная зона (+hh:mm или –hh:mm).
additional_data	object	Секция, содержащая детальную информацию по платежу.
receipt_text	array	Текст, который будет добавлен в письмо покупателю и отображен на странице об успешной оплате. Должен быть представлен как массив строк, например ["Первая строка", "Вторая строка"].
contract	array	Массив, элементами которого могут быть параметры: recurring - eComCharge вернет токен карты для проведения последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D ­Secure; oneclick - eComCharge вернет токен карты для осуществления последующих платежей по схеме one-click. eComCharge будет показывать пользователю страницу оплаты с уже частично заполненными реквизитами карты. Для завершения платежа пользователю достаточно ввести проверочный код карты CVC/CVV и пройти авторизацию по протоколу 3-D ­Secure; credit - eComCharge вернет токен карты для осуществления операций выплаты; card_on_file - eComCharge вернет токен карты, чтобы вы могли сохранить ее на профайле пользователя и использовать этот токен для последующих операций по списанию денег с карты за оказанные услуги или проданные товары. Ознакомьтесь ниже с секцией card_on_file, чтобы узнать сценарии использования данного значения.
avs_cvc_verification	object	AVS/CVC проверка.
card_on_file	object	Данная секция устанавливает атрибуты операции, которые будут отправлены в дальнейшем в платёжную систему и атрибуты операции которые, если секция не передана, будут использованы по умолчанию для initiator и type.
initiator	string	merchant - (по умолчанию) операция инициирована вашей системой или приложением (например, оплата за поездку в такси). customer - операция инициирована покупателем (например, покупатель сам нажал кнопку оплатить сохраненной картой в вашем приложении).
type	string	Используется только если additional_data.card_on_file.initiator имеет значение merchant. delayed_charge - (по умолчанию) отложенная оплата (например, за оказанную услугу) increment - списание дополнительной суммы (например, при дополнительной продаже товара или замене на более дорогой товар) resubmission - повторная попытка списать деньги из-за предыдущего отказа в операции (например, не было денег на карте) reauthorization - обновление авторизации (например, нужно повторно заблокировать деньги на карте в связи с истечением срока авторизации предыдущей операции) no_show - покупатель не пришел (например, не заехал в отель)
settings	object
auto_pay	boolean	По умолчанию – false. Если true, и запрос включает параметр payment_method.credit_card.token, то в ответе на запрос придет ссылка, переход по которой автоматически запустит транзакцию c использованием предоставленного токена. В результате, покупатель будет перенаправлен на suсcess_url, decline_url, fail_url или return_url в зависимости от результата транзакции и от того, какие ссылки предоставлены в запросе. Также на notification_url будет выслано автоматическое уведомление со статусом транзакции.
save_card_toggle	object	Опционально Секция для настройки тогла на платежном виджете. Тогл позволяет сохранить данные карты для последующих платежей.
display	boolean	Опционально Если true, то тогл сохранения карты будет отображаться на виджете. Данный параметр имеет более высокий приоритет, чем параметр Показывать опцию сохранения карты на платежной форме в настройках магазина в личном кабинете торговца. По умолчанию true.
customer_contract	boolean	Опционально true - тогл отвечает за согласие покупателя предоставить данные своей карты торговцу для последующих платежей. Если покупатель активирует тогл, система создаст токен для карты покупателя и вернет этот токен торговцу. Если тогл не активирован, токен карты не будет предоставлен торговцу. false - тогл отвечает за согласие покупателя сохранить данные для отображения на платежной странице. Если покупатель активирует тогл, система будет автоматически заполнять данные его карты для оплаты последующих заказов в магазине торговца. Если тогл не активирован, данные карты не сохраняются. По умолчанию false.
text	string	Параметр заменяет стандартное имя тогла Save card на любой текст торговца.
hint	string	Текст описывающий, для чего нужна опция сохранения карты.
another_card_toggle	object	Секция для настройки тогла оплаты другой картой.
display	boolean	Если true, то тогл Оплатить другой картой будет отображаться на виджете. Данный параметр имеет более высокий приоритет, чем параметр Показывать опцию оплаты другой картой на платежной форме в настройках магазина в личном кабинете торговца. По умолчанию true.
return_url	string	URL, на который будет перенаправлен покупатель после завершения оплаты. Если задан, то success_url и decline_url игнорируются.
success_url	string	URL, на который будет перенаправлен покупатель при успешной транзакции.
decline_url	string	URL, на который будет перенаправлен покупатель при отклоненной банком транзакции.
fail_url	string	URL, на который будет перенаправлен покупатель при неудавшейся транзакции (из-за ошибки, исключительной ситуации и т.д.). Вы можете запросить статус транзакции, используя токен оплаты, изучить status ответа или параметр message, чтобы оценить, почему транзакция не прошла.
cancel_url	string	URL, на который будет перенаправлен покупатель в случае отмены операции.
verification_url	string	URL, на который будут приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции.
notification_url	string	URL, на который будут приходить уведомления.
auto_return	string	По завершении операции eComCharge показывает страницу результата операции на заданное количество секунд и затем автоматически перенаправит покупателя обратно на сайт торговца. Если параметр равен 0, то по окончанию оплаты покупатель будет сразу перенаправлен на сайт торговца и результирующая страница оплаты показана не будет.
button_text	string	Пользовательский текст кнопки начала оплаты. Замечание: {amount} может быть использован как шаблон для отображения суммы транзакции внутри текста.
button_next_text	string	Пользовательский текст кнопки возврата со страницы результата операции на сайт торговца.
card_notification_url	string	URL, на который будут приходить карточные уведомления с ссылкой на файл с изображением платежной карты покупателя. Подробнее.
language	string	Язык страницы оплаты. По умолчанию - en. Доступные значения параметра language.
customer_fields	object	Управляет полями ввода на странице оплаты.
read_only	array	Массив, который может содержать значения email, first_name, last_name, address, city, state, zip, phone, country, birth_date и taxpayer_id. Поля, указанные в массиве, будут заблокированы (disabled). Если массив содержит поле email, то оно должно быть в секции customer ниже и не должно быть пустым.
visible	array	Массив, который может содержать значения email,first_name, last_name, address, city, state, zip, phone, country, birth_date и taxpayer_id. Поля, указанные в массиве, отобразятся на странице платежа и будут обязательны для заполнения.
credit_card_fields	object	Управляет автоматическим заполнением на странице оплаты поля с именем владельца карты.
holder	string	Имя держателя карты для автоматического заполнения на странице оплаты.
read_only	array	Массив, который может принимать только значение holder. Блокирует редактирование выбранного поля.
customer * условно обязательный	object	Секция информации о покупателе. Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции.
email	string	Адрес электронной почты покупателя.
first_name	string	Имя покупателя.
last_name	string	Фамилия покупателя.
address	string	Адрес для выставления счёта.
city	string	Город покупателя.
state	string	Штат / Область / Регион покупателя (состоит из двух букв), только если страна адреса для выставления счёта US или CA.
zip	string	Почтовый индекс покупателя.
country	string	Страна покупателя в ISO 3166-1 alpha-2 формате.
phone	string	Номер телефона.
birth_date	string	Дата рождения покупателя в формате ISO 8601 YYYY-MM-DD.
taxpayer_id	string	Идентификационный номер налогоплательщика (ИНН), присвоенный покупателю.
payment_method	object	Секция для указания доступных покупателю способов оплаты и их параметров. По умолчанию доступны все активные способы оплаты.
types	array	Массив способов оплаты для отображения на странице оплаты. Возможные значения: credit_card - оплата банковской картой Отображение Apple Pay, Google Pay, Samsung Pay и Yandex Pay на виджете зависит от типа устройства и браузера покупателя. Подробнее описано здесь.
excluded_types	array	Массив способов оплаты, которые будут исключены из доступных методов, отображаемых на платежной странице. При отправке в запросе обоих параметров payment_method.types и payment_method.excluded_types приоритетной считается информация в payment_method.types. Данные из payment_method.excluded_types игнорируются.
credit_card	object
token	string	Токен карты. На платежной странице будут отображаться данные токенизированной карты.
travel	object	Секция, предоставляющая расширенную информацию о продаже авиабилетов, туристических путевок и т.д.
airline	object	Необязательная секция, содержащая расширенную информацию о проданном авиабилете.
agency_code	string	IATA код агентства, например 03.
agency_name	string	Название агентства, продавшего билет, например Corel travel.
ticket_number	string	14-значный номер билета. Должен содержать 3-значный код билета, 4-значный номер формы, 6-значный серийный номер и контрольное число, например 390 5241 025377 1.
booking_number	string	Код брони, например DKZVUA.
restricted_ticked_indicator	string	Если билет можно вернуть - 0. Если вернуть нельзя - 1.
legs	array	Список перелетов, каждый элемент которого состоит из:
airline_code	string	2-символьный IATA код авиакомпании, например B2.
stop_over_code	string	IATA код длительности пересадки. Если пересадка больше 24 часов, то значение параметра O или пусто. Если аэропорт является транзитным, то значение параметра X.
flight_number	string	Номер рейса, например A3 971.
departure_date_time	string	Время и дата вылета, например 2014-05-26T05:15:00.
arrival_date_time	string	Время и дата прибытия, например 2014-05-26T07:30:00.
originating_country	string	Страна вылета, например RU.
originating_city	string	Город вылета, например Moscow.
originating_airport_code	string	3-значный код аэропорта вылета, например DME.
destination_country	string	Страна прилета, например Greece.
destination_city	string	Город прилета, например Athens.
destination_airport_code	string	3-значный код аэропорта прилета, например ATH.
coupon	string	Номер скидочного купона, если был применен.
class	string	Класс полета, 1-значный IATA код, например C.
passengers	array	Список пассажиров, каждый элемент которого состоит из:
first_name	string	Имя пассажира, например KONSTANTIN.
last_name	string	Фамилия пассажира, например IVANOV.

Пример запроса

{
  "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": "Привязать карту",
      "button_next_text": "Вернуться в магазин",
      "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"
    }
  }
}

Пример запроса с дополнительным текстом и без перенаправления на результирующую страницу оплаты

{
  "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": ["Первая строка", "Вторая строка"]
      }
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}

Пример запроса с информацией о продаже авиабилетов и тур путевок

{
  "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": "Привязать карту",
      "button_next_text": "Вернуться в магазин",
      "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": "Athems",
            "destination_airport_code": "ATH",
            "coupon": "coupon code",
            "class": "C"
          }
        ],
        "passengers":[
          {
            "first_name": "KONSTANTIN",
            "last_name": "IVANOV"
          },
          {
            "first_name": "JULIA",
            "last_name": "IVANOVA"
          }
        ]
      }
    }
  }
}

Пример запроса с 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"
    }
  }
}

Ответ

Параметры ответа копируют параметры запроса за исключением дополнительных:

Параметр	Тип	Описание
checkout	object
token * обязательный	string	Токен платежа.
redirect_url * обязательный	string	URL платежного виджета, на который необходимо перенаправить покупателя для оплаты заказа, связанного с созданным токеном платежа.

Пример ответа

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

Пример ответа об ошибке

{
  "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"
}