Создание токена платежа
Для использования страницы оплаты или платежного виджета торговцу требуется создать токен платежа.
Запрос
Отправьте POST
запрос на https://checkout.begateway.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 - Demo PSP вернет токен карты для проведения последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D Secure; oneclick - Demo PSP вернет токен карты для осуществления последующих платежей по схеме one-click. Demo PSP будет показывать пользователю страницу оплаты с уже частично заполненными реквизитами карты. Для завершения платежа пользователю достаточно ввести проверочный код карты CVC/CVV и пройти авторизацию по протоколу 3-D Secure;credit - Demo PSP вернет токен карты для осуществления операций выплаты;card_on_file - Demo PSP вернет токен карты, чтобы вы могли сохранить ее на профайле пользователя и использовать этот токен для последующих операций по списанию денег с карты за оказанные услуги или проданные товары. Ознакомьтесь ниже с секцией 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 | По завершении операции Demo PSP показывает страницу результата операции на заданное количество секунд и затем автоматически перенаправит покупателя обратно на сайт торговца. Если параметр равен 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 | Секция информации о покупателе. Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции. |
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 - оплата банковской картойДля остальных значений массива смотрите значение параметра type в описаниии альтернативных способов оплаты.Если перечисленный способ оплаты требует дополнительных параметров, то сформируйте объект, где имя ключа - это значение type данного способа оплаты, а внутренние параметры указаны так, как приведено в описании альтернативных способов оплаты.Например, для способа оплаты c типом apm и параметром channel добавьте следующий объект:apm : { channel: "ONLINE" } .Отображение Apple Pay, Google Pay и Samsung 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.begateway.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"
}