Введение

Модуль Выплат позволяет Партнерам (юридическим лицам), имеющим небанковское ПО (бухгалтерская система, кассовое решение, иная собственная система), осуществлять передачу Получателям денежных средств. Поддерживаются следующие способы выплат:

• По номеру карты
• На сохраненную карту (связку получателя)
• По номеру телефона через Систему Быстрых Платежей (СБП)

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

В процессе выплат участвуют следующие стороны:

• Получатель - физическое лицо, получающее выплату
• Плательщик - юридическое лицо (Партнер), осуществляющее перевод
• Сервис Партнера - приложение Партнера, занимающееся учетом и инициацией выплат в пользу физических лиц
• Модуль Выплат (далее МВ) - автоматизированная система Банка, предоставляющая Партнеру возможность осуществлять выплаты на банковские карты

Общий процесс взаимодействия с использованием только API вызовов (для работы с реквизитами получателя может потребоваться сертификация PCI DSS):

1. Получатель обращается к Оператору Партнера или самостоятельно в Сервис Партнера за получением Выплаты;
2. При получении обращения Сервис Партнера осуществляет сбор платежных реквизитов Получателя;
3. Сервис Партнера регистрирует проведение Выплаты в МВ и подтверждает Выплату;
4. Производится Выплата и возврат результата проведения Выплаты;
5. Сервис Партнера может запросить статус Выплаты в любой момент.

Общий процесс взаимодействия с использованием API вызовов и страниц Банка (страница сбора реквизитов получателя, финишная страница):

1. Получатель обращается к Оператору Партнера или самостоятельно в Сервис Партнера за получением Выплаты;
2. При получении обращения Сервис Партнера регистрирует проведение выплаты в МВ;
3. Сервис Партнера получает адрес страницы сбора реквизитов Получателя для ввода платежных реквизитов Получателя для отображения Оператору или Получателю;
4. Страница сбора реквизитов Получателя осуществляет сбор платежных реквизитов Получателя и подтверждение Выплаты;
5. Производится Выплата и возврат результата проведения Выплаты;
6. Сервис Партнера может запросить статус Выплаты в любой момент.

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

• сценарий запроса баланса через API
• сценарий выплаты с транзитного счета через API с передачей только объекта target
• сценарий выплаты с транзитного счета через API и платежную страницу
• сценарий запроса статуса выплаты

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

• сценарий создания связки корпоративной карты
• сценарий выплаты с корпоративной карты через API с передачей объектов source и target
• сценарий выплаты с корпоративной карты через API и платежную страницу
• сценарий запроса статуса выплаты

Особенности реализации и ограничения

1. Отмены и возвраты ранее выполненных выплат не поддерживаются;
2. Поддерживаются выплаты только в валюте с кодом 398 (KZT);
3. Выплаты осуществляются только на карты банков Казахстана.

Сценарии работы с использованием API

Запрос баланса выплат через API

Данный сценарий описывает последовательность действий по запросу баланса выплат с использованием API.

1. Оператор принимает решение о запросе баланса по выплатам и выполняет на стороне Сервиса Партнера необходимые действия;
2. Сервис Партнера отправляет запрос баланса (getAmount.do) в Модуль Выплат;
3. Входная проверка данных, формирование информации о балансе выплат;
4. Модуль Выплат возвращает в Сервис Партнера данные о балансе;
5. Сервис Партнера отображает Оператору информацию о балансе.

Выплата денежных средств только через API

Данный сценарий описывает последовательность выплаты из сервиса партнера с использованием API. Сбор реквизитов Получателя реализуется на стороне Партнера (для работы с реквизитами получателя может потребоваться сертификация PCI DSS).

1. Оператор (или Получатель) принимает решение о проведении выплаты и выполняет на стороне Сервиса Партнера необходимые действия.
2. Сервис Партнера отправляет запрос на осуществление выплаты (performPayout.do) в Модуль Выплат и передает все необходимые параметры выплаты. В зависимости от того, какие параметры будут переданы в блоке target, выплата будет осуществляться по номеру карты, по идентификатору связки получателя или по номеру телефона через СБП.
3. Входная проверка данных, выполнение регистрационных и платежных операций.
4. Модуль Выплат возвращает в Сервис Партнера итоговый статус выплаты.
5. Сервис Партнера уведомляет Оператора (или Получателя) о статусе выплаты.

Выплата денежных средств через API и страницы выплат Банка

Данный сценарий описывает последовательность выплаты из сервиса партнера с использованием API и страницы выплат Банка. Сбор карточных данных Получателя реализуется с использованием страницы на стороне Банка (для этого не требуется сертификация PCI DSS).

