Перейти к содержанию

Совершение выплаты

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

URL

Метод: POST

  • Production: https://api.pay.kvell.group/v1/orders/account2card
  • Stage: https://api.pay.stage.kvell.group/v1/orders/account2card

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

Название
 Тип данных Обязательно Описание
amount integer Да Сумма в копейках
recipient_pan string Да PAN карты получателя
description string Да Описание к транзакции
transaction string Да Уникальный номер транзакции на стороне мерчанта
customer string Нет Email / телефон клиента
extra_data json Нет Дополнительные данные
fiscal_data json Нет Фискализация чека по Ф3-54

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

{
  "recipient_pan": "4111111111111111",
  "amount": 100,
  "transaction": "344frge530jm",
  "description": "Выплата",
  "customer": "user@user.com"
}

Заголовки запроса

Название Тип данных Обязательно Описание
X-Api-Key string Да Уникальный идентификатор магазина
X-Signature string Да Подпись

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

При формировании запроса необходимо использовать ЭЦП. Используется алгоритм RSA/SHA256. Данное сообщение необходимо передавать в заголовке HTTP запроса в параметре X-Signature.

Ключ для ЭЦП

  1. Мерчант на своей стороне генерирует ключ: 
    $ openssl genrsa -out privatekey.pem 4096
  2. Получает от ключа публичную часть: 
    $ openssl rsa -in privatekey.pem -pubout -out publickey.pem
  3. Публичную часть ключа необходимо отправить в тех-поддержку, которая загружает содержимое в систему. проверка подписи мерчанта X-signature происходит при запросе. Все параметры запроса должны быть отсортированы по ключам.

Примеры кода

import base64
import json
import requests

from Crypto.Hash import SHA256
from Crypto.PublicKey import RSA
from Crypto.Signature import PKCS1_v1_5

x_api_key = '7d1f800c-ec7d-4597-a65f-cd7896934b5a'
secret_key = 'ddee181d-f8e8-4f3f-90bf-1d7e8f122d9a'

params = {
    "recipient_pan": "4111111111111111",
    "amount": 10000,
    "transaction": "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
    "description": "test_transaction_1",
    "customer": "test@test.com"
}

# сортировка по ключам параметров
data = json.dumps(params, separators=(',', ':'), sort_keys=True)

key = RSA.importKey(open('privatekey.pem').read())
digest = SHA256.new('{}{}'.format(data, secret_key).encode('utf8'))
signer = PKCS1_v1_5.new(key)
signature = signer.sign(digest)
x_signature = base64.b64encode(signature)

response = requests.post(
    'https://api.host/v1/orders/account2card',
    data=data,
    headers={
        'Content-Type': 'application/json; charset=UTF-8',
        'x-api-key': x_api_key,
        'x-signature': x_signature,
    }
)

<?php
function recursive_ksort( &$array) {
    foreach($array as & $value) {
        if (is_array($value)) recursive_ksort($value);
     }
     return ksort($array);
}

$secret_key = 'ddee181d-f8e8-4f3f-90bf-1d7e8f122d9a';

$params = [
     "recipient_pan" = > "4111111111111111"
     "amount" = > 10000,
     "transaction" = > "f4462ba6-37c5-4455-b0b2-53b179f7a25c",
     "description" = > "test_transaction_1",
     "customer" = > "test@test.com"
];

// сортировка по ключам параметров
recursive_ksort($params);

$data = json_encode($params);

$digest = $data. $secret_key;

$key = openssl_pkey_get_private(file_get_contents('privatekey.pem'));

$signature = "";

openssl_sign($digest, $signature, $key, "sha256WithRSAEncryption");

$x_signature = base64_encode($signature);

print("x-signature: " . $x_signature . "\n");

?>

Пример на openssl

Подпись для запроса на выплату можно сформировать с помощью команды openssl

openssl dgst -sha256 -sign /path/to/private_key.pem /path/to/data_to_be_signed | base64 | tr -d '\n'

Где:

  • /path/to/private_key.pem - полный путь к файлу приватного ключа
  • /path/to/data_to_be_signed - полный путь к файлу с данными, которые требуется подписать, т.е. в файле будет тело POST-запроса с прибавленным секретным ключом (secret_key).

Содержание файла с данными для подписи data_to_be_signed:

{"amount":100,"customer":"123","description":"test","recipient_pan":"4111111111111111","transaction":"4faf68bf-d484-40a0-968e-db867e1fd41d"}ef6710b3-b9dc-47ab-9f64-71a002e26a91

Пример сформированной подписи:

i/4LlP2lh5gr8vgKaWjvXZtlgIEpNvyWvbfv3U7XbZNw/F+hHvlDIMO7UlFd5hranniT8APE+RF5tS5dhOIfZ/Ks7GurvnTz6ZcfplOVKen4LeEXRzgA8pDsBj78aPOOoyy8wWl3AgsuqFEI+xu5V/XLIYVgMocCgn5YSg6bfuFW3SAdcj5sGpwg8v9YJ7uf6Kze7ScXuMViE7e+NCK0Qtzr5ZmOOHg2f/QKfnLzOLhro0lK+Ma5yBJWy/0Udv4l53xbsgVwROsm6WfXJRgMUsFpGVGTLytezDUnclIkJam7l9auUYkmI2yPiXtT2RnMZynAsh1zcVTuJC3hyeuKNAUm93qOwossSAjKMW1p48Ecy9vOd66FHvErgYWGXCZL2IhWHNwA1QsM+9t7KqrsRROeFgIs/lw6UwKUmrQlGftbZOsJx/0Jlr8A2jf5bNoiVyUlyz9PNFJkTqH1l5usAt/egf6M/uOmyKk1L9VV+uet7W+2vYbAqhTVgWmUyonuIBM4xTU6wzGCW1uQL+XzjTm8YORZOhBZwYa4qX+PWqPA45eULqkFG+cA7MLFZEWVZwswEsmpMCkuHaf4T3/jGmE1slrUONj8RxXUS200olFUk6buS1ymn1+KyeNEbETKRRuJeKLe5MSE5wR96CPhXJ1Lu5081+UdF5M46RPnhDk=

Ответ запроса

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

{
  "order": {
    "id": "string",
    "status": "string", // финальный статус транзакции
    "transaction": "string",
    "amount": 0,
    "commission": 0,
    "description": "string",
    "created_at": "string"
  },
  "status": "string" // статус отправки OTP-кода, если включена данная опция 
}

{
  "errors": [
    {
      "message": "string",
      "code": 0
    }
  ]
}
  • Если получен ответ со статусом 5XX, транзакцию необходимо оставить в обработке и отправить запрос на метод получения статуса транзакции.
  • Данные ошибки могут возникнуть по различным причинам: на стороне взаимодействия сети, технических сбоев сервера или ПО.
  • В случае повторного возникновения данной проблемы рекомендуется обратиться в службу поддержки.

В ответ приходит объект order, который служит получением статуса выплаты и параметр order.status.

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

{
  "order": null,
  "status": "wait_confirm"
}

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

Название Тип данных Описание
id string ID платежа в системе
amount integer Сумма в копейках
status string Статус транзакции
description string Описание к транзакции
transaction string Уникальный номер транзакции на стороне мерчанта
created_at string Дата создания транзакции
commission string Комиссия в копейках

Список статусов

Название Описание
new Новая транзакция
processing Транзакция обрабатывается
canceled Транзакция отклонена
completed Транзакция выполнена