«Система быстрых платежей»

Введение

«Система быстрых платежей» — метод, позволяющий проводить платежи в рублях с использованием банковских счетов в России. Для этого метода в платёжной платформе EtoPlatezhi поддерживаются разовые оплаты, возвраты и выплаты. И, в дополнение к ним, готовится поддержка повторяемых оплат.

В этой статье представлена информация о работе с методом «Система быстрых платежей»: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

Характеристика

Схема работы

В проведении отдельного платежа с использованием метода «Система быстрых платежей» задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа EtoPlatezhi, а также технические средства сервиса провайдера.

Основные операции

Для проведения платежей и выполнения операций с использованием метода «Система быстрых платежей» могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты и выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

При работе с методом «Система быстрых платежей», независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.

Сценарии использования

Проведение оплат с использованием метода «Система быстрых платежей» осуществляется с отображением пользователям платёжной инструкции, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

К особенностям работы с методом «Система быстрых платежей» можно отнести то, что для каждой выплаты с использованием этого метода должен быть указан конкретный банк. При инициировании выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка.

Поддержка со стороны банков

Со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечной точке /v2/info/banks/sbp-qr/payout/list, которая относится к группе конечных точек /v2/info/banks/{payment_method}/{operationType}/list Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.

{
    "general": {
        "project_id": 200,
        "payment_id": "ORDER_155860015",
        "signature": "K6jllym+PtObocZtr345st...=="
    },
    "payment": {
        "amount": 1000,
        "currency": "RUB"
    }
}

[
  {
    "id": 55131, // Индентификатор банка
    "abbr": "SBER", // Служебная аббревиатура банка, используемая в платформе
    "name": "Sberbank", // Основное (международное) название банка
    "nativeName": "СберБанк", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 643, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "RUB", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
        "number_3_4217": "643", // Цифровой код валюты платежа в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 55181,
    "abbr": "RAIFFEISEN",
    "name": "Raiffeisenbank",
    "nativeName": "Райффайзенбанк",
    "currencies": [ 
      {
        "id": 643,
        "alpha_3_4217": "RUB",
        "number_3_4217": "643",
        "exponent": 2
      }
    ]
  },
...
]

С вопросами о работе с банками, поддерживающими метод «Система быстрых платежей», можно обращаться к курирующему менеджеру EtoPlatezhi.

Общая информация

Для проведения оплаты через Payment Page с использованием метода «Система быстрых платежей» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL EtoPlatezhi и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Система быстрых платежей» через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Валютой платежа может быть только RUB.
4. Для предварительного выбора метода «Система быстрых платежей» необходимо указывать код этого метода в параметре force_payment_method — sbp-qr.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "RUB",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "RUB",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода «Система быстрых платежей» используется типовой формат, описание которого представлено в статье Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037 была проведена оплата в размере 100,00 RUB.

{
    "project_id": 1037,
    "payment": {
        "id": "123456789",
        "type": "purchase",
        "status": "success",
        "date": "2024-06-15T13:04:15+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "123"
    },
    "operation": {
        "id": 62,
        "type": "sale",
        "status": "success",
        "date": "2024-06-15T13:05:15+0000",
        "created_date": "2024-06-15T13:04:15+0000",
        "request_id": "363dedea310b7e3e35-00000001",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1782,
            "payment_id": "33007291SS518890B",
            "date": "2021-12-15T13:05:12+0000"
        }
    },
    "signature": "AAB6/UB0MJY+O/h11NfFIsO6WXRzCSnJDPXYg=="
}

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
    "project_id": 1037,
    "payment": {
        "id": "23456789",
        "type": "purchase",
        "status": "decline",
        "date": "2024-06-15T13:21:51+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "123"
    },
    "operation": {
        "id": 67,
        "type": "sale",
        "status": "decline",
        "date": "2024-06-15T13:22:51+0000",
        "created_date": "2024-06-15T13:21:51+0000",
        "request_id": "982fc18ec86c925d88-00000002",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 1782,
            "payment_id": "",
            "date": ""                      
        }
    },
    "signature": "zZBZHvDTIKG1+SdwLGW642i03JQL238wkmhcLcg=="
}

