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

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

Запрос

Отправьте POST запрос на https://panel.pay-cross.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` - PayCross вернет токен карты для проведения последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D Secure; `oneclick` - PayCross вернет токен карты для осуществления последующих платежей по схеме one-click. PayCross будет показывать пользователю страницу оплаты с уже частично заполненными реквизитами карты. Для завершения платежа пользователю достаточно ввести проверочный код карты CVC/CVV и пройти авторизацию по протоколу 3-D Secure; `credit` - PayCross вернет токен карты для осуществления операций выплаты; `card_on_file` - PayCross вернет токен карты, чтобы вы могли сохранить ее на профайле пользователя и использовать этот токен для последующих операций по списанию денег с карты за оказанные услуги или проданные товары. Ознакомьтесь ниже с секцией `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	По завершении операции PayCross показывает страницу результата операции на заданное количество секунд и затем автоматически перенаправит покупателя обратно на сайт торговца. Если параметр равен `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` - оплата банковской картой Для остальных значений массива смотрите значение параметра `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": "[email protected]"
    }
  }
}

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

{
  "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": "[email protected]"
    }
  }
}

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

{
  "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": "[email protected]"
    },
    "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://panel.pay-cross.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"
}