Перейти к содержанию

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

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

Запрос

Отправьте 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"
}