1. Оператор (или Получатель) принимает решение о проведении выплат и выполняет на стороне Сервиса Партнера необходимые действия;
2. Сервис Партнера отправляет в Модуль Выплат запрос на регистрацию выплаты (registerPayout.do) и передает все необходимые параметры для регистрации;
3. Модуль Выплат регистрирует выплату;
4. Модуль Выплат возвращает URL страницы (в ссылке присутствует уникальный идентификатор выплаты);
5. Сервис Партнера перенаправляет Оператора (или Получателя) на полученный URL страницы;
6. Оператор (или Получатель) переходит на страницу, заполняет реквизиты Получателя и подтверждает выплату;
7. Модуль Выплат выполняет выплату;
8. Модуль Выплат возвращает URL страницы (в ссылке присутствует уникальный идентификатор выплаты);
9. Оператор (или Получатель) переходит на страницу, и инициирует получение статуса;
10. Модуль Выплат формирует статус;
11. Модуль Выплат показывает статус на странице.

Запрос статуса выплаты

Данный сценарий описывает последовательность запроса статуса выплаты с использованием API. Запросить актуальный статус выплаты можно на любом этапе ее проведения.

1. Оператор (или Получатель) запрашивает статус выплаты в Сервисе Партнера;
2. Сервис Партнера отправляет в Модуль Выплат запрос статуса выплаты (getPayoutStatus.do);
3. Модуль Выплат проверяет данные запроса и формирует ответ;
4. Модуль Выплат возвращает в Сервис Партнера итоговый статус выплат;
5. Сервис Партнера уведомляет Оператора (или Получателя) о статусе выплаты.

Связки в модуле Выплат

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

Модуль выплат поддерживает следующие типы связок:

• Связка получателя средств (связка зачисления, target).
• Связка плательщика (связка списания, source).
• Сохраненная корпоративная карта (связка списания, source).

Связки получателя

Создать связку получателя можно одним из следующих способов:

• С помощью метода API createTargetBindingId.do. На своей странице выплат Партнер может реализовать сохранение номера карты получателя. Если получатель подтвердит сохранение карты, Партнер вызовет метод создания связки. Возвращенный в результате идентификатор bindingId можно будет передавать в блоке target метода performPayout.do при последующих выплатах.

Связки плательщика

Партнер может предоставлять своим партнерам (дочерним мерчантам) возможность выступать в роли Плательщика. В таком случае дочерние мерчанты производят выплаты со своих счетов. Для этого Партнер создает для дочернего мерчанта связку плательщика методом createSourceBindingId.do. Возвращенный в результате выполнения метода идентификатор bindingId можно будет передавать в блоке source метода performPayout.do при осуществлении выплат.

Добавление корпоративной карты в личном кабинете

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

Для Настроек выполните следующие шаги:

• Выполните вход в личный кабинет.
• В левой панели перейдите в раздел Настройки.
• Выбрать подраздел Мои карты.

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

• «Номер карты» - введите цифровое значение номера вашей карты
• «Месяц» - из выпадающего списка выберите месяц окончания срока действия карты
• «Год» - из выпадающего списка выберите год окончания срока действия карты
• «CVC» - укажите код банковской карты - три цифры, указанные на оборотной стороне карты

После заполнения всех полей в форме нажмите кнопку Сохранить карту. После чего появляется окно для подтверждения.

В поле «Пароль» необходимо ввести пароль, высланный в СМС на ваш мобильный номер, к которому привязана карта. После ввода пароля нажмите на кнопку Подтвердить.

Для подтверждения с добавляемой карты автоматически спишется (и сразу вернется) минимальная сумма. Добавленная карта отобразится на странице:

Если щелкнуть по привязанной карте, появляются кнопки:

1. Сделать карту основной;
2. Копировать ID связки;
3. Удалить карту.

Для выплат с использованием API вам необходимо скопировать ID связки и использовать ее для указания в параметре source.bindingId HTTPS POST API запроса /payouts/api/v2/performPayout.do при проведении выплаты.

Настройка КНП в Личном кабинете

Чтобы настроить значение КНП, Вы должны обладать соответствующей пермиссией. Для настройки необходимо выполнить следующие действия.

• Выполните вход в личный кабинет.
• В левой панели перейдите в раздел Настройки.
• Выбрать подраздел Значение КНП.

• В поле Значение КНП введите соответствующее цифровое значение КНП или воспользуйтесь справочником КНП кодов, нажав на одноименную кнопку.

• Введите цифровое значение КНП или слово для поиска, выберите необходимое значение и нажмите кнопку Применить.

API запросы для выплат

Запросы осуществляются с использованием протокола HTTP 1.1 с использованием SSL (HTTPS), на адрес:

TEST: https://3dsec.berekebank.kz/payouts/api/{api_version}/{api_method}
PROD: https://securepayments.berekebank.kz/payouts/api/{api_version}/{api_method}

HTTPS POST API запросы должны отвечать следующим требованиям:

• Авторизация запросов осуществляется с использованием пары логин - пароль с передачей в теле запроса.
  
• Тело запроса передается в формате application/json.
  
• Тело ответа возвращается в формате application/json.

HTTPS POST API запросы должны содержать заголовки:

• Content-Type: application/json; charset=UTF-8
• Accept: application/json; version=2.0

Актуальная версия API для указания в контексте запроса ({api_version}): v2

Требования безопасности

• Все сетевые взаимодействия производятся только по HTTPS.
• Приложение должно проверять корректность SSL-сертификата сервера. Если SSL-сертификат не прошел проверку, необходимо немедленно прекратить сессию, чтобы не допустить утечку данных авторизации.

Запрос проверки доступности Модуля Выплат

Для проверки работоспособности Модуля Выплат необходимо использовать HTTPS GET API запрос /payouts/api/v2/echo

Параметры запроса

Параметры не требуются.

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

Ответ предоставляется в формате text/plain. В ответе указывается текущая версия модуля выплат и имя ноды через дефис, в квадратных скобках указано имя инстанса.

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/echo'

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

Payout v2.3 is online in channel Payout_APIserver - svip01[instance:svipUAT]

Запрос баланса

Для запроса остатка баланса для выплат необходимо использовать HTTPS POST API запрос /payouts/api/v2/getAmount.do. Данный запрос возвращает данные об остатке баланса при условии успешной обработки запроса.

Параметры запроса

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

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/getAmount.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "payout_api_username",
    "password": "payout_api_password",
    "source": {
      "bindingId": "4908a3c3-6c7c-75d3-9707-66ab06c12040"
    }
}'

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

{
    "errorCode": "0",
    "balanceDescriptionList": {
        "balanceAmount": 49925200,
        "balanceCurrency": "398",
        "balanceSign": "C"
    }
}

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

Для регистрации выплаты необходимо использовать HTTPS POST API запрос /payouts/api/v2/registerPayout.do. Данный запрос осуществляет регистрацию Выплаты и возвращает ссылку на страницу указания реквизитов Получателя. Сбор реквизитов получателя реализуется на стороне Банка (для работы с реквизитами получателя не требуется сертификация PCI DSS).

Параметры запроса

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

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/registerPayout.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "payout_api_username",
    "password": "payout_api_password",
    "orderNumber": "1645458818047",
    "amount": 1234,
    "currency": "398",
    "description": "Decent payout",
    "language": "EN",
    "sessionTimeoutSecs": 300,
    "client": {
        "name": "John Doe",
        "clientId": "12345abc-d67e-8901-23fg-h45i67jk8901",
        "email": "payee@mail.com",
        "phone": "9991234567"
    },
    "urls": {
        "returnUrl": "https://partnerdomain.com/&result=ok",
        "failUrl": "https://partnerdomain.com/&result=ok",
    },
    "jsonParams": {
        "paramname1": "paramvalue1",
        "paramname2": "paramvalue2"
    }
}'

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

{
    "errorCode": "0",
    "orderNumber": "1645458818047",
    "orderId": "da42b8d9-328b-45e6-aa35-235e348268bf",
    "formUrl": "https://payoutdomain.com/payment/merchants/svip_payout_ab/payment_ru.html?mdOrder=da42b8d9-328b-45e6-aa35-235e348268bf"
}

Проведение выплаты

Для проведения выплаты необходимо использовать HTTPS POST API запрос /payouts/api/v2/performPayout.do.
Данный запрос осуществляет связанную отработку Выплаты и возвращает статус.
Сбор реквизитов Получателя реализуется на стороне Партнера (для работы с реквизитами получателя требуется сертификация PCI DSS).

Параметры запроса

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

Пример запроса - источник фондирования транзитный счет

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/performPayout.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "payout_api_username",
    "password": "payout_api_password",
    "orderNumber": "payout_1",
    "amount": 1234,
    "currency": "398",
    "client": {
        "name": "John Doe",
        "clientId": "12345abc-d67e-8901-23fg-h45i67jk8901",
        "email": "payee@mail.com",
        "phone": "9991234567"
    },
    "target": {
        "pan": "4111111111111111"
    },
    "jsonParams": {
        "paramname1": "paramvalue1",
        "paramname2": "paramvalue2"
    }
}'

