Перейти до змісту

Інтеграції

Створення рахунку (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 і потім сериалізувати його назад, зміняться пробіли та порядок ключів — і перевірка підпису не пройде.