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

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

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

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

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

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

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

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

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

{
  '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',
  merchant_cashier_id: 1
}

Описание:

Индикатор изменения суммы платежа:
Сумма платежа может быть изменена в момент создания, либо после неуспешного/просроченного статуса, чтобы определить такие платежи в запрос подается параметр “is_reprocessed”, который нужно дополнительно обработать.

Примеры платежей с измененной суммой:

1. Пользователь создает заявку на сумму 1000 RUB, но оплачивает только 900 RUB, в этом случае саппорт, обновляет сумму заявки на 900 RUB, а затем на ваш сервер отправляется дополнительный колбэк, где будет указана новая сумма. (ID платежа и все остальные данные остаются теми же, что были переданы в первый раз)
2. Пользователь создает заявку на сумму 1000 RUB, и в момент создания сумма была проуникализирована системой автоматически на 1001 RUB. В этом случае в первичном колбэке будет указана сумма 1001 RUB, с индикатором is_reprocessed: true.

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',
  merchant_cashier_id: 1
}

Описание:

Оповещения о закрытых арбитражах будут отправлены на 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: 'Пропуск',
  arbitrage_status_purpose_id: 7,
  merchant_cashier_id: 1
}

Описание:

Статусы PayIn/PayOut операций

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

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

Статусы причин закрытия арбитража

В зависимости от выбранного метода платежа, платежные реквизиты могут состоять из следующих структур:

Структура 1.:

"payment_credentials": {
  "card": "0000000000000000",
  "name": "Card Holder"
}

"payment_credentials": {
 "card": "0000000000000000",
 "bank_name": "Душанбе Сити Банк",
 "name": "Card Holder Name",
 "country_code": "TJ"
}

Описание:

Структура 2.:

"payment_credentials": {
  "card": "0000000000000000",
  "name": "Card Holder Name",
  "exp_date": "12/24"
}

Описание:

Структура 3.:

"payment_credentials": {
  "url": "https://google.com",
}

Описание:

Структура 4.:

"payment_credentials": {
  "iban": "IBAN",
  "name": "Card Holder Name",
  "last_card_digits": "0000",
  "bank_name": "Сбербанк"
}

Описание:

Структура 5.:

"payment_credentials": {
  "phone_number": "798711111111",
  "bank_name": "Bank name",
  "name": "Card holder name"
}

"payment_credentials": {
 "phone_number": "798711111111",
 "bank_name": "СБП Душанбе Сити Банк",
 "country_code": "TJ"
}

Описание:

Структура 6.:

"payment_credentials": {
  "phone_number": "798711111111",
  "sberpay_url": "https://sitelink.com/"
}

"payment_credentials": {
 "card": "4242424242424242",
 "sberpay_url": "https://sitelink.com/"
}

В зависимости от метода, возвращается либо номер телефона, либо номер карты.

Описание:

Структура 7.:

"payment_credentials": {
  "account_number": "40000000000000000000",
  "name": "Card Holder Name",
  "bank_name": "Bank name"
}

Описание:

Структура 8.:

"payment_credentials": {
  "phone_number": "798711111111",
  "operator_name": "МТС (Мобильный оператор)"
}

Описание:

Структура 9.:

"payment_credentials": {
  "nspk_url": "https://link.com/",
  "account_number": "40000000000000000000"
}

Описание:

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

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

1. before_creation – Поля которые нужно подать в момент создания заявки
2. after_creation – Поля которые нужно подать в момент подтверждение заявки пользователем

Если для выбранного метода динамические поля отсутствуют, то значит ничего подавать не нужно.

В случае осуществления PayIn платежей, эти поля заполняет пользователь в форме оплаты.
В случае осуществления PayOut платежа, эти поля заполняет мерчант в момент создания заявки.

Структура динамических полей прикрепленных к методу:

Описание полей:

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

Чтобы создать тестовый платеж, в запрос на создание платежа нужно добавить параметр:

"is_sandbox_payment": true

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

Все остальные поля запроса остаются такими же, как для обычных PayIn/PayOut операций

Особенности работы песочницы

• В личном кабинете доступна кнопка «Обновить статус», позволяющая вручную менять статус тестовой операции и её сумму для проверки работы уведомлений
• Тестовые операции полностью изолированы - они не изменяют баланс кошелька
• Время жизни заявки (По истечении времени статус автоматически изменится на Expired):
  • PayIn - 10 минут
  • PayOut - 10 минут
    
• Уникализация сумм:
  • Для PayIn платежей созданных в режиме песочницы существует вероятность 50%, что система создаст заявку с проуникализированной суммой (поле amount в ответе будет отличаться от переданного в запросе значения)

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

{
  "order_id": "my_order_id",
  "amount": 50000,
  "currency": "RUB",
  "method_id": "CARD_RUB",
  "user_context": "0.0.0.0",
  "is_sandbox_payment": true
}

{
  "order_id": "my_order_id",
  "amount": 50000,
  "currency": "RUB",
  "method_id": "CARD_RUB",
  "is_sandbox_payment": true,
  "fields_data": [
      {
          "key": "card-number",
          "value": {
              "value": "4400000000000008"
          }
      }
  ]
}

{
  "order_id": "my_order_id",
  "amount": 50000,
  "currency": "RUB",
  "method_id": "SBP_RUB",
  "is_sandbox_payment": true,
  "fields_data": [
      {
          "key": "phone",
          "value": {
              "value": "79000000001"
          }
      },
      {
          "key": "nspk-code",
          "value": {
              "value": "100000000150"
          }
      }
  ]
}

Для осуществления всех апи запросов требуется передавать API ключ - найти его можно в настройках профиля, а так же необходимо передавать хэш подпись и временную метку, подробнее о генерации подписи смотрите в секции "Генерация подписей для API запросов"

URL для апи запросов: Уточняйте у менеджера

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