Дополнительные материалы

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

• Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Проведение оплат — о том, как проводить разовые оплаты через Payment Page.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

Общая информация

Повторяемые оплаты через «Система быстрых платежей» — это метод проведения повторных платежей со списанием по запросам или рекуррентных операций с использованием сохраненных платёжных данных. Подробная информация представлена в разделе Повторяемая оплата со списаниями по запросам. Через Payment Page доступна регистрация повторяемой оплаты, для этого со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, а также данные для регистрации повторяемой оплаты в объекте recurring, на рабочий URL EtoPlatezhi и принять оповещение о результате. В оповещении о регистрации повторяемой оплаты вы получите её идентификатор, который нужно использовать для проведения или отмены регулярной оплаты через Gate. Подробная информация об этом представлена в разделе Повторяемые оплаты через Gate.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Система быстрых платежей» через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы для регистрации повторяемой оплаты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Для регистрации повторяемой оплаты необходимо передавать признак такой регистрации в объекте recurring и пояснение к характеру оказываемых услуг в параметре payment_description.

   При использовании JavaScript-библиотеки EtoPlatezhi объект recurring в таком запросе может представлять собой JSON-объект, включающий в себя параметр register со значением true. В других случаях объект recurring, как и тело запроса в целом, должен указываться в виде URL-строки, полученной из исходного JSON-объекта с помощью преобразования URL-encoding.

4. Для предварительного выбора метода «Система быстрых платежей» необходимо указывать код этого метода в параметре force_payment_method — sbp-qr.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор платежа, сумму и код валюты), идентификатор пользователя, признак регистрации повторяемой оплаты, а также подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "RUB",
   "customer_id": "customer1",
   "recurring": {"register":true},
   "payment_description": "example reason",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "RUB",
   "customer_id": "customer1",
   "recurring": {"register":true},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Дополнительные материалы

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

• Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

Общая информация

Для проведения оплаты через Gate с использованием метода «Система быстрых платежей» со стороны веб-сервиса необходимо:

1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL EtoPlatezhi.
2. Принять промежуточное оповещение от платёжной платформы и отобразить пользователю платёжную инструкцию.
3. Принять итоговое оповещение от платёжной платформы.

Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Система быстрых платежей» через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на оплаты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/sbp-qr/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
3. Валютой платежа может быть только RUB.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, а также подпись.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

Формат промежуточных оповещений для отображения платёжной инструкции

Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода «Система быстрых платежей» необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив display_data. Формат таких оповещений является типовым (подробнее), при этом в состав массива display_data включаются следующие параметры:

• type — тип объекта,
• title — название объекта,
• data — данные, соответствующие указанному типу объекта.

Параметр title определяет тип содержимого параметра data и может принимать одно из следующих значений:

• qr_img — при передаче QR-кода в виде изображения. В этом случае в параметре data передаётся строка, закодированная с использованием схемы Base64.
• qr_code_url — при передаче в параметре data платёжной ссылки в виде URL.
• qr_code_expired_timestamp — при передаче в параметре data срока действия QR-кода в виде порогового значения UNIX-времени (в секундах, в соответствии со стандартом ISO/IEC/IEEE 9945:2009), по достижении которого QR-код перестаёт быть действительным.
• qr_lifetime — при передаче в параметре data времени действия QR-кода (в секундах, начиная с момента создания оповещения с массивом display_data на стороне платёжной платформы).

Далее приведён фрагмент оповещения, содержащего строку для создания QR-кода, времени его действия и платёжной ссылки в качестве дополнительной информации.

    "display_data": [
        {
            "type": "qr_img",
            "title": "qr_code_img",
            "data": "image/png;base64 data"
        },
        {
            "type": "qr_url",
            "title": "qr_code_url",
            "data": "https://qr.nspk.ru/AS100001D9A3G?type=01&bank=1&crc=0C8A"
        },
        {
            "type": "add_info",
            "title": "qr_code_expired_timestamp",
            "data": "1718092645"
        },
        {
            "type": "add_info",
            "title": "qr_lifetime",
            "data": "1800"
        }
    ],