Пример запроса - источник фондирования корпоративная карта

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/performPayout.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "payout_api_username",
    "password": "payout_api_password",
    "orderNumber": "payout_1",
    "amount": 1234,
    "currency": "398",
    "client": {
        "name": "John Doe",
        "clientId": "12345abc-d67e-8901-23fg-h45i67jk8901",
        "email": "payee@mail.com",
        "phone": "9991234567"
    },
    "source": {
        "bindingId": "e7141803-e78a-79ef-9a10-db3b06c12040"
    },
    "target": {
        "pan": "4111111111111111"
    },
    "jsonParams": {
        "paramname1": "paramvalue1",
        "paramname2": "paramvalue2"
    }
}'

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

{
    "errorCode": "0",
    "errorMessage": "Успешно",
    "amount": 1234,
    "fee": 0,
    "currency": "398",
    "orderNumber": "1645458818059_12",
    "description": "Decent payout",
    "orderStatus": "2",
    "operationList": [
        {
            "operationDate": 1665414462047,
            "operationType": "P2P_CREDIT",
            "amount": 1234,
            "currency": "398",
            "resultCode": 0,
            "resultCodeDescription": "Перевод исполнен",
            "refNum": "948498232196",
            "pan": "411111XXXXXX1111",
            "cardholderName": "CARDHOLDER NAME"
        }
    ],
    "source": {
        "bindingId": "83309cde-a56d-7409-88dd-c02e00ab3428"
    },
    "target": {
        "bindingId": "83309cde-a56d-7409-88dd-c02e00ab3428",
        "clientId": "12345abc-d67e-8901-23fg-h45i67jk8901",
        "maskedPan": "411111XXXXXX1111"
    },
    "orderParams": {
        "paramname1": "paramvalue1",
        "paramname2": "paramvalue2"
    }
}

Запрос статуса выплаты

Для получения статуса выплаты необходимо использовать HTTPS POST API запрос /payouts/api/v2/getPayoutStatus.do

Параметры запроса

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

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/getPayoutStatus.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "payout_api_username",
    "password": "payout_api_password",
    "orderNumber": "payout_1"
}'

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

{
    "errorCode": "0",
    "errorMessage": "Успешно",
    "amount": 1234,
    "fee": 0,
    "currency": "398",
    "orderNumber": "1645458818059_12",
    "description": "Decent payout",
    "orderStatus": "2",
    "operationList": [
        {
            "datetime": "1665414462047",
            "operationType": "P2P_CREDIT",
            "amount": 1234,
            "currency": "643",
            "resultCode": 0,
            "resultCodeDescription": "Перевод исполнен",
            "refNum": "948498232196",
            "pan": "411111XXXXXX1111",
            "cardholderName": "CARDHOLDER NAME"
        }
    ],
    "target": {
        "bindingId": "83309cde-a56d-7409-88dd-c02e00ab3428",
        "clientId": "12345abc-d67e-8901-23fg-h45i67jk8901",
        "maskedPan": "411111XXXXXX1111"
    },
    "orderParams": {
        "name1": "value1",
        "name2": "value2"
    }
}

Создание связки получателя

Для создания связки получателя средств необходимо использовать API запрос /payouts/api/v2/createTargetBindingId.do. Данный запрос осуществляет создание связки с указанным идентификатором клиента и возвращает её параметры.

Параметры запроса

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

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/createTargetBindingId.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pan": "4111111111111111",
    "orderNumber": "1728285261_2111",
    "clientId": "TestClientID",
    "userName": "payout-api",
    "password": "payout-api"
}'

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

{
    "errorCode": "0",
    "errorMessage": "SUCCESS",
    "bindingId": "bff03edd-66ee-7f1d-ac01-936e088ae411",
    "clientId": "TestClientID",
    "maskedPan": "4111XXXXXXXX1111",
    "orderNumber": "1728285261_2111"
}

Создание связки плательщика

Для создания связки источника средств необходимо использовать API запрос /payouts/api/v2/createSourceBindingId.do. Данный запрос осуществляет создание связки с указанным идентификатором клиента и возвращает её.

После получения первого ответа необходимо будет пройти 3DS — см. Редирект на ACS. В результате будет получен второй ответ с параметрами созданной связки.

Параметры запроса

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

Первый ответ с параметрами для прохождения 3DS:

Второй ответ с данными связки:

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/createSourceBindingId.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pan": "4111111111111111",
    "clientId": "ClientId",
    "orderNumber": "1234567890",
    "cvc": "123",
    "year": "2034",
    "month": "12",
    "cardholderName": "Test Name",
    "userName": "test_user",
    "password": "test_user_password"
}

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

Пример ответа с данными 3DS:

{
    "acsUrl": "https://tst.rbstest.ru/payment/rest/getwhitepageurl.do?mdOrder=7bfa0573-b798-4a3e-9380-da1438f23f47&threeDsServerTransId=019eccbe-2b19-49d0-86aa-b6124b27e81a",
    "errorCode": "0",
    "info": "Ваш платёж обработан, происходит переадресация...",
    "is3DSVer2": false,
    "mdOrder": "7bfa0573-b798-4a3e-9380-da1438f23f47",
    "paReq": "White page paReq",
    "shortUrl": "https://tst.rbstest.ru/payment/acsRedirect.do?orderId=7bfa0573-b798-4a3e-9380-da1438f23f47",
    "termUrl": "https://​tst.rbstest.ru/payouts/api/v2/finish3DSv2.do"
    "orderNumber": "1234567890",
}

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

{
  "errorCode": "0",
  "errorMessage": "Успешно",
  "bindingId": "08bc10f3-67b3-705b-a8af-bf0407752e00",
  "clientId": "ClientId",
  "maskedPan": "4111XXXXXXXX1111",
  "merchantLogin": "testUser",
  "orderId": "7bfa0573-b798-4a3e-9380-da1438f23f47",
  "orderType": "createSourceBindingId",
  "orderNumber": "1234567890"
}

Запрос открытой компоненты ключа

Запрос /payouts/api/v2/keys.do возвращает публичный ключ модуля Выплат.

Для получения seToken, который можно передать в методе performPayout.do, необходимо зашифровать этим ключом строку timestamp/uuid/pan///////orderNumber с использованием алгоритма шифрования RSA "RSA/None/PKCS1Padding" с длиной ключа 2048.

Параметры запроса

Запрос направляется в модуль Выплат методом GET. Параметры отсутствуют.

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

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

Откройте в браузере ссылку https://3dsec.berekebank.kz/payouts/api/v2/keys.do или выполните запрос:

curl 'https://3dsec.berekebank.kz/payouts/api/v2/keys.do'

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

{
    "keys": [
    {
        "keyValue":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvnLlDQH6gu+6d7DT9EGa65QX7MgokW74S1gYIYTg3C6bf6z69Sg4EtXewCsp7txrCLBAkvns3Xf6tutYfVoFAIiZ45THXt7NNXTZw522AqfOVwDYUENwZgDqwh5LlAQv5H7Xb1gSF2H1vLPo4maZiuKiY64WzkHnDQJ6IzsHAArvXIA6f6QbRTqaI0GHUI7WHDRxNKh0p6z1HFLQxjj0yswR8eYTU2M0Zov7/4bMqB1Bgs4ByCi3AUeG2jtia04ycod2EROkddJcdPF23+G1JH0k2f3Y1XwKDuQI38oVY8HIaS1uriBrLWtCfw7sbtiowE4+cB7GOZsxtB9edKLygQIDAQAB",
        "keyExpiration":1758189688460,
        "protocolVersion":"RSA-2048"
    }]
}

Получение отчета по выплатам

Запрос getReportPayout.do позволяет получить выписку по выплатам Мерчанта.

Параметры запроса

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

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

curl --location 'https://3dsec.berekebank.kz/payouts/api/v2/getReportPayout.do' \
--header 'Content-Type: application/json' \
--data '{
  "startDate": "2025-02-03",     
  "endDate": "2025-02-06",    
  "reportName": "SSPV_AcctStatement",
  "userName": "test_user",
  "password": "test_user_password"
}'

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

{  
    "errorCode": "0",
    "errorMessage": "Успешно",
    "reportName": "SSPV_AcctStatement",
    "startDate": "2025-02-09",
    "endDate": "2025-04-09",
    "terminalId": "4225764450179702",
    "accountNumber": "KZ50914992240KZ001D8",
    "balanceInput": "50000000.00",
    "balanceOutput": "50000000.00",
    "turnoverDB": "2000000.00",
    "turnoverCR": "3000000.00",
    "transactions": [
        {
        "paymentOrderNumber": "25905147",
        "operationDate": "2025-02-04",
        "payerBank": "BankName",
        "payerName": "ТОО MerchantCompany",
        "debitAmount": "200.00",
        "creditAmount": "0.00",
        "paymentPurpose": "Test"
        }
     ]
}

Подпись запросов API

Модуль Выплат поддерживает подпись следующих API-запросов:

• registerPayout.do
• performPayout.do

Подпись выполняется так же, как для API-запросов в платежный шлюз с тем отличием, что тело API-запросов модуля Выплат передается только в формате JSON. Модуль выплат использует для подписи запросов тот же сертификат, что и платежный шлюз. Если вы еще не сгенерировали и не загрузили сертификат, сделайте это, следуя документации.

