Документация (2.0.5)

Download OpenAPI specification:Download

1. Hosted Payment Page (HPP)

Hosted Payment Page - это програмный интерфейс, который позволяет мерчантам принимать электронные платежи на веб-сайте или веб-приложении, без необходимости внедрения сложных технических решений.

Процесс взаимодействия с HPP (flow)

HPP flow

Настройка учетной записи мерчанта

Для начала работы необходимо заполнить настройки в личном кабинете на странице настройки

Название Описание
Callback URL под PayOut Ссылка на которую будут отправлены данные с информацией о PayOut платеже
Callback URL под PayIn Ссылка на которую будут отправлены данные с информацией о PayIn платеже
Callback URL под Арбитражи Ссылка на которую будут отправлены данные с информацией о Арбитраже
URL неудачного ввода На эту страницу будет перенаправлен покупатель по-умолчанию в случае неуспешной оплаты
URL успешного ввода На эту страницу будет перенаправлен покупатель по-умолчанию в случае успешной оплаты

Реализация

Для перехода к оплате, Вы должны отправить POST запрос на создание заявки, в ответе от нашего сервера вы получите ссылку на форму, на которую необходимо переадресовать клиента.

Документация по созданию заявки на оплату доступна в секции Создание PayIn заявки

2. Payment Request API Integration (H2H)

Payment Request API Integration (интеграция с API запросов на оплату) - это способ интеграции электронных платежей в веб-приложения и интернет-магазины, который позволяет пользователям легко и удобно производить платежи через веб-приложения, не покидая их. Этот метод позволяет мерчантам предоставить своим клиентам быстрый и удобный способ оплаты без необходимости перенаправления на сторонние страницы или использования сторонних платежных форм. Используя данный подход, мерчанту необходимо реализовать на своей стороне интерфейс который будет связыватся с нашим API.

Процесс взаимодействия с PRA (flow)

  1. Создание платежа [Документация к запросу]
    Обязательный шаг, в который подается выбранный метод оплаты, и заполненные динамические поля.
  2. Страница с реквизитами для оплаты
    После создания платежа, мерчант должен отобразить пользователю страницу с реквизитами для оплаты, которые были получены в ответе на запрос создания платежа.
  3. Обновление статуса заявки [Документация к запросу]
    Чтобы обновить статус заявки, мерчант должен отправить запрос на обновление статуса заявки.
  4. Пользовательские действия на форме
    4.1. Подтверждение оплаты пользователем [Документация к запросу]
    После оплаты заявки пользователем, пользователь может нажать на кнопку подтверждения оплаты, после чего мерчант должен отправить запрос на подтверждение платежа.
    4.2. Отмена заявки пользователем [Документация к запросу]
    Пользователь может отменить заявку, после чего мерчант должен отправить запрос на отмену платежа.
    4.3. Прикрепление чека и комментария к заявке (создание арбитража) [Документация к запросу]
    В случае возникновения проблем с заявкой, пользователь может создать арбитраж, прикрепив чек и комментарий к заявке.

Реализация

Для реализации данного метода интеграции, интегрируйте в свое приложение методы описанные в секции API/PayIn запросы

Генерация подписей

Ключи для генерации подписей можно посмотреть в личном кабинете на странице настройки

Название Описание
First secret Используется для генерации подписи для всех API запросов
Second secret Используется для генерации подписи в момент получения callback запроса от нас.

Генерация подписей для API запросов

Для успешной авторизации 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 секунд относительно текущего времени.

Пример сгенерированной подписи Для генерации этой подписи использовались следующие данные:
First secret = MY_FIRST_SECRET
Api token = MY_API_TOKEN
{
  'x-access-signature': 'd2f1c81f2a1fc4182cec0c4360c38ce6cf8bce603a15e6eec5979f6af01363d5',
  'x-access-ts': 1709200638686,
  'x-api-token': 'MY_API_TOKEN'
}

Пример генерации подписи на javascript/typescript:
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:
<?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());
?>

Пример генерации подписи на c#:
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, в которую входит все переданное тело запроса.

Пример генерации подписи на javascript/typescript:
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:
<?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');
?>

Пример генерации подписи на c#:
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));
  }
}

Пример обработчика запроса на c#:
[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, подробнее о генерации подписи можно прочитать в секции Генерация подписей для оповещений

Оповещение о PayIn платеже

Пример 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 платежа и все остальные данные остаются теми же, что были переданы в первый раз)

Пример обработки платежа на javascript:
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");
}

Оповещение о PayOut платеже

Пример 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 Причина с которой был закрыт арбитраж

Общее

Список статусов

Для защиты вашего обработчика вы можете использовать следующие правила:

  • <0 = Отказы/Ошибки
  • 0-99 = платеж находится в ожидании в каком-либо виде
  • >=100 = Платеж успешно завершен
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 Название оператора связи

Динамические поля (fields_data)

Динамические поля нужны для подачи значений введенных пользователем в момент создания или подтверждения заявки.

Типы заполнения полей (filling_type):

  1. before_creation – Поля которые нужно подать в момент создания заявки
  2. 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” } }
email 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) Платеж завершится с ошибкой

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

Пример запроса для PayIn операции (TESTB_RUB):
{
  "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"
          }
      }
  ]
Пример запроса для PayOut операции (TESTB_RUB):
{
  "order_id": "my_order_id",
  "amount": 50000,
  "currency": "RUB",
  "method_id": "TESTB_RUB",
  "fields_data": [
      {
          "key": "card-number",
          "value": {
              "value": "4400000000000008"
          }
      }
  ]
}
Пример запроса для PayOut операции (SBPTEST_RUB):
{
  "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 ключ - найти его можно в настройках профиля, а так же необходимо передавать хэш подпись и временную метку, подробнее о генерации подписи смотрите в секции "Генерация подписей для API запросов"

URL для апи запросов: https://api.safepays.io

Обязательные заголовки для всех запросов:
x-api-token: YOUR_API_TOKEN
x-access-signature: SIGNATURE
x-access-ts: TIMESTAMP

Общие запросы

Получить балансы кошельков

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "string"
}

