Оплата

Транзакция оплаты - это операция списания средств со счета пользователя в альтернативной платежной системе. Каждая платежная система устанавливает свои условия проведения операции оплаты и имеет собственный механизм списания средств.

Запрос

Для проведения оплаты отправьте POST запрос на https://data.pay-cross.com/beyag/transactions/payments со следующими параметрами:

Параметр	Тип	Описание
request	object
amount * обязательный	integer	Сумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245.
currency * обязательный	string	Валюта транзакции в формате ISO-4217 alpha-3 code. Например, `USD`.
description * обязательный	string	Описание заказа.
test	boolean	`true` или `false`
expired_at	string	Время в формате ISO-8601, до которого действителен платеж. По умолчанию, бессрочно. Формат: YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например 2019), MM – месяц (например 02), DD – день (например 09), hh – часы (например 18), mm – минуты (например 20), ss – секунды (например 45), TZD – часовой пояс (+hh:mm или –hh:mm), например +03:00 для Минска. Если в указанный момент платёж всё ещё не будет оплачен, он будет переведён в статус `expired`.
tracking_id	string	Внутренний идентификатор платежа (номер заказа или покупателя и т.д.) в системе торговца, по которому можно будет отследить платеж в поступившем уведомлении. В параметре может быть отправлено несколько значений, разделенных символом `;`. Например: `"cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f"`. Если в запросе было передано более одного значения `tracking_id`, поиск транзакции в личном кабинете может быть осуществлен по любому из них.
ip	string	IP-адрес клиента, производящего оплату в магазине торговца.
language	string	Язык вашей страницы оформления заказа. Если параметр установлен и уведомление о транзакции по электронной почте включено, PayCross отправит письмо по электронной почте, язык текста которого будет соответсвовать значению параметра `language`. По умолчанию - `en`. Доступные значения параметра `language`.
notification_url	string	URL, на который торговец будет получать уведомления об оплате. Если не указан, уведомления не высылаются.
verification_url	string	URL, на который будут приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции.
return_url * обязательный	string	URL, на который будет возвращен плательщик после завершения операции в платёжной системе.
iframe	boolean	Шлите `true`, если вы на вашем сайте используете оплату через iFrame. Внешняя платёжная система вернет шаблон, который подойдет для открытия в iFrame
customer * условно обязательный	object	Секция информации о покупателе. Проверьте описание платежного метода, чтобы узнать, необходимо ли передавать параметры данной секции.
first_name	string (60)	Имя покупателя.
last_name	string (60)	Фамилия покупателя.
middle_name	string (60)	Отчество покупателя.
email	string	Адрес электронной почты покупателя.
country	string	Страна покупателя в формате ISO 3166-1 alpha-2.
city	string (120)	Город покупателя.
zip	string (40)	Почтовый индекс покупателя.
address	string (510)	Адрес покупателя.
phone	string (200)	Номер телефона покупателя.
birth_date	string	Дата рождения покупателя в формате ISO-8601 (`YYYY-MM-DD`).
device_id	string	Идентификационный номер устройства покупателя.
id_number	string	Номер идентификационного документа покупателя.
method	object	Набор параметров данной секции зависит от того, какую электронную платёжную систему планируется использовать.
type * обязательный	string	Имя платёжной системы или определённый способ оплаты, поддерживаемый подключенной платёжной системой.
token	string	Токен `type` способа оплаты, который был получен в какой-то из предыдущих операций для осуществления быстрого платежа.
additional_data	object	Секция, содержащая дополнительную информацию о платеже.
contract	array	Массив, элементами которого могут быть параметры: `recurring` - PayCross вернет токен способа оплаты для осуществления последующих платежей без повторного ввода необходимых для `type` реквизитов платежа.
receipt_text	array	Текст, который будет добавлен в письмо клиенту. Должен быть представлен как массив строк, например `["Первая строка", "Вторая строка"]`.
customer	object	Секция дополнительной информации о покупателе. Параметры секции зависят от того платежного метода, с помощью которого вы хотите принять оплату от покупателя.
id * условно обязательный	string	ID покупателя. Проверьте описание платежного метода, чтобы узнать, какое значение необходимо передать в этом параметре.
browser	object	Секция параметров браузера клиента.
user_agent * условно обязательный	string	Cтрока агента пользователя текущего браузера. Соответствует параметру `navigator.userAgent` из JavaScript. Смотрите описание параметров платёжного метода, чтобы уточнить, является ли параметр обязательным.

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