Ниже описан порядок реализации подписи API-запросов в модуль Выплат и приведены примеры тела запроса, его хэша и подписи.

Реализация подписи

1. Рассчитайте хеш SHA256 тела запроса следующим образом:

   • Используйте тело запроса в виде строки без пробелов и переносов строк, например: {"amount":953,"currency":"643","source":{"bindingId":"6e8eb975-e1ba-7072-9f7a-5b7848ca5a88"},"target":{"pan":"4111111111111111"},"client":{"name":"client_name"},"orderNumber":"1744367939_0689","description":"test","userName":"test_user","password":"test_user_password"}
   • Вычислите хэш SHA256 из этой строки в необработанных байтах (raw bytes).

   • Преобразуйте необработанные байты в кодировку base64. Результат для строки из примера выше:

     Hash Base64: hpMyyXfesrC9Z5lcRP5NiC81InQx9HRIDUHZKJg709A=

2. Для вычисленного хеша SHA256 (в кодировке base64) сгенерируйте подпись с помощью алгоритма RSA, используя закрытый ключ.

   В примере используется следующий ключ с паролем "123456":

   -----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFJDBWBgkqhkiG9w0BBQ0wSTAxBgkqhkiG9w0BBQwwJAQQl1SCKeYxJARFpK4+ vpuKWAICCAAwDAYIKoZIhvcNAgkFADAUBggqhkiG9w0DBwQIKpe1cwjenNkEggTI RMyPX7K5zOVqxxWepI3SA3craSsdbxuWCc+Aa2Zgr4ZsVRgFBb+kbv1ydjD86N9y YkZAkI5J45BVPscu9TQpCN41GkprwnWCs1NFiF1ba4yYcnPUOJW1kuyh1T2B692s A+SxWY+BZX9ffZ48LAvFwAhvIdVJaDEdtMfDpuUZXExA5aEu5Pn004ObmDHB/S3n F12c7D/gPG7hNu1Bs+0XHHVvKLzk5NFwqghFa3nms5yRQ/MeF4oElnv91KK+oxMR ceoOOq0dXAJ7Go1LsIrY9k2lhaKpQHkgIxZjHh4dPBdyY8OIppVvwx1q1WE8qtbi OK4t0MiMNBJCXcRebbYuBQhG5h0ppqGHmX+HpJ5bFEo5K+fHmu91nQbhM/uAaTio M8qABkPfl7Q3bG63r54PwQag2bMRgf4HNY9kZRvQgKoqp3/cTh25I1Fy86lGKKQH KZOOIQHtAGU0xlNRO9FK154M8Pa99qJ74R96gQE08+hBWHNKf3CLnU4jsJlLnqwz IKLGZ4plZgUD8VegG1HLINi1ahnkTvlSJFZy5ygZKn3kRmtBmhL+Ns4kr6+Bu/ra EMJsVwqQCenA0IuzL/0Boq+hMY9+tsD5JpMB3x7EJxzr7/3rk+4LMWpNpxTyY1M3 Dx/KNS7+zWT1pnFwHLTz4Vqt3npEEDJFTZuPUB2J9A/mXveE6Tr+pkLVFW3Pz4xm IuRoz4I1Ag494kUivV6XqW9eVIPmJP1X4zi/BXwM9JTFQNMDsbEyP2Wp+0yKs7J6 s7Rzd71/Y5xlO1iL++oW8QdhcoX46Pr0vqgu8aItl8irFtEItrp9qGd/SS8+HvAO POC8fzwzaK/qPP1ywSidv8wys7f1V9bE/9Me9rReqR8iA5VWG2ZqJG/4peszI9i9 IQ4NsidwhtjcqMv/sYvNpSlyckMZQrZy1oTU2IDPFakV/uhxC7nhkFW7wMrS5CMs Mxzrj7zbt19MVpfvjW+DrHDHgPz+qteki86p7dEwgbe8Sirg5D57HM3XLFki9yPu eLa1TUJXknPFgcnKWRVEJaNMefQPbt6yE0lEjsSobRXlqfueHqMycPqU3KJmwkaw 2xTCtNQmrulba5BOgNX68yiUNxPLeajg7I2SRN8DO7ZNCqbsmd3v9+hh63oYuMGK Un/QQlYLpz1+ZLo7pLwBfWpaPIMm5Zdzof2W+uQB6KHKV3r0c5vYh4RVG5gufrjn zRRdp1CmdllUqepsruvhSqPo79sNYwyavbI3/8J9BCIg2kUnYEPuXmubtw7/4/+c wMtW9xrsw52rBuB288H6kcDSOKp7hCFvNShSK+hFz5uOh8DFi+8DFLMxstDS1+Or wBPXMSytHAQ0WlF1TvQvgY0L6ZPcsWp0WF3BBbMuvFx3qF6TI/k4YFbCvfi+5Ei+ 99cefeMYEkudCGvQbWqy9W4HDsNNMPHVNZ8BCDm8+dD0QPLXPx7dKGErk8W7VSjm 51WAqtwruLNolrrQL2AgKCp1Q5SQwas1Q9h7QOBTmDlU5ewbgogKMkUmTSzwZzYU S7nOt9PODRH5xOfYbgVdgJPfqDqK3hLKwl0zGRbs4vUFnlOe9uMK7mvDtQrmxndX o02fBHS9SFyMj6wfXjV+cH3INGpvsenO