Получить список доступных методов

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получить список кодов НСПК

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "string"
}

Получить список банков

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
query Parameters
currency
string
Example: currency=RUB

Валюта платежа в формате ISO 4217

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "string"
}

PayIn операции

Создание PayIn заявки

Используйте этот запрос для создания PayIn заявки, в случае HPP интеграции - после создания заявки, вам необходимо перенаправить пользователя на URL указанный в поле form_url.

Если вы используете свою форму оплаты, то используйте полученные данные из ответа для отображения деталей оплаты на вашей форме, подробнее смотрите в секции Payment Request API Integration

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
Request Body schema: application/json
amount
integer

Сумма платежа в наименьшем номинале валюты

order_id
string

ID платежа в вашей системе

currency
string

Валюта платежа (Доступные валюты: RUB, KZT, UZS)

method_id
string

Идентификатор метода оплаты

use_internal_form_for_fields
boolean

Использовать внутреннюю форму для заполнения динамических полей (поля с типом заполнения=before_creation), если установлено значение true, то все динамические поля будут заполнены пользователем на нашей форме оплаты, в случае если передано значение false, то мерчант должен самостоятельно передать все необходимые значения в параметр fields_data

traffic_type
string

Тип трафика (подробнее уточняйте у вашего менеджера) (не обязательный параметр)

fields_data
Array of objects

Заполненные динамические поля для выбранного метода (поля с типом заполнения=before_creation) (см. cекцию: Динамические поля)
Этот параметр обязателен, если use_internal_form_for_fields установлено в false, и выбранный метод оплаты имеет динамические поля

user_context
string

Уникальный идентификатор пользователя, это может быть айпи адрес, хэш строка, идентификатор пользователя в вашей системе и т.д.
Некоторые методы требуют передачи определенного формата этого параметра, подробнее уточняйте у вашего менеджера

success_url
string

URL куда переадресовать пользователя после успешной оплаты

fail_url
string

URL куда переадресовать пользователя после неуспешной оплаты

Responses

Request samples

Content type
application/json
{
  • "amount": 501253,
  • "order_id": "my_id1",
  • "currency": "RUB",
  • "method_id": "TESTB_RUB",
  • "use_internal_form_for_fields": false,
  • "traffic_type": "string",
  • "fields_data": [
    ],
  • "user_context": "dc4c84e3b37cd60db7d72e12d4df8b64",
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получить данные о PayIn операции по ID

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получить полные данные о PayIn операции по ID

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получить статус PayIn платежа

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Отменить PayIn платеж

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Response samples

Content type
application/json
{
  • "data": true,
  • "message": "string"
}

Подтвердить PayIn платеж

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Request Body schema: application/json
fields_data
Array of objects

Заполненные динамические поля для выбранного метода (поля с типом заполнения=after_creation) (см. cекцию: Динамические поля)

Responses

Request samples

Content type
application/json
{
  • "fields_data": [ ]
}

Response samples

Content type
application/json
{
  • "data": true,
  • "message": "string"
}

Прикрепить чек и комментарий к PayIn заявке

Прикрепление чека и комментария к PayIn заявке создаст арбитраж

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Request Body schema: multipart/form-data
attachment
string <binary>

Прикрепленный файл (jpg|jpeg|png|pdf)

comment
string

Комментарий

should_notify_merchant
boolean

Если установлено "true", то мерчант получит уведомление когда арбитраж будет закрыт
Подробнее смотрите в разделе Оповещения об арбитражах

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Редирект пользователя обратно к мерчанту

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Получить список PayIn операций

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

PayOut операции

Создать запрос на вывод средств пользователю

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
Request Body schema: application/json
order_id
string

ID платежа в вашей системе

amount
integer

Сумма платежа в наименьшем номинале валюты

currency
string

Валюта платежа

method_id
string

Идентификатор PayOut метода

fields_data
Array of objects

Динамические поля платежа (см. секцию Динамические поля)

Responses

Request samples

Content type
application/json
{
  • "order_id": "MERCHANT_ORDER_ID",
  • "amount": 500000,
  • "currency": "RUB",
  • "method_id": "TESTB_RUB",
  • "fields_data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получить данные о PayOut операции по ID

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
path Parameters
internal_id
required
string

ID платежа

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Получение списка PayOut операций

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Выплаты

Получение курса обмена фиата

Получить актуальный курс обмена фиата в криптовалюту под вывод

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
Request Body schema: application/json
merchant_wallet_id
uuid

Идентификатор фиатного кошелька мерчанта (список кошельков с идентификаторами можно получить используя запрос Получить балансы кошельков)

amount
string

Сумма для которой нужно получить обменный курс в наименьшем эквиваленте валюты

Responses

Request samples

Content type
application/json
{
  • "merchant_wallet_id": null,
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

Создание запроса на выплату в криптовалюте

Authorizations:
(x-api-tokenx-access-signaturex-access-ts)
Request Body schema: application/json
merchant_wallet_id
uuid

Идентификатор фиатного кошелька мерчанта (список кошельков с идентификаторами можно получить используя запрос Получить балансы кошельков)

amount
string

Сумма для которой нужно получить обменный курс в наименьшем эквиваленте валюты

crypto_address
string

Адрес кошелька USDT TRC20

Responses

Request samples

Content type
application/json
{
  • "merchant_wallet_id": null,
  • "amount": "string",
  • "crypto_address": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}