{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"description",
      "test": false,
      "expired_at": "2025-01-01T15:00:00+01:00",
      "tracking_id":"your_uniq_number",
      "ip":"127.0.0.1",
      "language":"en",
      "notification_url":"https://merchant.ltd/notification",
      "return_url":"https://merchant.ltd/return",
      "customer":{
        "first_name":"John",
        "last_name":"Doe",
        "middle_name": "Mid",
        "country":"US",
        "city":"Denver",
        "zip":"96002",
        "address":"1st Street",
        "phone":"17777777777",
        "device_id":"12312312321fff67"
      },
      "method":{
        "type": ":method_name"
      }
  }
}

Ответ

Если запрос на оплату принят успешно, в ответ на него придет сообщение, содержащее в строковом виде JSON-объект с дополнительными информационными полями. Такое же сообщение будет отправлено после проведения оплаты в уведомлении на адрес, указанный в notification_url. Полученный в ответе JSON-объект имеет единственный ключ transaction, значением которого является другой JSON-объект со следующими полями:

Параметр	Тип	Описание
transaction	object
uid * обязательный	string	UID обработанной транзакции.
type * обязательный	string	Тип транзакции.
status * обязательный	string	Статус обработанной транзакции.
amount * обязательный	integer	Сумма платежа в минимальных денежных единицах.
currency * обязательный	string	Валюта транзакции в формате ISO-4217 alpha-3 code. Например, `USD`.
description * обязательный	string	Описание платежа.
created_at * обязательный	string	Время создания транзакции в формате ISO-8601.
updated_at * обязательный	string	Время обновления транзакции в формате ISO-8601.
method_type * обязательный	string	Имя платёжной системы из запроса.
receipt_url * обязательный	string	Ссылка на квитанцию обработанной транзакции.
{method name}	object	Набор параметров, специфичный для платёжной системы.
type * обязательный	string	Имя платёжной системы.
token	string	Токен способа оплаты для быстрого совершения платежей в последующих операциях.
qr_code	string	Ссылка на QR код для оплаты.
payment	object
status * обязательный	string	Статус обработанной транзакции.
gateway_id * обязательный	integer	Идентификатор внутреннего платежного шлюза.
ref_id	string	Номер операции в платёжной системе.
message	string	Сообщение от платёжной системы.
bank_code	string	Код результата транзакции на стороне провайдера.
rrn	string	Идентификатор транзакции на стороне провайдера, полученный от третьей стороны.
message	string	Сообщение с результатом запроса.
tracking_id	string	Значение параметра tracking_id из запроса.
test	boolean	`true` или `false`. Транзакция будет тестовой при `true`
language	string	Значение параметра language из запроса.
paid_at	string	Дата проведения транзакции.
billing_address	object	Информация о плательщике.
first_name	string	Имя покупателя.
middle_name	string	Отчество покупателя.
last_name	string	Фамилия покупателя.
country	string	Страна покупателя.
city	string	Город покупателя.
zip	string	Почтовый индекс покупателя.
address	string	Адрес покупателя.
phone	string	Номер телефона покупателя.
customer	object	Секция информации о покупателе.
ip	string	IP-адрес покупателя.
email	string	email покупателя.
form	object	Элементы и атрибуты формы перенаправления на сайт платежной системы (форму с указанными полями и атрибутами необходимо предоставить пользователю для отправки):
action	string	Атрибут `action` HTML-формы;
method	string	Атрибут `method` HTML-формы;
fields	array	Массив данных HTML-формы (каждый элемент массива - объект, список ключей которого см. ниже):
type	string	Тип поля HTML-формы;
name	string	Название поля HTML-формы;
id	string	Идентификатор поля HTML-формы;
value	string	Значение поля HTML-формы;
additional_data	object	Секция, содержащая дополнительную информацию о платеже.

