Вступ/Автентифікація

Автентифікація та підписання запитів

Підписуйте API-запити за допомогою HMAC-SHA256, використовуючи project UUID та API key.

Кожен API-запит (окрім вхідних webhooks) повинен містити ваш project UUID та підпис запиту. Підпис підтверджує, що запит надійшов саме від вас і ніхто його не змінив під час передачі.

API-ключі

2328.io використовує два ключі, які мають однаковий алгоритм підпису, але охоплюють різні endpoints:

Ключ	Використовується для
API key	Платежі, статичні гаманці, баланс, курси обміну, а також перевірка webhooks для платежів та статичних гаманців
Payout API key	Усі endpoints `/v1/payout/*` та перевірка webhooks для виплат

Обидва ключі знаходяться у налаштуваннях вашого проєкту на 2328.io. У наведених нижче прикладах "API key" — узагальнена назва; підставте відповідний ключ для endpoint, який викликаєте.

Ніколи не змішуйте два ключі: підписання запиту виплати звичайним API key (або платіжного запиту ключем виплат) повертає помилку підпису.

Обов'язкові заголовки

Заголовок	Тип	Обов'язковий	Опис
`Content-Type`	string	так	Завжди `application/json`
`project`	string	так	Ваш project UUID
`sign`	string	так	Підпис запиту HMAC-SHA256, обчислений за допомогою вашого API key
`User-Agent`	string	так	Ідентифікує ваш застосунок (наприклад, `MyShop/1.4 (+https://myshop.example)`). Запити без `User-Agent` можуть бути заблоковані.

Як працює підпис

Уявіть собі підпис як відбиток тіла запиту. Він формується так:

Серіалізуйте тіло у JSON (компактний — без зайвих пробілів).
Закодуйте цей JSON у base64. Цей крок нормалізує вхідні дані між мовами — щойно це стане звичайним ASCII, кожна мова формуватиме однакові байти для HMAC.
Обчисліть HMAC-SHA256 від base64-рядка, використовуючи ваш API key, потім перетворіть результат на нижній регістр у hex-форматі.

Для GET та інших запитів без тіла підписуйте порожній рядок замість JSON.

Підпис порожнього рядка є константою для конкретного API key. Ви можете кешувати його, якщо робите багато GET-викликів.

Реалізації

PHP

<?php
function apiSign(array $data, string $apiKey): string {
    $json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $base64 = base64_encode($json);
    return hash_hmac('sha256', $base64, $apiKey);
}

JavaScript

import crypto from "crypto";

export function apiSign(data, apiKey) {
  const json = JSON.stringify(data);
  const base64 = Buffer.from(json).toString("base64");
  return crypto.createHmac("sha256", apiKey).update(base64).digest("hex");
}

TypeScript

import { createHmac } from "crypto";

export function apiSign(data: object, apiKey: string): string {
  const json = JSON.stringify(data);
  const base64 = Buffer.from(json).toString("base64");
  return createHmac("sha256", apiKey).update(base64).digest("hex");
}

Python

import json
import hmac
import hashlib
import base64

def api_sign(data: dict, api_key: str) -> str:
    # ensure_ascii=False keeps non-ASCII characters (Cyrillic, Chinese, …)
    # as-is. Without it, Python escapes them to \uXXXX and the signature
    # diverges from PHP / Node / Go.
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    b64 = base64.b64encode(body.encode("utf-8")).decode()
    return hmac.new(api_key.encode(), b64.encode(), hashlib.sha256).hexdigest()

package sign

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "encoding/json"
)

func ApiSign(data any, apiKey string) (string, error) {
    // json.Encoder with SetEscapeHTML(false) — without it, Go escapes <, >, &
    // to \u003c etc., which breaks compatibility with PHP / Node / Python.
    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    enc.SetEscapeHTML(false)
    if err := enc.Encode(data); err != nil {
        return "", err
    }
    // Encoder appends a trailing newline — drop it.
    body := bytes.TrimRight(buf.Bytes(), "\n")

    b64 := base64.StdEncoding.EncodeToString(body)
    h := hmac.New(sha256.New, []byte(apiKey))
    h.Write([]byte(b64))
    return hex.EncodeToString(h.Sum(nil)), nil
}

Запити без тіла (GET)

Для запитів із порожнім тілом (наприклад, GET /v1/payout/status/{uuid}) підписуйте порожній рядок:

Shell

SIGN=$(printf '' | openssl dgst -sha256 -hmac "$API_KEY" -hex | awk '{print $NF}')

package sign

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
)

func EmptyBodySign(apiKey string) string {
    b64 := base64.StdEncoding.EncodeToString([]byte(""))
    h := hmac.New(sha256.New, []byte(apiKey))
    h.Write([]byte(b64))
    return hex.EncodeToString(h.Sum(nil))
}

Повний приклад запиту

Shell

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"amount":"100.00","currency":"USD","order_id":"ORDER-123"}'

PHP

<?php
function apiSign(string $body, string $apiKey): string {
    return hash_hmac('sha256', base64_encode($body), $apiKey);
}

$project = 'YOUR_PROJECT_UUID';
$apiKey  = 'YOUR_API_KEY';

$data = [
    'amount'   => '100.00',
    'currency' => 'USD',
    'order_id' => 'ORDER-123',
];

$body = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sign = apiSign($body, $apiKey);

$ch = curl_init('https://api.2328.io/api/v1/payment');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'User-Agent: MyShop/1.0 (+https://myshop.example)',
        "project: $project",
        "sign: $sign",
    ],
]);

$response = json_decode(curl_exec($ch), true);

JavaScript

import { createHmac } from "crypto";

function apiSign(body, apiKey) {
  const base64 = Buffer.from(body, "utf8").toString("base64");
  return createHmac("sha256", apiKey).update(base64).digest("hex");
}

