Download OpenAPI specification:Download
Hosted Payment Page - это програмный интерфейс, который позволяет мерчантам принимать электронные платежи на веб-сайте или веб-приложении, без необходимости внедрения сложных технических решений.
Для начала работы необходимо заполнить настройки в личном кабинете на странице настройки
Название | Описание |
---|---|
Callback URL под PayOut | Ссылка на которую будут отправлены данные с информацией о PayOut платеже |
Callback URL под PayIn | Ссылка на которую будут отправлены данные с информацией о PayIn платеже |
Callback URL под Арбитражи | Ссылка на которую будут отправлены данные с информацией о Арбитраже |
URL неудачного ввода | На эту страницу будет перенаправлен покупатель по-умолчанию в случае неуспешной оплаты |
URL успешного ввода | На эту страницу будет перенаправлен покупатель по-умолчанию в случае успешной оплаты |
Для перехода к оплате, Вы должны отправить POST запрос на создание заявки, в ответе от нашего сервера вы получите ссылку на форму, на которую необходимо переадресовать клиента.
Документация по созданию заявки на оплату доступна в секции Создание PayIn заявки
Payment Request API Integration (интеграция с API запросов на оплату) - это способ интеграции электронных платежей в веб-приложения и интернет-магазины, который позволяет пользователям легко и удобно производить платежи через веб-приложения, не покидая их. Этот метод позволяет мерчантам предоставить своим клиентам быстрый и удобный способ оплаты без необходимости перенаправления на сторонние страницы или использования сторонних платежных форм. Используя данный подход, мерчанту необходимо реализовать на своей стороне интерфейс который будет связыватся с нашим API.
Для реализации данного метода интеграции, интегрируйте в свое приложение методы описанные в секции API/PayIn запросы
Ключи для генерации подписей можно посмотреть в личном кабинете на странице настройки
Название | Описание |
---|---|
First secret | Используется для генерации подписи для всех API запросов |
Second secret | Используется для генерации подписи в момент получения callback запроса от нас. |
Для успешной авторизации API запросов необходимо подготовить подпись с помощью First secret
.
Мерчант на своей стороне должен сгенерировать unix timestamp (текущее время в миллисекундах), сформировать строку для подписи {unixTimestamp}:{apiToken}
и подписать ее с помощью first secret
используя алгоритм SHA256
.
Полученную подпись, сгенерированный timestamp и ваш API токен необходимо передать в заголовках запроса:
x-access-signature
- SHA256 подпись подписанная с помощью First secret
x-access-ts
- сгенерированный timestamp (текущее время в миллисекундах), который включен в подпись
x-api-token
- ваш api token.
Примечание: Значение переданное в x-access-ts
в момент запроса должно быть не старше 15 секунд относительно текущего времени.
MY_FIRST_SECRET
MY_API_TOKEN
{
'x-access-signature': 'd2f1c81f2a1fc4182cec0c4360c38ce6cf8bce603a15e6eec5979f6af01363d5',
'x-access-ts': 1709200638686,
'x-api-token': 'MY_API_TOKEN'
}
import * as crypto from "crypto";
const generateSignature = (
rawSignature,
secret
) => {
return crypto
.createHmac("sha256", secret)
.update(rawSignature)
.digest("hex");
}
const generateRequestHeaders = () => {
// populate these values from the env or your config service
const apiToken = "MY_API_TOKEN";
const firstSecret = "MY_FIRST_SECRET";
const timestamp = 1709201276442; // new Date().getTime()
const rawSignature = `${timestamp}:${apiToken}`;
const signature = generateSignature(rawSignature, firstSecret);
return {
"x-access-signature": signature,
"x-access-ts": timestamp,
"x-api-token": apiToken
};
}
console.log(generateRequestHeaders());
<?php
function generateSignature($rawSignature, $secret) {
return hash_hmac('sha256', $rawSignature, $secret);
}
function generateRequestHeaders() {
// populate these values from the env or your config service
$apiToken = "MY_API_TOKEN";
$firstSecret = "MY_FIRST_SECRET";
$timestamp = 1709201276442; // floor(microtime(true) * 1000);
$rawSignature = $timestamp . ':' . $apiToken;
$signature = generateSignature($rawSignature, $firstSecret);
return [
'x-access-signature' => $signature,
'x-access-ts' => $timestamp,
'x-api-token' => $apiToken
];
}
print_r(generateRequestHeaders());
?>
using System;
using System.Security.Cryptography;
using System.Text;
using System.Collections.Generic;
class Program
{
static string GenerateSignature(string rawSignature, string secret)
{
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
{
byte[] signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawSignature));
return BitConverter.ToString(signatureBytes).Replace("-", "").ToLower();
}
}
static string[] GenerateRequestHeaders()
{
// populate these values from the env or your config service
string apiToken = "MY_API_TOKEN";
string firstSecret = "MY_FIRST_SECRET";
long timestamp = 1709201276442; // DateTimeOffset.Now.ToUnixTimeMilliseconds();
string rawSignature = $"{timestamp}:{apiToken}";
string signature = GenerateSignature(rawSignature, firstSecret);
return new string[] {
$"x-access-signature: {signature}",
$"x-access-ts: {timestamp}",
$"x-api-token: {apiToken}"
};
}
static void Main(string[] args)
{
string[] headers = GenerateRequestHeaders();
foreach (string header in headers)
{
Console.WriteLine(header);
}
}
}
Подпись для оповещений используется для проверки подлинности запроса, который приходит на ваш сервер.
На ваш сервер в заголовке x-access-signature
будет передана подпись, которую необходимо сверить с подписью, которую вы сгенерировали на вашей стороне.
Значение x-access-signature
является HMAC SHA256
подписью подписанную с помощью Second secret
, в которую входит все переданное тело запроса.
import * as crypto from "crypto";
const generateSignature = (
rawSignature,
secret
) => {
return crypto
.createHmac("sha256", secret)
.update(rawSignature)
.digest("hex");
}
const validateSignature = (receivedSignature, receivedPayload) => {
const secondSecret = "MY_SECOND_SECRET";
const signature = generateSignature(JSON.stringify(receivedPayload), secondSecret);
if (receivedSignature === signature) {
return true;
}
return false;
}
const signatureHeaderValue = "c47f8bbe4ba6d2ca418155f3c4e390d2f4484960389275cfd75a952227cd6c12";
const payload = {
internal_id: 1,
status: -2,
amount: '501253',
is_reprocessed: false,
target_address: '0000********0000',
formatted_amount: '5012.53',
transaction_amount: '501253',
currency_id: 'RUB',
method_id: 'CARD_RUB',
fields_data: { 'card-mask': { value: '4242********4242' } },
operation_type: 1,
order_id: 'my_id1'
}
console.log("Is signature valid", validateSignature(signatureHeaderValue, payload));
<?php
function generateSignature($rawSignature, $secret) {
return hash_hmac("sha256", $rawSignature, $secret);
}
function validateSignature($receivedSignature, $receivedPayload) {
$secondSecret = "MY_SECOND_SECRET";
$signature = generateSignature(json_encode($receivedPayload), $secondSecret);
return $receivedSignature === $signature;
}
$signatureHeaderValue = "c47f8bbe4ba6d2ca418155f3c4e390d2f4484960389275cfd75a952227cd6c12";
$payload = array(
"internal_id" => 1,
"status" => -2,
"amount" => '501253',
"is_reprocessed" => false,
"target_address" => '0000********0000',
"formatted_amount" => '5012.53',
"transaction_amount" => '501253',
"currency_id" => 'RUB',
"method_id" => 'CARD_RUB',
"fields_data" => array('card-mask' => array("value" => '4242********4242')),
"operation_type" => 1,
"order_id" => 'my_id1'
);
echo "Is signature valid: " . (validateSignature($signatureHeaderValue, $payload) ? 'true' : 'false');
?>
using System;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json.Linq;
public class SignatureHelper
{
private static string GenerateSignature(string rawSignature, string secret)
{
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
{
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawSignature));
return BitConverter.ToString(hash).Replace("-", "").ToLower();
}
}
private static bool ValidateSignature(string receivedSignature, object receivedPayload)
{
const string secondSecret = "MY_SECOND_SECRET";
string signature = GenerateSignature(Newtonsoft.Json.JsonConvert.SerializeObject(receivedPayload), secondSecret);
return receivedSignature.Equals(signature, StringComparison.OrdinalIgnoreCase);
}
public static void Main(string[] args)
{
string signatureHeaderValue = "c47f8bbe4ba6d2ca418155f3c4e390d2f4484960389275cfd75a952227cd6c12";
var payload = new JObject
{
{ "internal_id", 1 },
{ "status", -2 },
{ "amount", "501253" },
{ "is_reprocessed", false },
{ "target_address", "0000********0000" },
{ "formatted_amount", "5012.53" },
{ "transaction_amount", "501253" },
{ "currency_id", "RUB" },
{ "method_id", "CARD_RUB" },
{ "fields_data", new JObject
{
{ "card-mask", new JObject
{
{ "value", "4242********4242" }
}
}
}
},
{ "operation_type", 1 },
{ "order_id", "my_id1" }
};
Console.WriteLine("Is signature valid: " + ValidateSignature(signatureHeaderValue, payload));
}
}
[HttpPost("callback-handler")]
public async Task<IActionResult> CallbackHandler()
{
var signatureHeader = Request.Headers["x-access-signature"];
var signature = signatureHeader.FirstOrDefault();
if (string.IsNullOrEmpty(signature))
{
return BadRequest("No signature");
}
var rawBody = await new StreamReader(Request.Body).ReadToEndAsync();
var bodyObject = JObject.Parse(rawBody);
if(!SignatureHelper.ValidateSignature(signature, bodyObject))
{
return BadRequest("Invalid signature");
}
return Ok("Valid signature");
}
Для получения оповещений вы должны в настройках своего магазина указать ссылки на которые наша система будет отправлять вам оповещения о изменениях статуса операций.
Оповещения на ваш сервер отправляются через POST запрос, в свою очередь, ваш сервер должен вернуть успешный HTTP Status Code (200-204), если же ваш сервер вернет другой статус код, то наша система отправит повторный запрос через 3 минуты, максимально количество повторных запросов: 2
На ваш сервер так же будет отправлена подпись запроса в заголовке x-access-signature
, подробнее о генерации подписи можно прочитать в секции Генерация подписей для оповещений
Пример Request Body который будет отправлен вам на сервер:
{
internal_id: 1,
status: -2,
amount: '501253',
is_reprocessed: false,
target_address: '0000********0000',
formatted_amount: '5012.53',
transaction_amount: ''501253'',
currency_id: 'RUB',
method_id: 'CARD_RUB',
fields_data: { 'card-mask': { value: '4242********4242' } },
operation_type: 1,
order_id: 'my_id1'
}
Описание:
status | Int | Статус платежа |
---|---|---|
status | Int | Статус платежа |
internal_id | Int | Идентификатор платежа в нашей системе |
amount | string | Сумма платежа |
Is_reprocessed | bool | Является ли платеж повторно-обработанным (см. Описание ниже) |
target_address | string|null | Адрес куда перевел деньги пользователь |
formatted_amount | string | Сумма платежа (отформатированная) |
transaction_amount | string | Сумма которая была добавлена на ваш кошелек |
currency_id | string | Валюта платежа |
method_id | string | Выбранный метод платежа |
fields_data | object | Динамические поля |
operation_type | Int | Тип платежа (1 – PayIn, 2 - PayOut) |
order_id | string | ID платежа в вашей системе |
Повторно-обработанные платежи:
Платеж может быть повторно обработан, после неуспешного/просроченного статуса, чтобы определить такие платежи в запрос подается параметр “is_reprocessed”, который нужно дополнительно обработать.
Пример повторно-обработанного платежа:
Пользователь создает заявку на сумму 1000 RUB, но оплачивает только 900 RUB, в этом случае саппорт, обновляет сумму заявки на 900 RUB, а затем на ваш сервер отправляется дополнительный колбэк, где будет указана новая сумма. (ID платежа и все остальные данные остаются теми же, что были переданы в первый раз)
const crypto = require('crypto');
const generateSignature = (
rawSignature,
secret
) => {
return crypto
.createHmac("sha256", secret)
.update(rawSignature)
.digest("hex");
}
const validateSignature = (receivedSignature, receivedPayload) => {
const secondSecret = "MY_SECOND_SECRET";
const signature = generateSignature(JSON.stringify(receivedPayload), secondSecret);
if (receivedSignature === signature) {
return true;
}
return false;
}
const handleRequest = () => {
const signatureHeaderValue = "c47f8bbe4ba6d2ca418155f3c4e390d2f4484960389275cfd75a952227cd6c12";
const callbackData = {
internal_id: 1,
status: -2,
amount: '501253',
is_reprocessed: false,
target_address: '0000********0000',
formatted_amount: '5012.53',
transaction_amount: '501253',
currency_id: 'RUB',
method_id: 'CARD_RUB',
fields_data: { 'card-mask': { value: '4242********4242' } },
operation_type: 1,
order_id: 'my_id1'
}
const isSignatureValid = validateSignature(signatureHeaderValue, callbackData);
if (!isSignatureValid) {
throw new Error("Invalid signature");
}
if (callbackData.is_reprocessed) {
// handle reprocessed payment
return "ok";
}
if (callbackData.status === 0) {
// handle pending payment
return "ok";
}
if (callbackData.status < 0) {
// handle failed payment
return "ok";
}
if (callbackData.status >= 100) {
// handle successful payment
return "ok";
}
throw new Error("Invalid status");
}
Пример Request Body который будет отправлен вам на сервер:
{
status: -3,
internal_id: 1,
amount: '500000',
formatted_amount: '5000',
transaction_amount: '0',
currency_id: 'RUB',
method_id: 'TESTB_RUB',
fields_data: { 'card-number': { value: '4002690000000008' } },
operation_type: 2,
order_id: 'MERCHANT_ORDER_ID'
}
Описание:
status | Int | Статус платежа |
---|---|---|
status | Int | Статус платежа |
internal_id | Int | ID платежа в нашей системе |
amount | string | Сумма платежа |
formatted_amount | string | Сумма платежа (отформатированная) |
transaction_amount | string | Сумма которая была добавлена на ваш кошелек |
currency_id | string | Валюта платежа |
method_id | string | Выбранный метод платежа |
fields_data | object | Поля введенные в момент создания платежа |
operation_type | Int | Тип платежа (1 – PayIn, 2 - PayOut) |
order_id | string | ID платежа в системе мерчанта |
Оповещения о закрытых арбитражах будут отправлены на callback url
который указан в настройках
Оповещения отправляются только для арбитражей созданных через API Прикрепление чека и комментария к PayIn заявке с подачей параметра should_notify_merchant=true
Пример Request Body который будет отправлен вам на сервер:
{
operation_id: 597803,
order_id: '1702637068',
arbitrage_id: 1155,
operation_status: 100,
operation_type: 1,
operation_amount: '55500',
arbitrage_status: 100,
arbitrage_status_purpose: 'Успешно оплачено'
}
Описание:
status | Int | Статус платежа |
---|---|---|
operation_id | Int | ID платежа в нашей системе |
order_id | string | ID платежа в системе мерчанта |
arbitrage_id | Int | ID арбитража |
operation_status | Int | Текущий статус операции |
operation_type | Int | Тип платежа (1 – PayIn, 2 - PayOut) |
operation_amount | string | Сумма платежа |
arbitrage_status | Int | Статус арбитража (100 - Оплачено, -1 - Не оплачено) |
arbitrage_status_purpose | string | Причина с которой был закрыт арбитраж |
Для защиты вашего обработчика вы можете использовать следующие правила:
ID статуса | Описание |
---|---|
-3 | Платеж завершен с ошибкой (Failed) |
-2 | Платеж отменен (Rejected) |
-1 | Срок платежа истёк (Expired) |
0 | Ожидание (Pending) |
1 | Ожидание заполнения дополнительной информации. Например: верификация почты (Waiting) |
100 | Платеж успешно завершен (Success) |
В зависимости от выбранного метода платежа, платежные реквизиты могут состоять из следующих структур:
Структура 1.:
"payment_credentials": {
"card": "0000000000000000",
"comment": ""
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.card | string | Номер карты куда должен перевести деньги пользователь |
payment_credentials.comment | string|undefined | Обязательный комментарий к платежу |
Структура 2.:
"payment_credentials": {
"card": "0000000000000000",
"name": "Card Holder Name",
"exp_date": "12/24"
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.card | string | Номер карты куда должен перевести деньги пользователь |
payment_credentials.name | string | Имя держателя карты |
payment_credentials.exp_date | string | Срок действия карты |
Структура 3.:
"payment_credentials": {
"url": "https://google.com",
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.url | string | Ссылка на которую нужно перенаправить пользователя |
Структура 4.:
"payment_credentials": {
"iban": "IBAN",
"name": "Card Holder Name",
"last_card_digits": "0000",
"bank_name": "Сбербанк"
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.iban | string | IBAN счет куда должен перевести деньги пользователь |
payment_credentials.name | string | Имя держателя счета |
payment_credentials.last_card_digits | string | Последние 4 цифры карты |
payment_credentials.bank_name | string | Название банка |
Структура 5.:
"payment_credentials": {
"phone_number": "798711111111",
"bank_name": "Bank name",
"name": "Card holder name"
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.phone_number | string | Номер куда должен перевести деньги пользователь |
payment_credentials.bank_name | string | Название банка |
payment_credentials.name | string|undefined | Имя держателя счета |
Структура 6.:
"payment_credentials": {
"phone_number": "798711111111",
"sberpay_url": "https://sitelink.com/"
}
"payment_credentials": {
"card": "4242424242424242",
"sberpay_url": "https://sitelink.com/"
}
В зависимости от метода, возвращается либо номер телефона, либо номер карты.
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.phone_number | string | Номер куда должен перевести деньги пользователь |
payment_credentials.card | string | Номер карты куда должен перевести деньги пользователь |
payment_credentials.sberpay_url | string | Ссылка на оплату через SberPay |
Структура 7.:
"payment_credentials": {
"account_number": "40000000000000000000",
"bank_name": "Bank name"
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.account_number | string | Номер счета куда должен перевести деньги пользователь |
payment_credentials.bank_name | string | Название банка |
Структура 8.:
"payment_credentials": {
"phone_number": "798711111111",
"operator_name": "МТС (Мобильный оператор)"
}
Описание:
Название параметра | Тип | Описание |
---|---|---|
payment_credentials.phone_number | string | Номер куда должен перевести деньги пользователь |
payment_credentials.operator_name | string | Название оператора связи |
Динамические поля нужны для подачи значений введенных пользователем в момент создания или подтверждения заявки.
Типы заполнения полей (filling_type):
before_creation
– Поля которые нужно подать в момент создания заявкиafter_creation
– Поля которые нужно подать в момент подтверждение заявки пользователемЕсли для выбранного метода динамические поля отсутствуют, то значит ничего подавать не нужно.
В случае осуществления PayIn платежей, эти поля заполняет пользователь в форме оплаты.
В случае осуществления PayOut платежа, эти поля заполняет мерчант в момент создания заявки.
Структура динамических полей прикрепленных к методу:
Название параметра | Тип | Описание |
---|---|---|
type | String | Тип поля (email, phone, card, card-mask, card-number, name, bank) |
required | Bool | Является ли поле обязательным для заполнения |
validate_key | String | Идентификатор валидации поля (может быть использован фронтэндом для внедрения валидации поля на форме оплаты) |
filling_type | String | Тип заполнения поля (before_creation, after_creation) |
value | String | Если поле уже было заполнено пользователем, то в этом параметре вернется значение |
Описание полей:
Название поля | Тип заполнения | Описание | Пример |
---|---|---|---|
card-mask | before_creation | маска карты пользователя | { key: “card-mask”, value: { value: “4242********4242” } } |
card-number | before_creation | полный номер карты пользователя | { key: “card-number”, value: { value: “42424242424242” } } |
before_creation | электронная почта пользователя | { key: “email”, value: { value: “abc@gmail.com” } } | |
phone | before_creation | номер телефона пользователя | { key: “phone”, value: { value: “79221110500” } } |
name | before_creation | имя клиента | { key: “name”, value: { value: “Alexey Fomin” } } |
card | before_creation | полные данные карты | { key: “card”, value: { card: “4242424242424242”, year: “26”, month: “05”, cvv: 053 } } |
nspk-code | before_creation | НСПК код банка, используется для осуществления выплат по СБП. Чтобы получить список поддерживаемых кодов используйте запрос: Получить список НСПК кодов | { key: “nspk-code”, value: { value: “100000000111” } } |
bank | before_creation | Идентификатор банка, используется для осуществлений пополнений для определенных ГЕО. Чтобы получить список поддерживаемых банков используйте запрос: Получить список НСПК кодов | { key: “bank”, value: { value: “ZIRAAT” } } |
Для PayIn и PayOut платежей доступен тестовый метод, для того чтобы протестировать работоспособность системы. Чтобы включить тестовый метод, обратитесь к саппорту.
Обратите внимание, что платежи совершенные через тестовый метод, не имеют никакого влияния на Ваш кошелек.
Список карт со статусами для тестирования карточных PayIn операций (метод: TESTB_RUB):
Поле | Значение | Статус | Описание |
---|---|---|---|
card-mask | 4242********4242 | 100 (Success) | Платеж завершится успешно |
card-mask | 5151********5151 | -1 (Expired) | Платеж завершится с ошибкой (просрочен) |
card-mask | 4444********4444 | -2 (Rejected) | Платеж завершится с ошибкой (отклонен) |
card-mask | 5252********5252 | -3 (Failed) | Платеж завершится с ошибкой |
Список карт со статусами для тестирования карточных PayOut операций (метод: TESTB_RUB):
Поле | Значение | Статус | Описание |
---|---|---|---|
card-number | 4400000000000008 | 100 (Success) | Платеж завершится успешно |
card-number | 5555555555554444 | -1 (Expired) | Платеж завершится с ошибкой (просрочен) |
card-number | 4002690000000008 | -2 (Rejected) | Платеж завершится с ошибкой (отклонен) |
card-number | 4000020000000000 | -3 (Failed) | Платеж завершится с ошибкой |
Список номеров со статусами для тестирования СБП PayOut операций (метод: SBPTEST_RUB):
Помимо поля "phone", для этого метода необходимо передавать поле "nspk-code" с одним из значений из списка НСПК кодов
Поле | Значение | Статус | Описание |
---|---|---|---|
phone | 79000000001 | 100 (Success) | Платеж завершится успешно |
phone | 79000000003 | -1 (Expired) | Платеж завершится с ошибкой (просрочен) |
phone | 79000000002 | -2 (Rejected) | Платеж завершится с ошибкой (отклонен) |
phone | 79000000004 | -3 (Failed) | Платеж завершится с ошибкой |
{
"order_id": "my_order_id",
"amount": 50000,
"currency": "RUB",
"method_id": "TESTB_RUB",
"user_context": "0.0.0.0",
"fields_data": [
{
"key": "card-mask",
"value": {
"value": "4242********4242"
}
}
]
{
"order_id": "my_order_id",
"amount": 50000,
"currency": "RUB",
"method_id": "TESTB_RUB",
"fields_data": [
{
"key": "card-number",
"value": {
"value": "4400000000000008"
}
}
]
}
{
"order_id": "my_order_id",
"amount": 50000,
"currency": "RUB",
"method_id": "SBPTEST_RUB",
"fields_data": [
{
"key": "phone",
"value": {
"value": "79000000001"
}
},
{
"key": "nspk-code",
"value": {
"value": "100000000150"
}
}
]
}
После создания, статус операции автоматическии поменяется исходя из переданного значения, на ваш сервер практически сразу придет оповещение с новым статусом. Если было передано значение которое не соответствует списку, то статус платежа обновится на Expired
по истечении времени жизни платежа.
Для осуществления всех апи запросов требуется передавать API ключ - найти его можно в настройках профиля, а так же необходимо передавать хэш подпись и временную метку, подробнее о генерации подписи смотрите в секции "Генерация подписей для API запросов"
URL для апи запросов: https://api.safepays.io
Обязательные заголовки для всех запросов:
x-api-token: YOUR_API_TOKEN
x-access-signature: SIGNATURE
x-access-ts: TIMESTAMP
{- "data": [
- {
- "id": "99b63a1b-c986-4ff3-8a54-7d08f0d0082f",
- "amount": "1073940",
- "hold_amount": "560000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "63.0246848750",
- "sell_usdt_currency": "63.0246848750"
}
}
], - "message": "string"
}
{- "data": {
- "payIn": [
- {
- "id": "CARD_RUB",
- "name": "Visa/Mastercard RUB",
- "fields": [
- {
- "type": "card-mask",
- "required": true,
- "validate_key": "card-mask",
- "filling_type": "before_creation",
- "filling_mode": "default"
}
], - "meta": {
- "icon_url": "/assets/methods/generic-card.png",
- "color": null
}, - "min_amount": "50000",
- "max_amount": "15000000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "63.0246848750"
}
}
], - "payOut": [
- {
- "id": "CARD_RUB",
- "name": "Visa/Mastercard RUB",
- "fields": [
- {
- "type": "card-mask",
- "required": true,
- "validate_key": "card-mask",
- "filling_type": "before_creation",
- "filling_mode": "default"
}
], - "meta": {
- "icon_url": "/assets/methods/generic-card.png",
- "color": null
}, - "min_amount": "50000",
- "max_amount": "15000000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "63.0246848750"
}
}
]
}, - "message": "string"
}
Используйте этот запрос для создания PayIn заявки, в случае HPP интеграции - после создания заявки, вам необходимо перенаправить пользователя на URL указанный в поле form_url
.
Если вы используете свою форму оплаты, то используйте полученные данные из ответа для отображения деталей оплаты на вашей форме, подробнее смотрите в секции Payment Request API Integration
amount | integer Сумма платежа в наименьшем номинале валюты |
order_id | string ID платежа в вашей системе |
currency | string Валюта платежа (Доступные валюты: RUB, KZT, UZS) |
method_id | string Идентификатор метода оплаты |
use_internal_form_for_fields | boolean Использовать внутреннюю форму для заполнения динамических полей (поля с типом заполнения=before_creation), если установлено значение |
traffic_type | string Тип трафика (подробнее уточняйте у вашего менеджера) (не обязательный параметр) |
fields_data | Array of objects Заполненные динамические поля для выбранного метода (поля с типом заполнения=before_creation) (см. cекцию: Динамические поля) |
user_context | string Уникальный идентификатор пользователя, это может быть айпи адрес, хэш строка, идентификатор пользователя в вашей системе и т.д. |
success_url | string URL куда переадресовать пользователя после успешной оплаты |
fail_url | string URL куда переадресовать пользователя после неуспешной оплаты |
{- "amount": 501253,
- "order_id": "my_id1",
- "currency": "RUB",
- "method_id": "TESTB_RUB",
- "use_internal_form_for_fields": false,
- "traffic_type": "string",
- "fields_data": [
- {
- "key": "card-mask",
- "value": {
- "value": "4242********1111"
}
}
], - "user_context": "dc4c84e3b37cd60db7d72e12d4df8b64",
}
{- "data": {
- "hash": "e9a30dec3bd2d99b7c02f091692b7e6dd9591c311f9d1fbe40f093807c6bcfe8",
- "internal_id": 10000,
- "amount": 501253,
- "origin_amount": 501253,
- "status": 0,
- "merchant_order_id": "my_id1",
- "is_user_confirmed": false,
- "can_be_confirmed": false,
- "payment_credentials": {
- "card": "0000000000000000",
- "comment": ""
}, - "method": {
- "id": "302c9606-3375-4791-b8fc-73e83dbcc38e",
- "name": "Test Adapter RUB",
- "flow_type": "default",
- "visibility_type": 1,
- "fields": [
- {
- "type": "card-mask",
- "required": true,
- "validate_key": "card-mask",
- "filling_type": "before_creation",
- "value": {
- "value": "4242********1111"
}
}
], - "meta": {
- "icon_url": "/assets/methods/test-adapter.png"
}, - "min_amount": "50000",
- "max_amount": "15000000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "63.0246848750"
}
}, - "expires_at": "2024-02-29T13:47:48.310Z",
- "created_at": "2024-02-29T13:32:48.280Z",
- "submitted_at": "2024-02-29T13:32:48.310Z"
}, - "message": "string"
}
internal_id required | string ID платежа |
{- "data": {
- "id": 30,
- "merchant_order_id": "ORDER_ID",
- "method_id": "TESTB_RUB",
- "status": -2,
- "amount": "55000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "68.8070856084"
}, - "created_at": "2023-01-17T14:19:00.592Z",
- "finished_at": "2023-01-17T14:25:22.592Z"
}, - "message": "string"
}
internal_id required | string ID платежа |
{- "data": {
- "hash": "e9a30dec3bd2d99b7c02f091692b7e6dd9591c311f9d1fbe40f093807c6bcfe8",
- "internal_id": 10000,
- "amount": 501253,
- "origin_amount": 501253,
- "status": 0,
- "merchant_order_id": "my_id1",
- "is_user_confirmed": false,
- "can_be_confirmed": false,
- "payment_credentials": {
- "card": "0000000000000000",
- "comment": ""
}, - "method": {
- "id": "302c9606-3375-4791-b8fc-73e83dbcc38e",
- "name": "Test Adapter RUB",
- "flow_type": "default",
- "visibility_type": 1,
- "fields": [
- {
- "type": "card-mask",
- "required": true,
- "validate_key": "card-mask",
- "filling_type": "before_creation",
- "value": {
- "value": "4242********1111"
}
}
], - "meta": {
- "icon_url": "/assets/methods/test-adapter.png"
}, - "min_amount": "50000",
- "max_amount": "15000000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "63.0246848750"
}
}, - "expires_at": "2024-02-29T13:47:48.310Z",
- "created_at": "2024-02-29T13:32:48.280Z",
- "submitted_at": "2024-02-29T13:32:48.310Z"
}, - "message": "string"
}
internal_id required | string ID платежа |
fields_data | Array of objects Заполненные динамические поля для выбранного метода (поля с типом заполнения=after_creation) (см. cекцию: Динамические поля) |
{- "fields_data": [ ]
}
{- "data": true,
- "message": "string"
}
Прикрепление чека и комментария к PayIn заявке создаст арбитраж
internal_id required | string ID платежа |
attachment | string <binary> Прикрепленный файл (jpg|jpeg|png|pdf) |
comment | string Комментарий |
should_notify_merchant | boolean Если установлено "true", то мерчант получит уведомление когда арбитраж будет закрыт |
{- "data": {
- "arbitrage_id": 0
}, - "message": "string"
}
sort_dir | string Example: sort_dir=ASC Порядок сортировки (по возрастанию/по убыванию по времени создания заявки) |
page | integer Example: page=1 Номер страницы |
page_limit | integer Example: page_limit=15 Количество записей на 1 странице |
internal_id[] | Array of integers Example: internal_id[]=10&internal_id[]=11 ID платежа в нашей системе |
merchant_order_id[] | Array of strings Example: merchant_order_id[]=MERCHANT_ORDER_ID ID платежа в системе мерчанта |
amount_from | integer Example: amount_from=50000 Сумма платежа от (включительно) |
amount_to | integer Example: amount_to=150000 Сумма платежа до (включительно) |
status | Array of integers Example: status=100&status=200 Статус платежа |
created_from | string Example: created_from=30/12/2022 Дата создания заявки от (формат: DD/MM/YYYY) |
created_to | string Example: created_to=31/12/2022 Дата создания заявки до (формат: DD/MM/YYYY) |
finished_from | string Example: finished_from=30/12/2022 Дата завершения заявки от (формат: DD/MM/YYYY) |
finished_to | string Example: finished_to=31/12/2022 Дата завершения заявки до (формат: DD/MM/YYYY) |
{- "data": {
- "items": [
- {
- "finished_at": "2024-02-28T15:52:44.613Z",
- "expires_at": "2024-02-28T16:07:43.551Z",
- "submitted_at": "2024-02-28T15:52:43.551Z",
- "created_at": "2024-02-28T15:51:41.078Z",
- "updated_at": "2024-02-28T15:52:44.613Z",
- "id": 598256,
- "merchant_order_id": "my_id1",
- "amount": "500000",
- "is_amount_changed": false,
- "is_user_confirmed": false,
- "user_context": "0.0.0.0",
- "comment": 0,
- "currency_id": "RUB",
- "status": 100,
- "merchant_received_amount_fee": 0,
- "fields_data": {
- "card-mask": {
- "value": "4242********4242"
}
}, - "payment_credentials": {
- "card": "0000********0000"
}, - "operator_method": {
- "name": "Test Adapter TEST RUB",
- "slug": "TESTB_RUB"
}
}
], - "count": 1
}, - "message": "string"
}
order_id | string ID платежа в вашей системе |
amount | integer Сумма платежа в наименьшем номинале валюты |
currency | string Валюта платежа |
method_id | string Идентификатор PayOut метода |
fields_data | Array of objects Динамические поля платежа (см. секцию Динамические поля) |
{- "order_id": "MERCHANT_ORDER_ID",
- "amount": 500000,
- "currency": "RUB",
- "method_id": "TESTB_RUB",
- "fields_data": [
- {
- "key": "card-number",
- "value": {
- "value": "4002690000000008"
}
}
]
}
{- "data": {
- "status": 0,
- "amount": "500000",
- "currency_id": "RUB",
- "merchant_order_id": "MERCHANT_ORDER_ID_123456",
- "internal_id": 10000
}, - "message": "string"
}
internal_id required | string ID платежа |
{- "data": {
- "id": 30,
- "merchant_order_id": "ORDER_ID",
- "method_id": "TESTB_RUB",
- "status": -2,
- "amount": "55000",
- "currency": {
- "key": "RUB",
- "name": "Russian Ruble",
- "symbol": "₽",
- "usdt_currency": "68.8070856084"
}, - "created_at": "2023-01-17T14:19:00.592Z",
- "finished_at": "2023-01-17T14:25:22.592Z"
}, - "message": "string"
}
sort_dir | string Example: sort_dir=ASC Порядок сортировки (по возрастанию/по убыванию по времени создания заявки) |
page | integer Example: page=1 Номер страницы |
page_limit | integer Example: page_limit=15 Количество записей на 1 странице |
internal_id[] | Array of integers Example: internal_id[]=10&internal_id[]=11 ID платежа в нашей системе |
merchant_order_id[] | Array of strings Example: merchant_order_id[]=MERCHANT_ORDER_ID ID платежа в системе мерчанта |
amount_from | integer Example: amount_from=50000 Сумма платежа от (включительно) |
amount_to | integer Example: amount_to=150000 Сумма платежа до (включительно) |
status | Array of integers Example: status=100&status=200 Статус платежа |
created_from | string Example: created_from=30/12/2022 Дата создания заявки от (формат: DD/MM/YYYY) |
created_to | string Example: created_to=31/12/2022 Дата создания заявки до (формат: DD/MM/YYYY) |
finished_from | string Example: finished_from=30/12/2022 Дата завершения заявки от (формат: DD/MM/YYYY) |
finished_to | string Example: finished_to=31/12/2022 Дата завершения заявки до (формат: DD/MM/YYYY) |
{- "data": {
- "items": [
- {
- "finished_at": "2022-12-29T13:23:17.760Z",
- "created_at": "2022-12-29T13:08:17.734Z",
- "updated_at": "2022-12-29T13:23:17.760Z",
- "id": 30,
- "merchant_order_id": "MERCHANT_ORDER_ID",
- "amount": "100000",
- "currency_id": "RUB",
- "status": 100,
- "merchant_fee": "1000",
- "fields_data": {
- "card-number": {
- "value": "4002690000000008"
}
}, - "operator_method": {
- "name": "Test Adapter RUB",
- "slug": "TESTB_RUB"
}
}
], - "count": 1
}, - "message": "string"
}
Получить актуальный курс обмена фиата в криптовалюту под вывод
merchant_wallet_id | uuid Идентификатор фиатного кошелька мерчанта (список кошельков с идентификаторами можно получить используя запрос Получить балансы кошельков) |
amount | string Сумма для которой нужно получить обменный курс в наименьшем эквиваленте валюты |
{- "merchant_wallet_id": null,
- "amount": "string"
}
{- "data": {
- "query_amount": "100000",
- "converted_amount": "10.697",
- "exchange_rate": 93.4815,
- "base_currency": "RUB",
- "target_currency": "USDT"
}, - "message": "string"
}
merchant_wallet_id | uuid Идентификатор фиатного кошелька мерчанта (список кошельков с идентификаторами можно получить используя запрос Получить балансы кошельков) |
amount | string Сумма для которой нужно получить обменный курс в наименьшем эквиваленте валюты |
crypto_address | string Адрес кошелька USDT TRC20 |
{- "merchant_wallet_id": null,
- "amount": "string",
- "crypto_address": "string"
}
{- "data": {
- "created_at": "2023-08-16T12:55:21.404Z",
- "updated_at": "2023-08-16T12:55:21.404Z",
- "status": 0,
- "id": 2313,
- "merchant_wallet_id": "99b63a1b-c986-4ff3-8a54-7d08f0d0082f",
- "amount": "100000",
- "merchant_id": 1,
- "crypto_currency_id": "USDT",
- "fields_data": {
- "crypto_address": "CRYPTO_ADDRESS_HERE"
}, - "currency_amount": "10.697"
}, - "message": "string"
}