Выплаты

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

Выплата создаётся по API и обрабатывается асинхронно. Статус выплаты обновляется автоматически, и результат передаётся через webhook.

Создание выплаты

Важно: Для создания выплаты у терминала должен быть достаточный доступный баланс (balance - on hold).

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


POST https://api.capitalpay.biz/api/public/payout
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "amount": 100.50,
  "currency_code": "KZT",
  "terminal_uuid": "3e377cd4-8fdb-46ff-a748-78349c2bdf70",
  "knp": 332,
  "recipient_name": "John Doe",
  "card_number": "4111111111111111",
  "phone_number": "+77089858290",
  "description": "Payout to client",
  "external_payout_id": 123,
  "external_client_id": 4001,
  "external_data": {
    "order_id": 777,
    "comment": "Test payout"
  },
  "webhook_url": "https://example.com/webhook"
}

Важно: Необходимо передать либо card_number, либо phone_number. Минимум одно из этих полей обязательно.

Подпись запроса передаётся в HTTP-заголовке Signature и формируется с использованием HMAC SHA256.

Общий алгоритм генерации подписи и примеры на разных языках описаны в разделе Создание подписи.

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

Для формирования подписи используются следующие поля в указанном порядке. Если поле отсутствует, используется пустое значение.

amount
card_number
currency_code
knp
phone_number
terminal_uuid


{amount};{card_number};{currency_code};{knp};{phone_number};{terminal_uuid};
100.5;4111111111111111;KZT;332;;3e377cd4-8fdb-46ff-a748-78349c2bdf70;

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


HTTP/1.1 200 OK
{
    "success": true,
    "data": {
        "uuid": "b82d4128-058c-4c75-971c-43057c8a3aa3",
        "amount": 100.50,
        "fee_amount": null,
        "currency_code": "KZT",
        "status_id": 2,
        "status_label": "Pending",
        "knp": "332",
        "description": "Payout to client",
        "external_payout_id": 123,
        "external_client_id": 4001,
        "external_data": {
            "order_id": 777,
            "comment": "Test payout"
        },
        "webhook_url": "https://example.com/webhook",
        "terminal_uuid": "24ea15f7-6681-4f19-8e76-cda87554822d",
        "shop_uuid": "57df258e-b528-444e-b22d-5743d648fb3c",
        "created_at": "2025-01-01T10:01:45.000000Z",
        "card_pan": "411111******1111"
    }
}

Поля запроса

Поле	Тип	Обязательное	Описание	Примечания
`amount`	number	Да	Сумма выплаты	Минимум: `0.01`
`currency_code`	string	Да	Код валюты	Допустимое значение: `KZT`
`terminal_uuid`	string	Да	UUID терминала для выплат	Должен существовать
`knp`	integer	Да	KNP код операции
`recipient_name`	string	Да	Имя и фамилия получателя	Формат: `First Last`
`card_number`	string	Условно	Номер карты	Обязателен, если нет `phone_number`
`phone_number`	string	Условно	Телефон получателя	Обязателен, если нет `card_number`
`description`	string	Да	Описание выплаты
`external_payout_id`	integer	Да	Внешний ID выплаты	Для идемпотентности
`external_client_id`	integer	Да	Внешний ID клиента
`external_data`	object	Да	Произвольные данные	JSON-объект
`webhook_url`	string	Да	URL для вебхуков	Валидный URL

Валидация получателя

Имя получателя (recipient_name)

Должно содержать имя и фамилию, разделённые пробелом
Допустимы только буквы, дефисы и апострофы

Примеры допустимых значений:

John Doe
Jean-Paul O'Connor

Статусы выплаты

Статус	Описание
`Created`	Выплата создана
`Pending`	Отправлена на обработку
`Completed`	Успешно завершена
`Failed`	Ошибка при выполнении

Webhooks

Для выплат используются отдельные webhook-уведомления.

Если при создании выплаты был указан webhook_url, платформа отправляет
HTTP POST запрос на указанный адрес при изменении статуса выплаты.

Пример webhook выплаты