const data = {
  amount: "100.00",
  currency: "USD",
  order_id: "ORDER-123",
};

const body = JSON.stringify(data);
const sign = apiSign(body, process.env.API_KEY);

const res = await fetch("https://api.2328.io/api/v1/payment", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "User-Agent": "MyShop/1.0 (+https://myshop.example)",
    project: process.env.PROJECT_UUID,
    sign,
  },
  body,
});

const json = await res.json();

TypeScript

import { createHmac } from "crypto";

function apiSign(body: string, apiKey: string): string {
  const base64 = Buffer.from(body, "utf8").toString("base64");
  return createHmac("sha256", apiKey).update(base64).digest("hex");
}

type CreatePaymentBody = {
  amount: string;
  currency: string;
  order_id: string;
};

type CreatePaymentResponse = { state: number; result: unknown };

const data: CreatePaymentBody = {
  amount: "100.00",
  currency: "USD",
  order_id: "ORDER-123",
};

const body = JSON.stringify(data);
const sign = apiSign(body, process.env.API_KEY!);

const res = await fetch("https://api.2328.io/api/v1/payment", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "User-Agent": "MyShop/1.0 (+https://myshop.example)",
    project: process.env.PROJECT_UUID!,
    sign,
  },
  body,
});

const json = (await res.json()) as CreatePaymentResponse;

Python

import json
import hmac
import hashlib
import base64
import httpx

def api_sign(body: str, api_key: str) -> str:
    b64 = base64.b64encode(body.encode("utf-8")).decode()
    return hmac.new(api_key.encode(), b64.encode(), hashlib.sha256).hexdigest()

data = {
    "amount": "100.00",
    "currency": "USD",
    "order_id": "ORDER-123",
}

body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
sign = api_sign(body, API_KEY)

r = httpx.post(
    "https://api.2328.io/api/v1/payment",
    headers={
        "Content-Type": "application/json",
        "User-Agent": "MyShop/1.0 (+https://myshop.example)",
        "project": PROJECT_UUID,
        "sign": sign,
    },
    content=body.encode("utf-8"),
)
response = r.json()

package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "encoding/json"
    "net/http"
)

func ApiSign(body []byte, apiKey string) string {
    b64 := base64.StdEncoding.EncodeToString(body)
    h := hmac.New(sha256.New, []byte(apiKey))
    h.Write([]byte(b64))
    return hex.EncodeToString(h.Sum(nil))
}

func marshalCanonical(v any) ([]byte, error) {
    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    enc.SetEscapeHTML(false)
    if err := enc.Encode(v); err != nil {
        return nil, err
    }
    return bytes.TrimRight(buf.Bytes(), "\n"), nil
}

func main() {
    data := struct {
        Amount   string `json:"amount"`
        Currency string `json:"currency"`
        OrderID  string `json:"order_id"`
    }{
        Amount:   "100.00",
        Currency: "USD",
        OrderID:  "ORDER-123",
    }

    body, err := marshalCanonical(data)
    if err != nil {
        panic(err)
    }
    sign := ApiSign(body, apiKey)

    req, _ := http.NewRequest("POST",
        "https://api.2328.io/api/v1/payment",
        bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("User-Agent", "MyShop/1.0 (+https://myshop.example)")
    req.Header.Set("project", projectUUID)
    req.Header.Set("sign", sign)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
}

Ніколи не розкривайте свій API key у клієнтському коді. Підписуйте запити на бекенді. Витік API key надає будь-кому повний доступ до вашого мерчант-акаунту.

Перевірка підписів webhooks

Коли 2328.io надсилає вам webhook, той самий алгоритм виконується у зворотному напрямку:

Витягніть поле sign із payload.
Закодуйте інші поля у JSON (компактний, без пробілів).
Закодуйте отриманий рядок у base64.
Обчисліть HMAC-SHA256 за допомогою відповідного ключа.
Порівняйте його з отриманим sign, використовуючи порівняння за константний час (hash_equals, crypto.timingSafeEqual, hmac.compare_digest, subtle.ConstantTimeCompare, OpenSSL.fixed_length_secure_compare).

Ключ підпису залежить від джерела webhook:

Webhook	Ключ для перевірки
Webhooks платежів та статичних гаманців (`/v1/payment`, `/v1/static-wallet`)	API key
Webhooks виплат (`/v1/payout`)	Payout API key

Типові помилки перевірки. Ваш JSON-енкодер має видавати точно ті самі байти, що й відправник — інакше Base64 буде відрізнятися і підпис не співпаде.

Go: використовуйте json.NewEncoder із SetEscapeHTML(false). Стандартний json.Marshal екранує <, >, & як < і ламає підпис.
Python: передавайте ensure_ascii=False у json.dumps. Без цього не-ASCII символи (кирилиця, китайська тощо) екрануються в \uXXXX.
Компактний JSON: без пробілів між полями (separators=(",", ":") у Python).
Порядок полів (Go): звичайний map[string]any рандомізує ключі при перекодуванні. Використовуйте json.RawMessage, упорядковану структуру або видаляйте sign зі сирих байтів.

Якщо перевірка все одно не проходить, запустіть apiSign на payload самостійно — він має видавати той самий hex-рядок, що й отриманий sign.

Валідний підпис не захищає від повторів. Він лише доводить, що webhook прийшов від 2328.io — і не заважає зловмиснику пізніше повторно надіслати перехоплений webhook. Завжди перевіряйте ідемпотентність за uuid (або txid для статичних гаманців) перед зарахуванням коштів. Відхиляйте з HTTP 401, якщо підпис відсутній або неправильний.

Повні приклади коду на сторінці Webhook-сповіщення. Обробка повторних спроб і правила ідемпотентності — у розділі Найкращі практики.