Вместе с платёжной ссылкой из массива display_data рекомендуется предоставлять пользователю доступ к списку поддерживаемых банков и инструкции для мобильного приложения на сайте «Системы Быстрых Платежей», а также предупреждать пользователя о необходимости разрешить в настройках браузера открытие приложений по ссылкам (в связи с тем, что переход в приложение банка реализован по URL).

Формат итоговых оповещений

Для итоговых оповещений об оплатах с применением метода «Система быстрых платежей» используется типовой формат, описание которого представлено в статье Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037 была проведена оплата в размере 100,00 RUB.

{
    "project_id": 1037,
    "payment": {
        "id": "123456789",
        "type": "purchase",
        "status": "success",
        "date": "2024-06-15T13:04:15+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "123"
    },
    "operation": {
        "id": 62,
        "type": "sale",
        "status": "success",
        "date": "2024-06-15T13:05:15+0000",
        "created_date": "2024-06-15T13:04:15+0000",
        "request_id": "363dedea310b7e3e35-00000001",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1782,
            "payment_id": "33007291SS518890B",
            "date": "2021-12-15T13:05:12+0000"
        }
    },
    "signature": "AAB6/UB0MJY+O/h11NfFIsO6WXRzCSnJDPXYg=="
}

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
    "project_id": 1037,
    "payment": {
        "id": "23456789",
        "type": "purchase",
        "status": "decline",
        "date": "2024-06-15T13:21:51+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "123"
    },
    "operation": {
        "id": 67,
        "type": "sale",
        "status": "decline",
        "date": "2024-06-15T13:22:51+0000",
        "created_date": "2024-06-15T13:21:51+0000",
        "request_id": "982fc18ec86c925d88-00000002",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 1782,
            "payment_id": "",
            "date": ""                      
        }
    },
    "signature": "zZBZHvDTIKG1+SdwLGW642i03JQL238wkmhcLcg=="
}

Дополнительные материалы

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

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
• Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Общая информация

Повторяемые оплаты через «Система быстрых платежей» — это метод проведения повторных платежей со списанием по запросам или рекуррентных операций с использованием сохраненных платёжных данных. Подробная информация представлена в разделе Повторяемая оплата со списаниями по запросам.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом «Система быстрых платежей» через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Регистрация повторяемой оплаты

Для регистрации повторяемых оплат со стороны веб-сервиса необходимо отправить запрос на оплату, содержащий требуемые параметры и подпись, а также признак регистрации повторяемой оплаты в параметре register объекта recurring со значением true, на заданный URL EtoPlatezhi и принять оповещение с информацией о результате. Если вы укажете в параметре register какое-либо другое значение, будет проведена разовая оплата, а повторяемая оплата зарегистрирована не будет.

В ответном оповещении о регистрации повторяемой оплаты содержится идентификатор повторяемой оплаты, который в дальнейшем можно использовать для проведения повторяемых оплат.

Информация о проведении оплаты через Gate с помощью метода «Система быстрых платежей» представлена в разделе Разовые оплаты через Gate.

Формат запросов на регистрацию повторяемой оплаты

При работе с запросами на регистрацию повторяемой оплаты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Каждый раз должен использоваться запрос, отправляемый методом POST к конечной точке /v2/payment/sbp-qr/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • description — пояснение к характеру оказываемых услуг;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
   • recurring — объект, содержащий сведения о повторяемой оплате (условия проведения регулярной оплаты определяются на стороне мерчанта):
     • register — признак регистрации платежа как повторяемой оплаты;
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на регистрацию повторяемой оплаты с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор платежа, сумму и код валюты), идентификатор пользователя и IP-адрес пользователя, признак регистрации повторяемой оплаты, а также подпись.

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB",
    "description": "example reason"
  },
  "recurring": {
    "register": true
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB",
    "description": "example reason"
  },
  "recurring": {
    "register": true
  }
}