{
  "event": "payout.status.update",
  "data": {
    "payout_uuid": "b82d4128-058c-4c75-971c-43057c8a3aa3",
    "external_payout_id": 123,
    "external_client_id": 4001,
    "amount": 100.50,
    "fee_amount": null,
    "currency_code": "KZT",
    "status_id": 3,
    "status": "Completed",
    "external_data": {
      "order_id": 777,
      "comment": "Test payout"
    },
    "description": "Payout to client",
    "shop_uuid": "fc81fd31-1618-484a-ad44-8a61e84926f5",
    "terminal_uuid": "3e377cd4-8fdb-46ff-a748-78349c2bdf70",
    "card_pan": "411111******1111"
  }
}

Webhook-запросы подписываются платформой CapitalPay.

Подпись передаётся в HTTP-заголовке Signature. Проверка подписи позволяет убедиться, что webhook был отправлен платформой, а данные в запросе не были изменены.

Алгоритм генерации подписи, а также примеры на PHP, Python и Node.js описаны в разделе Создание подписи.

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

Для формирования подписи используются следующие поля в указанном порядке:

amount
currency_code
external_client_id
external_payout_id
payout_uuid
status
status_id

Пример строки для подписи


{amount};{currency_code};{external_client_id};{external_payout_id};{payout_uuid};{status};{status_id};
100.50;KZT;4001;123;b82d4128-058c-4c75-971c-43057c8a3aa3;Completed;3;

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

В дополнение к созданию выплаты, платформа предоставляет дополнительные операции, которые позволяют проверять данные получателя и получать актуальный статус выплаты.

Проверка получателя выплаты

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

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

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


GET https://api.capitalpay.biz/api/public/payout/lookup-recipient
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "phone": "+77089858290",
  "terminal_uuid": "3e377cd4-8fdb-46ff-a748-78349c2bdf70"
}

Формирование подписи

Подпись запроса передаётся в HTTP-заголовке Signature и формируется с использованием HMAC SHA256.

Общий алгоритм генерации подписи и примеры на разных языках описаны в разделе Создание подписи.

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

Для формирования подписи используется следующее поле в указанном порядке:

terminal_uuid
phone

Пример строки для подписи


{terminal_uuid};{phone};
3e377cd4-8fdb-46ff-a748-78349c2bdf70;+77089858290;

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


HTTP/1.1 200 OK
{
  "success": true,
  "data": {
    "location": "Visa",
    "masked_pan": "************9370",
    "full_name": "NATALYA M.",
    "issuer_name": "JSC Bank CenterCredit",
    "country": "KAZ"
  }
}

Поля запроса

Поле	Тип	Обязательное	Описание	Примечания
`phone`	string	Да	Номер телефона получателя выплаты	Формат: `+{код_страны}{номер}` без пробелов
`terminal_uuid`	string	Да	UUID терминала для выплат	Должен существовать

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

Метод используется для получения актуальной информации о выплате по её UUID с использованием HMAC-подписи.

Может применяться для:

проверки текущего статуса выплаты
повторного запроса результата

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


GET https://api.capitalpay.biz/api/public/payout/{payout_uuid}
 
Accept: application/json
Signature: {generated_hmac_signature}

Формирование подписи

Подпись запроса передаётся в HTTP-заголовке Signature и формируется с использованием HMAC SHA256.

Общий алгоритм генерации подписи и примеры на разных языках описаны в разделе Создание подписи.

Обратите внимание:
Для данного метода используется только одно поле - payout_uuid. Использование других полей приведёт к некорректной подписи.

Для формирования подписи используется следующее поле в указанном порядке:

payout_uuid

Пример строки для подписи


{payout_uuid};
b9e2d72a-7894-4b4c-b726-1b7e223fbb45;

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


HTTP/1.1 200 OK
{
    "success": true,
    "data": {
        "uuid": "b82d4128-058c-4c75-971c-43057c8a3aa3",
        "amount": 100.5,
        "fee_amount": null,
        "currency_code": "KZT",
        "status_id": 3,
        "status_label": "Completed",
        "knp": "332",
        "description": "Payout to client",
        "external_payout_id": 123,
        "external_client_id": 4001,
        "external_data": {
            "order_id": 777,
            "comment": "Test payout"
        },
        "webhook_url": "https://example.com/webhook",
        "terminal_uuid": "24ea15f7-6681-4f19-8e76-cda87554822d",
        "shop_uuid": "57df258e-b528-444e-b22d-5743d648fb3c",
        "created_at": "2025-01-01T10:01:45.000000Z",
        "card_pan": "411111******1111"
    }
}

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

Параметр	Тип	Где передаётся	Обязательный	Описание
`payout_uuid`	string	path	Да	UUID выплаты