Введение

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

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

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

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

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

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

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

1. Оператор (или Получатель) принимает решение о проведении выплаты и выполняет на стороне Сервиса Партнера необходимые действия;
2. Сервис Партнера отправляет запрос на осуществление выплаты (performPayout.do) в Модуль Выплат и передает все необходимые параметры выплаты;
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. Сервис Партнера уведомляет Оператора (или Получателя) о статусе выплаты.

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"
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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