В случае ошибки ответ на запрос будет иметь следующие параметры:

Параметр	Тип	Описание
message * обязательный	string	Сообщение об ошибке;
errors * обязательный	object	Ассоциативный массив (объект) с ключами соответствующими типам ошибок (например system - системная ошибка):
error.{key} * обязательный	array	Массив сообщений об ошибке соответствующего типа. Если ошибка одна (как в примере) - массив будет состоять из одного элемента;

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

{
  "transaction":{
    "uid":"2-52671c8733",
    "type":"payment",
    "status":"successful",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "created_at":"2024-06-11T12:04:59+03:00",
    "updated_at":"2024-06-11T12:04:59+03:00",
    "tracking_id":"tracking_id_000",
    "message":"Successfully processed",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://admin.pay-cross.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    ":method_name":{
      "type":":method_name",
      "token":"55524-1559836037-0-1800"
    },
    "payment":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
      "bank_code": null,
      "rrn": null
    },
    "customer":{
      "ip":"127.0.0.1",
      "email":"[email protected]"
    },
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "phone":17777777777
    }
  }
}

Пример ответа с параметрами формы

{
  "transaction":{
    "status":"pending",
    "type":"payment",
    "uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "amount":1000,
    "currency":"USD",
    "description":"Order #123",
    "tracking_id":"AB8923",
    "created_at":"2024-12-07T14:21:24.420Z",
    "expired_at":"2025-12-07T14:51:240Z",
    "paid_at":"2024-12-07T14:40:120Z",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://admin.pay-cross.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "language":"en",
    "billing_address":{
        "first_name": "Ivan",
        "middle_name": "M",
        "last_name": "Doe",
        "country": "LV",
        "city": "Riga",
        "zip": "LV1024",
        "address": "Brivibas str, 123",
        "phone": "+372500000000"
    },
    "customer":{
        "email":"[email protected]",
        "ip":"127.0.0.7"
    },
    "payment":{
        "ref_id":null,
        "message":null,
        "status":"pending",
        "gateway_id":1,
        "bank_code": null,
        "rrn": null
    },
    ":method_name":{
        "type":":method_name",
        "account":"[email protected]",
    },
    "payment_form":{
        "action":"https://pay.method-name.com",
        "method":"GET",
        "fields":[
            {
              "type":"hidden",
              "name":"sid",
              "id":"sid",
              "value":"185737d3d7f665641ab339ea38dc06bc"
            }
        ]
    }
  }
}

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

{
  "message": "Unknown 'method_name_new' payment method",
  "errors": {
    "system": [
      "System error."
    ]
  }
}

Пример HTML-формы на основе ответа

На основе ответа из примера выше необходимо сформировать и предоставить пользователю для отправки следующую HTML-форму:

<form id="payment-form" action="https://pay.method-name.com" accept-charset="UTF-8" method="get">
  <input name="utf8" type="hidden" value="&#x2713;" />
  <input type="hidden" name="sid" id="sid" value="185737d3d7f665641ab339ea38dc06bc" />
  <input type="submit" name="submit" value="Оплатить">
</form>

Обратите внимание на то, что в ответе выше отсутствует параметры кнопки отправки формы (<input type="submit" name="submit" value="Оплатить">) - её вам необходимо добавить самостоятельно в соответствии с дизайном вашего сайта и языковыми предпочтениями.