Интеграция Банков в сеть HeyPay

Руководство по подключению автоматизированных банковских систем (АБС), мобильных приложений банков и платёжных шлюзов к открытому межбанковскому клирингу HeyPay.

Архитектура и Порядок расчётов

1. Резолвинг: Банк-отправитель запрашивает POST /heypay/apibank/api/resolve для проверки существования номера в целевом банке.

2. Блокировка: Банк-отправитель холдирует средства на счёте своего клиента.

3. Клиринг: Банк-отправитель шлёт запрос POST /heypay/apibank/api/transfer. Шлюз HeyPay списывает сумму с корсчёта банка-отправителя и начисляет банку-получателю.

4. Уведомление: HeyPay генерирует глобальный чек UTR и отправляет подписанный Webhook в АБС банка-получателя для финального зачисления.

Аутентификация запросов АБС

Каждый запрос от сервера банка должен содержать HTTP-заголовки аутентификации:

X-HeyPay-Client-ID: bid_xxxxxxxxxxxx
X-HeyPay-Client-Secret: bsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Методы Межбанковского API

GET /heypay/apibank/api/banks

Без авторизации

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

curl -X GET https://heycat.online/heypay/apibank/api/banks

POST /heypay/apibank/api/resolve

Валидация

Проверка номера телефона / счета получателя перед отправкой перевода.

curl -X POST https://heycat.online/heypay/apibank/api/resolve   -H "Content-Type: application/json"   -d '{
    "recipient_bank_id": "heycat",
    "recipient_account": "+79991234567"
  }'

POST /heypay/apibank/api/transfer

Клиринг

Инициирование межбанковского клиринга со списанием с корсчета банка-отправителя.

curl -X POST https://heycat.online/heypay/apibank/api/transfer   -H "X-HeyPay-Client-ID: bid_xxxxxxxx"   -H "X-HeyPay-Client-Secret: bsec_xxxxxxxx"   -H "Content-Type: application/json"   -d '{
    "sender_account": "+79001112233",
    "sender_name": "Алексей С.",
    "recipient_bank_id": "heycat",
    "recipient_account": "+79991234567",
    "amount": 500.00,
    "comment": "Оплата услуг",
    "external_ref": "ABS-TX-9841"
  }'

GET /heypay/apibank/api/balance

Баланс

curl -X GET https://heycat.online/heypay/apibank/api/balance   -H "X-HeyPay-Client-ID: bid_xxxxxxxx"   -H "X-HeyPay-Client-Secret: bsec_xxxxxxxx"

Входящий Webhook в АБС банка (Зачисления)

При поступлении перевода на клиента вашего банка, HeyPay Switch отправляет HTTP POST на ваш webhook_transfer_url:

{
  "event": "interbank.incoming_transfer",
  "utr": "HP-4F2A-8B1E",
  "sender_bank_id": "bnk_alpha",
  "sender_bank_name": "AlphaSand Bank",
  "sender_account": "+79001112233",
  "recipient_bank_id": "bnk_yourbank",
  "recipient_account": "+79991234567",
  "amount": 500.00,
  "currency": "ANL",
  "comment": "Оплата услуг",
  "external_ref": "ABS-TX-9841"
}

Подпись передается в заголовке X-HeyPay-Signature: sha256(utr + amount + client_secret).

Готовый PHP Bank Gateway SDK

🐘 HeyPayBankClient.php

<?php
class HeyPayBankClient {
    private $clientId;
    private $clientSecret;
    private $apiBase;

    public function __construct($clientId, $clientSecret, $apiBase = "https://heycat.online") {
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
        $this->apiBase = rtrim($apiBase, '/');
    }

    public function sendTransfer($fromAccount, $senderName, $toBankId, $toAccount, $amount, $comment = "", $extRef = null) {
        $url = $this->apiBase . "/heypay/apibank/api/transfer";
        $data = [
            "sender_account" => (string)$fromAccount,
            "sender_name" => (string)$senderName,
            "recipient_bank_id" => (string)$toBankId,
            "recipient_account" => (string)$toAccount,
            "amount" => (float)$amount,
            "comment" => $comment,
            "external_ref" => $extRef ?: ("REF-" . time())
        ];

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Content-Type: application/json",
            "X-HeyPay-Client-ID: " . $this->clientId,
            "X-HeyPay-Client-Secret: " . $this->clientSecret
        ]);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        $res = curl_exec($ch);
        curl_close($ch);
        return json_decode($res, true);
    }

    public function verifyIncomingWebhook($rawJson, $receivedSignature) {
        $data = json_decode($rawJson, true);
        if (!$data) return false;
        $check = $data['utr'] . $data['amount'] . $this->clientSecret;
        return hash_equals(hash('sha256', $check), (string)$receivedSignature);
    }
}
?>

Готовый Python Bank Gateway SDK

🐍 heypay_bank.py

import requests
import hashlib

class HeyPayBankGateway:
    def __init__(self, client_id, client_secret, api_base="https://heycat.online"):
        self.client_id = client_id
        self.client_secret = client_secret
        self.api_base = api_base.rstrip('/')

    def send_transfer(self, sender_account, sender_name, recipient_bank_id, recipient_account, amount, comment=""):
        url = f"{self.api_base}/heypay/apibank/api/transfer"
        headers = {
            "Content-Type": "application/json",
            "X-HeyPay-Client-ID": self.client_id,
            "X-HeyPay-Client-Secret": self.client_secret
        }
        payload = {
            "sender_account": sender_account,
            "sender_name": sender_name,
            "recipient_bank_id": recipient_bank_id,
            "recipient_account": recipient_account,
            "amount": float(amount),
            "comment": comment
        }
        r = requests.post(url, json=payload, headers=headers)
        return r.json()

    def verify_webhook(self, utr, amount, signature):
        raw = f"{utr}{amount}{self.client_secret}"
        expected = hashlib.sha256(raw.encode()).hexdigest()
        return expected == signature

Интеграция Банков в сеть HeyPay

Пополнение счёта