Інтеграції
Створення рахунку (Checkout)
Щоб створити рахунок, спочатку потрібно отримати ID платіжного методу.
- Якщо ви завжди використовуєте один і той самий метод, зверніться до служби підтримки.
- Якщо використовуєте різні методи, надішліть запит на наступну адресу.
Endpoint: /v1/payment-method/list
Метод: GET
Приклад відповіді:
{
"data": [
{
"id": "11111",
"title": "Cards International",
"countries": ["US", "GB", "FR"],
"currencies": ["USD", "EUR"],
"icon": "",
"fields": [
{
"name": "cardNumber",
"title": "card number"
},
{
"name": "holderName",
"title": "holder name"
}
]
},
{
"id": "11117",
"title": "Alipay",
"countries": ["CN"],
"currencies": ["CNY"],
"icon": "",
"fields": []
}
]
}
Використовуйте значення id як payment_method під час створення рахунку.
Створити рахунок
Endpoint: /v1/payment/create
Метод: POST
Запит (мінімальні параметри):
{
"amount": "10.03",
"currency": "USD",
"payment_method": "11111",
"save_card": "1",
"customer": {
"email": "[email protected]",
"name": "John Doe",
"ip": "192.168.1.1"
},
"urls": {
"success": "https://example.com/success",
"fail": "https://example.com/fail",
"notification": "https://example.com/notification"
},
"reference": "3d7d949e-94fb-4b8b-bc32-7c7f46bcd638",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Запит із збереженою карткою:
{
"amount": "10.03",
"currency": "USD",
"payment_method": "11111",
"customer": {
"email": "[email protected]",
"name": "John Doe",
"ip": "192.168.1.1"
},
"urls": {
"success": "https://example.com/success",
"fail": "https://example.com/fail",
"notification": "https://example.com/notification"
},
"reference": "3d7d949e-94fb-4b8b-bc32-7c7f46bcd638",
"card": {
"cardId": "050159eb-6af3-407c-84c0-ca1680711a77"
},
"metadata": {
"key1": "value1",
"key2": "value2"
}
}
Відповідь:
{
"data": {
"payment_id": "...",
"amount": "10.03",
"currency": "USD",
"status": "pending",
"reference": "...",
"url": "https://api.beezyycashier.com/process/...",
"method": "get"
}
}
Перенаправте клієнта на url.
Отримання інформації про платіж
За ID платежу
Endpoint: /v1/payment/{payment_id}
Метод: GET
За посиланням
Endpoint: /v1/payment/by-reference/{reference}
Метод: GET
Приклад відповіді
{
"data": {
"payment_id": "...",
"amount": "10.03",
"status": "success",
"transactions": [ ... ]
}
}
Повернення коштів
Endpoint: /v1/refund/create
Метод: POST
{
"reference": "...",
"payment_id": "...",
"amount": "10.03",
"currency": "USD"
}
Відповідь:
{
"data": {
"refund_id": "...",
"amount": "10.03",
"status": "success",
"message": "Повернення прийнято"
}
}
Збереження картки
Endpoint: /v1/client/card/save
Метод: POST
{
"payment_method": "11111",
"customer": {
"email": "[email protected]",
"name": "John Doe",
"ip": "192.168.1.1"
},
"urls": {
"success": "https://example.com/success",
"fail": "https://example.com/fail",
"notification": "https://example.com/notification"
},
"reference": "...",
"metadata": {
"key1": "value1"
}
}
Інформація про клієнта
За email:
GET: /v1/client/[email protected]
За ID картки:
GET: /v1/client/card/{card_id}
Дії з карткою
- Деактивувати:
GET /v1/client/card/deactivate/{card_id} - Активувати:
GET /v1/client/card/activate/{card_id}
Виведення коштів
Одиничне:
POST: /v1/withdrawal/create
{
"reference": "...",
"amount": "10.03",
"currency": "USD",
"withdrawal_method_id": "22222",
"receiver": {
"cardNumber": "...",
"name": "John Doe",
"email": "[email protected]"
},
"urls": {
"notification": "https://example.com/notify"
}
}
Масове:
POST: /v1/withdrawal/create-mass
Тіло: масив об’єктів виведення
За Stack ID:
GET: /v1/withdrawal/{stack_id}
Підпис повідомлення
Ви можете перевірити повідомлення за заголовком підпису.
- Алгоритм:
HMAC-SHA512 - Підпис:
hash_hmac('sha512', raw_request_body, project_key) - Заголовок:
signature - Для повідомлень про виведення коштів використовуйте ключ виведення проєкту замість платіжного ключа.
- Хешуйте сире JSON-тіло саме в тому вигляді, у якому його отримано — не перекодовуйте та не переформатовуйте перед хешуванням.
Приклади генерації підпису
Усі сніпети нижче дають однаковий результат у нижньому регістрі hex для однакових raw_body та project_key.
PHP
$signature = hash_hmac('sha512', $rawBody, $projectKey);
Python
import hmac
import hashlib
signature = hmac.new(
project_key.encode('utf-8'),
raw_body.encode('utf-8'),
hashlib.sha512
).hexdigest()
Go
import (
"crypto/hmac"
"crypto/sha512"
"encoding/hex"
)
mac := hmac.New(sha512.New, []byte(projectKey))
mac.Write([]byte(rawBody))
signature := hex.EncodeToString(mac.Sum(nil))
Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(new SecretKeySpec(
projectKey.getBytes(StandardCharsets.UTF_8),
"HmacSHA512"
));
byte[] hash = mac.doFinal(rawBody.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : hash) sb.append(String.format("%02x", b));
String signature = sb.toString();
Важливо: raw_body — це саме ті байти, які ви прочитали з тіла HTTP-запиту, до будь-якого json_decode / json.loads. Якщо спершу розпарсити JSON і потім сериалізувати його назад, зміняться пробіли та порядок ключів — і перевірка підпису не пройде.