API masowych wypłat kryptowalutowych: Automatyzacja wypłat w sposób niepowierniczy

Co właściwie robi API masowych wypłat kryptowalut

Pojedyncze wywołanie POST /v1/payout rezerwuje środki na całą partię, weryfikuje każdego odbiorcę i umieszcza go w kolejce do podpisania. Operator następnie podpisuje i nadaje z offline'owych kluczy. To jest uczciwy kształt API masowych wypłat kryptowalut zbudowanego na bramce non-custodial: API automatyzuje przesyłanie, weryfikację, status i webhooki — nie automatyzuje podpisu, ponieważ klucze prywatne nigdy nie znajdują się na serwerze. Nie ma gorącego portfela do opróżnienia i żadnego cichego automatycznego wysyłania. Jeśli ta wymiana wydaje się akceptowalna, API przekształca ręczną wypłatę lub uruchomienie afiliacyjne w dwie lub trzy linie kodu.

To jest przewodnik dla deweloperów. Kopiuje dokładny kontrakt z dokumentacji API, abyś mógł go wdrożyć już dziś: punkty końcowe, podpis HMAC, Idempotency-Key, ścisła walidacja 422, webhook payout.sent oraz jak anulowanie zwalnia zablokowany bilans. Jeśli chcesz najpierw przegląd produktu, przeczytaj stronę masowych wypłat.

Dlaczego jest półautomatyczne i dlaczego to jest wygrana w zakresie bezpieczeństwa

Nic nie jest nadawane przez samą aplikację internetową. Adresy odbiorców pochodzą z materiału klucza publicznego; klucze prywatne, które autoryzują wydanie, pozostają na twoim sprzęcie, offline. Dlatego przepływ jest celowo dwuetapowy. Kiedy przesyłasz partię — z szafy lub przez API — Payora rezerwuje całkowitą kwotę plus opłatę za ruch na twoim wewnętrznym saldzie natychmiast, więc partia nigdy nie może być przekroczona. Następnie człowiek (ty lub twoja rotacja operacyjna) podpisuje kolejkę offline i nadaje je.

Naruszenie serwera nie może przenieść ani jednej monety, ponieważ skrzynka, która odbiera wywołanie API, nie ma nic do podpisania. Koszt to jeden krok podpisania na partię. Dla wypłat, uruchomień afiliacyjnych i rozliczeń z dostawcami to uczciwa cena, a to ta sama architektura opisana w płaceniu setkom portfeli bez gorącego portfela. Nigdy nie modeluj tego jako "wywołanie API, monety natychmiast znikają" — to byłby inny, bardziej ryzykowny produkt.

Uwierzytelnianie i podpisywanie żądań

API masowych wypłat kryptowalut używa tego samego uwierzytelniania co reszta Payora. Każde żądanie zawiera trzy nagłówki: X-Payora-Key, X-Payora-Timestamp (sekundy Unix, ±120s przesunięcia) oraz X-Payora-Signature. Podpis to HMAC-SHA256 nad znacznikiem czasu, dosłowną kropką i dokładnym surowym ciałem żądania:

X-Payora-Signature = hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body))

Podpisz bajty, które faktycznie wysyłasz, przed jakąkolwiek reserializacją. Jeśli twój klient HTTP ponownie koduje JSON, najpierw uchwyć surowe ciało i zhashuj to. To jest identyczny schemat używany do weryfikacji przychodzących webhooków, omówiony w weryfikacji podpisu webhooka HMAC-SHA256.

POST /v1/payout: przesyłanie partii

Wyślij walutę, do 500 pozycji i opcjonalną notatkę. Każda pozycja to adres, kwota jako ciąg i opcjonalny tag — tag docelowy XRP lub memo XLM, gdy aktywa tego wymagają.

curl -X POST https://api.payora.money/v1/payout \
  -H "X-Payora-Key: pk_live_9f3c8a12" \
  -H "X-Payora-Timestamp: 1753280400" \
  -H "X-Payora-Signature: 7b1e0c4d9a55f2..." \
  -H "Idempotency-Key: payroll-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "items": [
      {"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "250.00"},
      {"address": "TXk9mP2v7wQ3nR5tYb1cD8eF4gH6jK0lMn", "amount": "1800.00", "tag": ""}
    ],
    "note": "Wykonawcy lipca"
  }'

W przypadku sukcesu otrzymujesz 201 z partią, którą możesz śledzić. Całkowita kwota to suma kwot, opłata to opłata za ruch twojego planu (1,5% w planie Free) plus opłata sieciowa monety’, a obie są już zablokowane na twoim saldzie:

{
  "batch_id": "po_7Qd2K8xM4b",
  "status": "oczekujące",
  "currency": "USDT",
  "item_count": 2,
  "total": "2050.00",
  "fee": "20.50",
  "items": [
    {"index": 0, "address": "TR7NHqjeKQ...", "amount": "250.00", "status": "oczekujące"},
    {"index": 1, "address": "TXk9mP2v7w...", "amount": "1800.00", "status": "oczekujące"}
  ]
}

Akceptowanie płatności nadal wynosi 0%; opłata za ruch dotyczy tylko, gdy pieniądze opuszczają. Opłaty sieciowe są oddzielne i płacone na łańcuchu w momencie nadawania.