Формат запросов на проведение повторяемой оплаты

После того, как повторяемая оплата зарегистрирована, для инициирования повторяемой оплаты, следует отправить в платёжную платформу запрос с полученным идентификатором повторяемой оплаты, который вы ранее получили в оповещении при регистрации этой повторяемой оплаты.

При работе с запросами на проведение повторяемой оплаты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Для проведения каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/sbp-qr/recurring.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на проведение повторяемой оплаты с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор платежа, сумму и код валюты), IP-адрес пользователя, идентификатор зарегистрированной регулярной оплаты, а также подпись.

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6bltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "recurring": {
    "id": 1234567890
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6bltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "recurring": {
    "id": 1234567890
  }
}

Формат промежуточных оповещений для отображения платёжной инструкции

Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода «Система быстрых платежей» необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив display_data. Формат таких оповещений является типовым (подробнее), при этом в состав массива display_data включаются следующие параметры:

• type — тип объекта,
• title — название объекта,
• data — данные, соответствующие указанному типу объекта.

Параметр title определяет тип содержимого параметра data и может принимать одно из следующих значений:

• qr_img — при передаче QR-кода в виде изображения. В этом случае в параметре data передаётся строка, закодированная с использованием схемы Base64.
• qr_code_url — при передаче в параметре data платёжной ссылки в виде URL.
• qr_code_expired_timestamp — при передаче в параметре data срока действия QR-кода в виде порогового значения UNIX-времени (в секундах, в соответствии со стандартом ISO/IEC/IEEE 9945:2009), по достижении которого QR-код перестаёт быть действительным.
• qr_lifetime — при передаче в параметре data времени действия QR-кода (в секундах, начиная с момента создания оповещения с массивом display_data на стороне платёжной платформы).

Далее приведён фрагмент оповещения, содержащего строку для создания QR-кода, времени его действия и платёжной ссылки в качестве дополнительной информации.

    "display_data": [
        {
            "type": "qr_img",
            "title": "qr_code_img",
            "data": "image/png;base64 data"
        },
        {
            "type": "qr_url",
            "title": "qr_code_url",
            "data": "https://qr.nspk.ru/AS100001D9A3G?type=01&bank=1&crc=0C8A"
        },
        {
            "type": "add_info",
            "title": "qr_code_expired_timestamp",
            "data": "1718092645"
        },
        {
            "type": "add_info",
            "title": "qr_lifetime",
            "data": "1800"
        }
    ],

Вместе с платёжной ссылкой из массива display_data рекомендуется предоставлять пользователю доступ к списку поддерживаемых банков и инструкции для мобильного приложения на сайте «Системы Быстрых Платежей», а также предупреждать пользователя о необходимости разрешить в настройках браузера открытие приложений по ссылкам (в связи с тем, что переход в приложение банка реализован по URL).

Дополнительные материалы

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

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Общая информация

Для выполнения возврата через Gate с использованием метода «Система быстрых платежей» со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL EtoPlatezhi и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом «Система быстрых платежей» через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на возвраты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/sbp-qr/refund.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;,
     • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий к возврату или его описание;,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода «Система быстрых платежей» должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя и подпись.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

Формат оповещений

Для оповещений о результатах возвратов с применением метода «Система быстрых платежей» используется типовой формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037 был выполнен возврат в размере 100,00 RUB.

{
    "project_id": 1037,
    "payment": {
        "id": "62153051",
        "type": "purchase",
        "status": "refunded",
        "date": "2024-06-15T13:21:51+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "1234"
    },
    "operation": {
        "id": 63,
        "type": "refund",
        "status": "success",
        "date": "2024-06-15T14:23:56+0000",
        "created_date": "2024-06-15T14:22:51+0000",
        "request_id": "ea2e5888a65cf1b1f2b5-00000003",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1782,
            "payment_id": "7C035795EJ562523A",
            "date": "2024-06-15T14:23:51+0000"
        }
    },
    "signature": "uU6LOpEjEqxeqJ2GsDkDnaY+1p1m4aS5zTPkJA=="
}