-----END ENCRYPTED PRIVATE KEY-----

   Полученная подпись:

   gEU2NarCF478VyMYG7/wqjHDP4Ok08zCaRshUocko872j3AHi91G6S/xyRYK4gYykK+F2mXb7vZJdb3WzvL+If7MlPnDl7oC7hDFp8iR75ZfqT2k4znnqOQfuNa0mBTkUG3d+4YXtyTdY0f9rZCnWU+ANWQGXmTWxHhFf1vmsYQAD3q4aMEuoksXnhi32e14N/GUx26+8MiFvLVjb7Rgynwriv5xFlQ1HjFDQXokAbIwWZ0HrulGZvBkxQs0HIKxZJPegpJt2UODcqfhvBwmTYeXdTaqNUqvcVG041XjH3aEx3AJUwLZLEnCJpPWwcXxJ++EL3L7lEz2kRtoBOKYMQ==

3. Передайте сгенерированный хэш (X-Hash) и значение подписи (X-Signature) в заголовке запроса. Запрос будет выглядеть так:

curl 'https://sb02.tst.rbstest.ru/payouts/api/v2/performPayout.do' \
-H 'X-hash: hpMyyXfesrC9Z5lcRP5NiC81InQx9HRIDUHZKJg709A=' \
-H 'X-signature: gEU2NarCF478VyMYG7/wqjHDP4Ok08zCaRshUocko872j3AHi91G6S/xyRYK4gYykK+F2mXb7vZJdb3WzvL+If7MlPnDl7oC7hDFp8iR75ZfqT2k4znnqOQfuNa0mBTkUG3d+4YXtyTdY0f9rZCnWU+ANWQGXmTWxHhFf1vmsYQAD3q4aMEuoksXnhi32e14N/GUx26+8MiFvLVjb7Rgynwriv5xFlQ1HjFDQXokAbIwWZ0HrulGZvBkxQs0HIKxZJPegpJt2UODcqfhvBwmTYeXdTaqNUqvcVG041XjH3aEx3AJUwLZLEnCJpPWwcXxJ++EL3L7lEz2kRtoBOKYMQ== -H 'Content-Type: application/json' \
-d '{"amount":953,"currency":"643","source":{"bindingId":"6e8eb975-e1ba-7072-9f7a-5b7848ca5a88"},"target":{"pan":"4111111111111111"},"client":{"name":"client_name"},"orderNumber":"1744367939_0689","description":"test","userName":"test_user","password":"test_user_password"}'

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

• Все параметры запроса включены в тело запроса (не в URL).

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

  --header 'content-type: application/json'

• Запрос содержит правильный логин и пароль пользователя API.

• Заголовок X-Hash содержит хэш SHA256 тела запроса (рассчитывается на Шаге 1).

• Заголовок X-Signature содержит подпись для хэша SHA256, рассчитанную с помощью алгоритма RSA с использованием закрытого ключа (генерируется на Шаге 2).

Пример кода генерации подписи на Python

import base64
import hashlib
from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend

data = """{"amount":953,"currency":"643","source":{"bindingId":"6e8eb975-e1ba-7072-9f7a-5b7848ca5a88"},"target":{"pan":"4111111111111111"},"client":{"name":"client_name"},"orderNumber":"1744367939_0689","description":"test","userName":"test_user","password":"test_user_password"}"""