Ścisła walidacja: brak cichych odrzuconych odbiorców

Walidacja jest celowo wszystko albo nic. Jeśli jakikolwiek adres jest źle sformułowany dla wybranej sieci, lub jakakolwiek kwota ma więcej miejsc po przecinku niż obsługuje moneta, cała partia jest odrzucana z 422 i wskazanymi indeksami. Nic nie jest umieszczane w kolejce, nic nie jest zatrzymywane.

HTTP/1.1 422 Nieprzetwarzalny podmiot
{
  "error": "validation_failed",
  "invalid_items": [3, 17],
  "message": "nieprawidłowy adres na indeksie 3; kwota przekracza precyzję monety na indeksie 17"
}

To jest zachowanie, którego chcesz dla wypłat. Bramki, które cicho skróciłyby 1800.123456789 lub pominęłyby jeden zły wiersz, zapłaciłyby za mało lub pominęłyby osobę, a nie zauważyłbyś tego, dopóki ktoś nie zgłosiłby skargi. Napraw oznaczone indeksy i ponownie prześlij całą partię.

Idempotencja: ponowne próby nigdy nie podwajają płatności

Sieci mają czas na wygaśnięcie. Żądanie wypłaty, które nie powiedzie się w połowie, jest niebezpieczne do ponownego wysłania bezmyślnie, więc wyślij nagłówek Idempotency-Key — dowolny stabilny, unikalny ciąg dla tej logicznej partii (okres wypłat, grupa faktur). Jeśli żądanie z tym samym kluczem przyjdzie ponownie, Payora zwraca oryginalną partię zamiast tworzyć drugą. Użyj klucza do każdej ponownej próby tej samej partii; użyj nowego klucza dla naprawdę nowej partii.

• Ten sam klucz, ta sama partia — bezpieczne do ponownego wysłania po czasie oczekiwania; otrzymujesz pierwszy wynik z powrotem.
• Nowy klucz — nowa partia, nowa blokada na twoim saldzie.
• Zapisz zwrócone batch_id tak szybko, jak to możliwe, abyś mógł uzgodnić, nawet jeśli odpowiedź została utracona.

Uzgodnij z GET /v1/payout/{id}

Po podpisaniu przez operatora, sprawdź GET /v1/payout/{id} w celu uzyskania aktualnego statusu i per-pozycji tx_hash, gdy każda transakcja jest nadawana. GET /v1/payout wyświetla ostatnie partie dla pulpitów i audytów. Zapisz batch_id i każdy indeks pozycji w swoich własnych zapisach, aby każdy odbiorca odpowiadał na hasz na łańcuchu, który możesz im pokazać.

Potrzebujesz cofnąć jedną przed podpisaniem? POST /v1/payout/{id}/cancel anuluje wciąż oczekującą partię i zwalnia zablokowany bilans w całości. Gdy przedmioty są nadawane, są na łańcuchu i ostateczne, jak każda transakcja kryptograficzna — anulowanie działa tylko, gdy partia jest w toku.

Webhook payout.sent

Zamiast sprawdzać w nieskończoność, subskrybuj payout.sent. Gdy operator nada wszystkie przedmioty w partii, Payora uruchamia podpisany webhook, używając tego samego podpisu HMAC, co invoice.paid. Zweryfikuj to w ten sam sposób — przelicz podpis nad znacznikiem czasu, kropką, surowym ciałem i porównaj w stałym czasie:

$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $webhook_secret);
if (!hash_equals($expected, $signature_header)) { http_response_code(400); exit; }
// payload.event == "payout.sent", payload.batch_id, payload.items[].tx_hash

Dopiero po tym, jak ten test przejdzie, powinieneś oznaczyć uruchomienie wypłaty jako zakończone, wysłać potwierdzenia e-mailem lub zaktualizować księgi. Niezweryfikowany webhook to tylko nieufne żądanie HTTP.

Minimalna lista kontrolna integracji

1. Utwórz konto i wygeneruj klucze API w rejestrze; zasil wewnętrzne saldo w walucie, którą będziesz wypłacać.
2. Zbuduj surowe ciało JSON, podpisz je (znacznik czasu + "." + ciało) za pomocą HMAC-SHA256, dołącz trzy nagłówki plus Idempotency-Key.
3. POST /v1/payout; przy 201 zachowaj batch_id, przy 422 napraw oznaczone indeksy i wyślij ponownie.
4. Niech twój operator podpisze i nada z kolejki offline.
5. Zweryfikuj webhook payout.sent, lub sprawdź GET /v1/payout/{id}, i zapisz każdy tx_hash.

To jest cały cykl. API usuwa nużącą, podatną na błędy część — budowanie, weryfikację i śledzenie 500-liniowej partii — podczas gdy offline'owy podpis trzyma to, co naprawdę ma znaczenie, twoje klucze, poza zasięgiem serwera.

Zacznij budować

Przeczytaj sekcję API masowych wypłat w dokumentacji, zdobądź klucze w rejestrze i zobacz funkcję od początku do końca na stronie masowych wypłat. Możesz zautomatyzować partię już dziś i nadal podpisywać tam, gdzie to należy — offline.