В следующем примере оповещение свидетельствует об отклонённом возврате.

{
    "project_id": 1037,
    "payment": {
        "id": "59375393",
        "type": "purchase",
        "status": "success",
        "date": "2024-06-15T14:23:56+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 10000,
            "currency": "RUB"
        },
        "description": "Test sale"
    },
    "customer": {
        "id": "1234"
    },
    "operation": {
        "id": 84,
        "type": "refund",
        "status": "decline",
        "date": "2024-06-15T14:23:56+0000",
        "created_date": "2024-06-15T14:23:56+0000",
        "request_id": "776d5d3e602912e88858c922e34e5-00000001",
        "sum_initial": {
            "amount": 10000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "RUB"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 1782,
            "payment_id": "",
            "date": ""  
        }
    },
    "signature": "qjVnKRZX51lrxh5kqCzurbJbQQSAeFwqH7H9gk7gUYI3A=="
}

Дополнительные материалы

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

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Возвраты средств после оплат — о том, как выполнять возвраты через Gate.
• Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Общая информация

Для проведения выплаты через Gate с использованием метода «Система быстрых платежей» со стороны веб-сервиса необходимо:

1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL EtoPlatezhi.
2. Если проведение выплаты требуется дополнительно подтверждать — принять соответствующее оповещение и отправить запрос на продолжение платежа. Подробнее о дополнении данных — в разделе Дополнение информации о платеже.
3. Принять от платежной платформы оповещение о результате выплаты.

Информация о форматах запросов и оповещений, используемых для проведения выплат методом «Система быстрых платежей» через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в разделе Организация взаимодействия.

Формат запросов

При работе с запросами на выплаты с применением метода «Система быстрых платежей» необходимо учитывать следующее:

1. Для инициирования каждой выплаты должен использоваться POST-запрос к конечной точке /v2/payment/sbp-qr/payout.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от EtoPlatezhi при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Использование подписи к данным);
   • payment — сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;
     • currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • customer — сведения о пользователе:
     • id — идентификатор, уникальный в рамках проекта;
     • ip_address — IP-адрес, актуальный для инициируемой выплаты;
   • account — сведения о счёте пользователя:
     • number — номер телефона, по которому необходимо провести выплату, указывается с кодом страны, без знаков пунктуации и специальных символов (например, 79031234567);
     • bank_id — идентификатор банка.
3. При использовании варианта проведения выплат без дополнительных подтверждений в запросе может быть необходимым указывать сведения о пользователе в формате PAM (Personal Assurance Message) в параметре pam объекта customer. Эти сведения включают в себя имя, отчество (при наличии) и первую букву фамилии без точки (например, Софья Васильевна К). Необходимость указания этого параметра следует уточнять у курирующего менеджера EtoPlatezhi.
4. Валютой платежа может быть только RUB.
5. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на выплату с применением метода «Система быстрых платежей» должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), информацию о пользователе и счёте, подпись, а также может содержать сведения о пользователе в формате PAM.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "pam": "Софья Васильевна К"
  },
  "account": {
    "number": "79031234567",
    "bank_id": 12345
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "pam": "Софья Васильевна К"
  },
  "account": {
    "number": "79031234567",
    "bank_id": 12345
  }
}

Форматы оповещений и запросов для дополнительного подтверждения платежа

При использовании варианта проведения выплат с дополнительными подтверждениями со стороны мерчанта необходимо обеспечить приём оповещений о необходимости дополнения информации и отправку ответных запросов, подтверждающих эти выплаты.

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

В оповещениях о необходимости дополнительного подтверждения платежа содержатся:

• Массив clarification_fields с названием параметра confirm. В таких случаях этот параметр указывает на то, что выплата должна быть дополнительно подтверждена.
• Объект provider_extra_fields с параметром account_name. В таких случаях этот параметр содержит имя и первую букву фамилии человека, на которого в указанном банке зарегистрирован счёт, связанный с указанным номером мобильного телефона (на основании данных банка). В некоторых случаях, в зависимости от банка, может указываться и отчество.

Далее приведён фрагмент оповещения, содержащего названия параметров для дополнения информации о платеже.

    "clarification_fields": [
        "confirm"
    ],
...
    "provider_extra_fields": {
        "account_name": "Софья Васильевна К"
    }

Запросы с подтверждениями должны отправляться методом POST к конечной точке /v2/payment/clarification и должны содержать следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, к которому относится проводимый платёж;
  • payment_id — идентификатор платежа, к которому относятся отправляемые данные;
  • signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• additional_data — объект с запрошенными данными:
  • confirm — параметр с информацией о подтверждении выплаты (формат данных boolean).

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и данные, которые требуются для продолжения платежа:

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
        "confirm": true
  }
}

При отправке запроса с информацией о подтверждении выплаты проведение платежа может продолжаться следующим образом:

• Если в параметре confirm указано значение true и информация своевременно доставлена провайдеру, то проведение платежа продолжается на стороне платёжной платформы и сервиса провайдера, после чего к веб-сервису отправляется итоговое оповещение.
• Если в параметре confirm указано значение false или любое другое значение либо информация своевременно не доставлена провайдеру, то платёж переводится в статус decline.

Формат итоговых оповещений

Для оповещений о результатах выплат с применением метода «Система быстрых платежей» используется типовой формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 8181 была проведена выплата в размере 1,00 RUB.

{
    "project_id": 8181,
    "payment": {
        "id": "sbp_test_1",
        "type": "payout",
        "status": "success",
        "date": "2022-10-27T12:36:28+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 100,
            "currency": "RUB"
        },
        "description": ""
    },
    "account": {
        "number": "***0091"
    },
    "customer": {
        "id": "test_1"
    },
    "operation": {
        "id": 12,
        "type": "payout",
        "status": "success",
        "date": "2022-10-27T12:36:28+0000",
        "created_date": "2022-10-27T12:35:54+0000",
        "request_id": "341d14d645d9123e388c0661147e40dfaf9d-00000001",
        "sum_initial": {
            "amount": "amount": 100,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": "amount": 100,
            "currency": "RUB"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 18932,
            "payment_id": "824",
            "auth_code": "",
            "date": "2022-10-27T12:36:17+0000"
        }
    },
    "signature": "X5xSW/oeLKzL9303WzgxQh7Cmico59B3wl/V78kcg/JSSBQ=="
}

В следующем примере оповещение свидетельствует об отклонённой выплате.

{
    "project_id": 8181,
    "payment": {
        "id": "sbp_test_2",
        "type": "payout",
        "status": "decline",
        "date": "2022-10-27T12:41:59+0000",
        "method": "sbp-qr",
        "sum": {
            "amount": 100,
            "currency": "RUB"
        },
        "description": ""
    },
    "account": {
        "number": "***0091"
    },
    "customer": {
        "id": "test_1"
    },
    "operation": {
        "id": 13,
        "type": "payout",
        "status": "decline",
        "date": "2022-10-27T12:41:59+0000",
        "created_date": "2022-10-27T12:41:30+0000",
        "request_id": "2f0866179aba2ec5dd9781dd07e2888-00000001",
        "sum_initial": {
            "amount": 100,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 100,
            "currency": "RUB"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 18932,
            "payment_id": "",
            "auth_code": ""
        }
    },
    "signature": "nb8RCW9/815yZEK0UMfWse6R0VlUJwpoyUWGHKXY18bX8jE41Q=="
}

Дополнительные материалы

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

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Выплаты — о том, как проводить выплаты через Gate.
• Работа с информацией об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.