priv_key_pem = """
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFJDBWBgkqhkiG9w0BBQ0wSTAxBgkqhkiG9w0BBQwwJAQQl1SCKeYxJARFpK4+
vpuKWAICCAAwDAYIKoZIhvcNAgkFADAUBggqhkiG9w0DBwQIKpe1cwjenNkEggTI
RMyPX7K5zOVqxxWepI3SA3craSsdbxuWCc+Aa2Zgr4ZsVRgFBb+kbv1ydjD86N9y
YkZAkI5J45BVPscu9TQpCN41GkprwnWCs1NFiF1ba4yYcnPUOJW1kuyh1T2B692s
A+SxWY+BZX9ffZ48LAvFwAhvIdVJaDEdtMfDpuUZXExA5aEu5Pn004ObmDHB/S3n
F12c7D/gPG7hNu1Bs+0XHHVvKLzk5NFwqghFa3nms5yRQ/MeF4oElnv91KK+oxMR
ceoOOq0dXAJ7Go1LsIrY9k2lhaKpQHkgIxZjHh4dPBdyY8OIppVvwx1q1WE8qtbi
OK4t0MiMNBJCXcRebbYuBQhG5h0ppqGHmX+HpJ5bFEo5K+fHmu91nQbhM/uAaTio
M8qABkPfl7Q3bG63r54PwQag2bMRgf4HNY9kZRvQgKoqp3/cTh25I1Fy86lGKKQH
KZOOIQHtAGU0xlNRO9FK154M8Pa99qJ74R96gQE08+hBWHNKf3CLnU4jsJlLnqwz
IKLGZ4plZgUD8VegG1HLINi1ahnkTvlSJFZy5ygZKn3kRmtBmhL+Ns4kr6+Bu/ra
EMJsVwqQCenA0IuzL/0Boq+hMY9+tsD5JpMB3x7EJxzr7/3rk+4LMWpNpxTyY1M3
Dx/KNS7+zWT1pnFwHLTz4Vqt3npEEDJFTZuPUB2J9A/mXveE6Tr+pkLVFW3Pz4xm
IuRoz4I1Ag494kUivV6XqW9eVIPmJP1X4zi/BXwM9JTFQNMDsbEyP2Wp+0yKs7J6
s7Rzd71/Y5xlO1iL++oW8QdhcoX46Pr0vqgu8aItl8irFtEItrp9qGd/SS8+HvAO
POC8fzwzaK/qPP1ywSidv8wys7f1V9bE/9Me9rReqR8iA5VWG2ZqJG/4peszI9i9
IQ4NsidwhtjcqMv/sYvNpSlyckMZQrZy1oTU2IDPFakV/uhxC7nhkFW7wMrS5CMs
Mxzrj7zbt19MVpfvjW+DrHDHgPz+qteki86p7dEwgbe8Sirg5D57HM3XLFki9yPu
eLa1TUJXknPFgcnKWRVEJaNMefQPbt6yE0lEjsSobRXlqfueHqMycPqU3KJmwkaw
2xTCtNQmrulba5BOgNX68yiUNxPLeajg7I2SRN8DO7ZNCqbsmd3v9+hh63oYuMGK
Un/QQlYLpz1+ZLo7pLwBfWpaPIMm5Zdzof2W+uQB6KHKV3r0c5vYh4RVG5gufrjn
zRRdp1CmdllUqepsruvhSqPo79sNYwyavbI3/8J9BCIg2kUnYEPuXmubtw7/4/+c
wMtW9xrsw52rBuB288H6kcDSOKp7hCFvNShSK+hFz5uOh8DFi+8DFLMxstDS1+Or
wBPXMSytHAQ0WlF1TvQvgY0L6ZPcsWp0WF3BBbMuvFx3qF6TI/k4YFbCvfi+5Ei+
99cefeMYEkudCGvQbWqy9W4HDsNNMPHVNZ8BCDm8+dD0QPLXPx7dKGErk8W7VSjm
51WAqtwruLNolrrQL2AgKCp1Q5SQwas1Q9h7QOBTmDlU5ewbgogKMkUmTSzwZzYU
S7nOt9PODRH5xOfYbgVdgJPfqDqK3hLKwl0zGRbs4vUFnlOe9uMK7mvDtQrmxndX
o02fBHS9SFyMj6wfXjV+cH3INGpvsenO
-----END ENCRYPTED PRIVATE KEY-----
"""

# HASH в base64
hash_bytes = hashlib.sha256(data.encode('utf-8')).digest()
hash_base64 = base64.b64encode(hash_bytes).decode('utf-8')
print("Hash base64: ", hash_base64)

# Подпись
private_key = serialization.load_pem_private_key(
    priv_key_pem.encode('utf-8'),
    password=b'123456',  # Пароль для расшифровки ключа
    backend=default_backend()
)

signature = private_key.sign(
    hash_base64.encode("utf-8"),
    padding.PKCS1v15(),
    hashes.SHA256()
)

signature_base64 = base64.b64encode(signature).decode('utf-8')
print("Signature: ", signature_base64)

Ключ для примера Python должен быть в PEM-формате с элементами BEGIN и END.

Описание ошибок