DOKUMENTACJA DLA PROGRAMISTÓW
Dokumentacja API
Zintegruj faktury, stronę płatności i powiadomienia o płatnościach.
Wyniki wyszukiwania
Brak wyników. Spróbuj nazwy punktu końcowego, pola lub przewodnika.
Szybki start
Utwórz pierwszą fakturę.
- Przygotuj sklep
Włącz jego metody płatności, skonfiguruj dostawców i wykonaj kopie zapasowe portfeli projektu.
- Utwórz dane dostępu API
W panelu w Ustawienia → Dostęp API wybierz odczyt/zapis i przypisz projekt.
- Wyślij żądanie
Użyj swojego hosta API i skopiuj identyfikatory projektu i sklepu. Wysyłaj kwoty dziesiętne jako ciągi znaków.
- Otwórz stronę płatności
Przekieruj na
links.checkoutz odpowiedzi. Zweryfikuj rozliczenie przed realizacją zamówienia.
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: order-1042-attempt-1' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Przykłady używają symboli zastępczych i nie wysyłają żądań z tej strony. Zobacz wszystkie pola faktury i format odpowiedzi →
Identyfikatory projektu i sklepu
Gdzie znaleźć YOUR_PROJECT_ID i YOUR_STORE_ID.
Używaj UUID z panelu, a nie nazw projektów lub sklepów ani ich czytelnych identyfikatorów.
| Symbol zastępczy | Gdzie go znaleźć | Zastosowanie |
|---|---|---|
| YOUR_PROJECT_ID | Projekt → Ustawienia → Identyfikatory API → Identyfikator API projektu → Kopiuj. Widoczny też na karcie Podstawowe sklepu. | Żądania na poziomie projektu i sklepu. |
| YOUR_STORE_ID | Projekt → Sklepy → wybierz sklep → Podstawowe → Identyfikatory API → Identyfikator API sklepu → Kopiuj. | Tworzenie faktur i żądania metod płatności sklepu. |
- Tworzenie faktury wymaga obu identyfikatorów, nawet dla domyślnego sklepu. Sklep musi należeć do tego projektu, a dane dostępu API muszą zapewniać dostęp do projektu.
- Tworzenie, lista, szczegóły i strona płatności faktury zwracają invoice_id: ten sam UUID, który jest wysyłany w IPN/webhookach. Używaj go w ścieżkach faktur zamiast wewnętrznego id lub order_id. Od wersji 4.0.0 oprogramowania sprzedawcy stare pole odpowiedzi public_id jest usunięte; zaktualizuj integracje przed aktualizacją oprogramowania.
- API REST nie udostępnia tras listowania projektów/sklepów. Skopiuj identyfikatory w panelu lub użyj narzędzi MCP list_projects i list_stores z ograniczonym zakresem w oprogramowaniu sprzedawcy 5.0.0+.
- Sklep → Podstawowe → Domeny sklepu wybiera aktywne nazwy hostów merchant, pay i API. Zwracane linki płatnicze i nowe linki wywołań zwrotnych preferują ten sklep, następnie sklep domyślny, a potem ustawienia systemowe. Wycofane lub nieaktywowane nazwy nigdy nie są wybierane. Skonfiguruj SDK z preferowaną nazwą hosta API; zmiana preferencji nie przekierowuje innych aktywnych aliasów.
Uwierzytelnianie i zakres
Przechowuj dane dostępu na serwerze i przyznawaj tylko potrzebne uprawnienia.
| Domyślny host | Cel |
|---|---|
| merchant.example.com | Panel sprzedawcy i Ustawienia |
| pay.example.com | Strona płatności klienta |
| api.example.com | Żądania API sprzedawcy |
Zastąp example.com swoją domeną. Istniejące instalacje zachowują skonfigurowane nazwy; zarządzaj aliasami w Ustawienia → System.
Authorization: Bearer YOUR_MERCHANT_API_TOKEN| Ustawienie | Jak to działa |
|---|---|
| Poziom dostępu | Dane dostępu tylko do odczytu pozwalają listować i pobierać. Dane z prawem odczytu i zapisu pozwalają też tworzyć faktury i aktualizować udokumentowane polityki aktywów. |
| Projekty | Przypisz projekty dostępne dla danych dostępu. Identyfikatory sklepów i faktur muszą należeć do przypisanego projektu. |
| Ograniczenia IP | Opcjonalnie zezwól na dokładne publiczne adresy wyjściowe IPv4 lub IPv6 w Ustawienia → Dostęp API. |
| Przechowywanie danych dostępu | Przechowuj tokeny w konfiguracji backendu. Nigdy nie umieszczaj danych dostępu bearer w przeglądarce ani w linku płatniczym. |
Publiczne trasy płatności używają publicznego identyfikatora faktury i ujawniają tylko dane bezpieczne dla strony płatności. Sesje panelu i funkcje administracyjne są oddzielne od danych dostępu API sprzedawcy.
Aktywa i portfele
Wybieraj metody płatności niezależnie dla każdego sklepu.
- Odczytaj aktywa płatnicze projektu i ich gotowość.
- Włącz natywny blockchain oraz skonfiguruj jego portfel i dostawców.
- Przeglądaj kandydatów na tokeny i zweryfikuj kontrakt lub mint przed włączeniem tokena.
- Wybierz uporządkowane metody płatnościsklepu. Nowe faktury używają jego gotowych do działania opcji.
Tokeny współdzielą portfel swojego natywnego blockchaina. Salda portfeli zwracają dokładne kwoty w jednostkach atomowych i orientacyjne wartości fiducjarne. Używaj zwróconych pól gotowości, aby ustalić, które metody mogą przyjmować płatności.
Zweryfikowane tokeny ERC-20 korzystają z obsługiwanych sieci EVM; zweryfikowane tokeny SPL korzystają z Solana. Natywne metody płatności są dostępne w 30 zintegrowanych sieciach. Monero korzysta z przypisanego do projektu połączenia z zewnętrznym portfelem tylko do podglądu.
API odbioru oraz zakres obsługi monet natywnych i tokenów
| Kanał płatności | Obsługa | Dowody | Wymagania |
|---|---|---|---|
| Natywne kanały płatności | obsługiwane | Skanowanie transakcji | BTC, SOL, ETH (Ethereum/Base/Arbitrum/OP), BNB, HYPE, AVAX i POL; wyjścia Bitcoin, kanoniczne transakcje/potwierdzenia EVM i przeanalizowane przelewy Solana dostarczają dowodów dla faktury. |
| Kanały tokenów ERC-20 | obsługiwane | Skanowanie transakcji | Ethereum, Base, BNB Chain, HyperEVM, Avalanche, Polygon, Arbitrum i Optimism wymagają weryfikacji on-chain; indeksowane logi Transfer pozwalają przypisać płatność. |
| Kanały tokenów SPL | obsługiwane | Skanowanie transakcji | Kandydaci Solana wymagają weryfikacji sieci głównej i mint; dokładne zmiany sald tokenów w przeanalizowanych transakcjach pozwalają przypisać płatność. |
| Dodatkowe natywne kanały UTXO | obsługiwane | Skanowanie transakcji | BCH/LTC/DOGE używają Esplora; BCH/DOGE akceptują też Bitcore, LTC/DOGE/DASH akceptują BlockCypher, Dash akceptuje Insight, a przejrzyste ZEC akceptuje zcash-explorer. Wszystkie akceptują też kompletne zachowane bloki node-rpc zgodne z Core. Tryb surowy wymaga 1–48 potwierdzeń, a nie wykrycia w mempoolu. Osłonięte transakcje Zcash nie są obsługiwane. |
| Indeksowane natywne kanały kontowe | obsługiwane | Skanowanie transakcji | TRON używa tron-indexer lub node-rpc dla utrwalonych bloków; XRP używa xrpl-jsonrpc; Stellar używa stellar-horizon lub zachowanych ksiąg Stellar node-rpc; Cosmos Hub używa cometbft-jsonrpc; Algorand używa algorand-indexer lub algod node-rpc; Hedera wymaga hedera-mirror, a nie przekaźnika EVM. |
| Natywne kanały płatności oparte na księgach | obsługiwane | Skanowanie transakcji | Aptos używa aptos-rest; Sui używa sui-graphql; NEAR używa near-jsonrpc; Kaspa używa kaspa-rest. Polkadot Asset Hub akceptuje substrate-rest lub sfinalizowane node-rpc z obsługą metadanych; Tezos akceptuje tezos-tzkt lub pełne operacje Octez node-rpc. Tylko wpływy natywne; starsze faktury wymagają przechowywania archiwum. |
| Natywne kanały Cardano i TON | obsługiwane | Skanowanie transakcji | Cardano wymaga cardano-koios, a TON wymaga toncenter-v3. Tagi XRP, identyfikatory memo Stellar i komentarze faktur TON są zwracane jako destination_tag i muszą zostać wysłane dokładnie w tej postaci. |
| Integralność rozliczenia | obsługiwane | Niezależna weryfikacja | Domyślnie końcowe rozliczenie wymaga zgodności dwóch niezależnych dostawców co do dokładnej transakcji/zdarzenia, kwoty, kanonicznego bloku lub slotu i ostateczności. Surowe i współdzielone okna EVM weryfikują też kompletność pokrycia. Administrator może jawnie ustawić jeden zaufany podmiot dla danego blockchaina; usuwa to niezależną kontrolę krzyżową, ale nie kontrole tożsamości, kompletności ani ostateczności. |
| Natywny kanał Monero | obsługiwane | RPC portfela tylko do podglądu przypisanego do projektu | Jeden dedykowany zewnętrzny wallet-RPC tylko do obserwacji, za bramą HTTPS z listą dozwolonych metod, tworzy podadresy konta 0. Skonfigurowany próg demonów sieci głównej (domyślnie 2 niezależne źródła, opcjonalnie 1) dostarcza dowodów rozliczenia. Natywne --restricted-rpc jest niezgodne z create_address; operator wyraźnie poświadcza wykonanie kopii zapasowej portfela i brak klucza wydawania, a żaden materiał kluczowy nie jest wysyłany do Wholly Crypto. |
Salda giełdowe i wybór celu sweep dla każdego aktywa - portfel lub giełda - są dostępne w panelu, a nie przez publiczne API v1. Zobacz konfigurację giełdy.
Cykl życia faktury
Dowody płatności, rozliczenie i realizacja zamówień.
| Status | Znaczenie |
|---|---|
| new | Oczekiwanie na płatność |
| processing | Zaobserwowano płatność; oczekiwanie na akceptowaną kwotę lub ostateczność |
| settled | Zaakceptowano zgodnie z polityką rozliczenia faktury lub ręcznie |
| expired | Termin upłynął; monitorowanie spóźnionych płatności może trwać dalej |
| invalid | Płatność nie może zostać zaakceptowana automatycznie |
| cancelled | Anulowano; tylko jawne uzgodnienie może otworzyć ją ponownie |
amount_status zapisuje none, partial, paid lub overpaid. timing_status rozróżnia płatności terminowe i spóźnione. Reguły sklepu określają wymagane potwierdzenia i akceptowaną tolerancję niedopłaty.
Użyj pola faktury invoice_id z trasą szczegółów faktury. Samo przekierowanie ze strony płatności nie dowodzi rozliczenia. Sprawdzaj wyjątki przez uzgadnianie płatności.
Bezpieczne ponawianie
Tworzenie faktury wymaga Idempotency-Key. Po przekroczeniu czasu oczekiwania ponów próbę z tymi samymi danymi dostępu, kluczem i dokładnie tą samą treścią żądania. Używaj nowego klucza wyłącznie dla nowej faktury.
Skanowanie płatności EVM
Współdzielone wykrywanie natywnych bloków i ERC-20 grupuje najnowsze faktury oddzielnie od nadrabiania starszych danych. Każda faktura zachowuje trwały kursor historii. Zapytania o tokeny obejmują najwyżej 100 bloków na żądanie i zmniejszają zakres przy surowszych limitach dostawcy. Domyślnie dwóch niezależnych dostawców weryfikuje każde okno. Ustawienia → Połączenia z blockchainami → Szczegóły pozwala wybrać dla blockchaina jedno zaufane źródło, bez niezależnej kontroli krzyżowej; kontrole kanonicznej transakcji, kwoty i potwierdzeń pozostają. Szczegóły połączenia rozróżniają opóźnienia skanera, ograniczenia historii i przerwy po wyczerpaniu limitów od podstawowego stanu węzła. Wydajność publicznego RPC nie jest gwarantowana.
IPN i webhooki
Odbieraj i weryfikuj zdarzenia płatnicze.
IPN otrzymuje każde wygenerowane zdarzenie faktury pod jej obowiązującym adresem ipn_url. Webhooki otrzymują tylko zdarzenia wybrane dla każdego włączonego punktu końcowego sklepu. Oba wysyłają POST z tym samym stanem JSON; są niezależne, więc włączenie obu może powiadomić aplikację dwukrotnie.
Ustaw ipn_url podczas tworzenia faktury lub odziedzicz wartość domyślną sklepu. IPN używa sekretu Sklep → IPN ; każdy punkt końcowy Sklep → Webhooki ma własny sekret. Żaden z nich nie jest Twoim kluczem API.
Kiedy realizować zamówienie?
W obsłudze opartej na zdarzeniach używaj event_type = invoice.settled razem ze status = settled, aby uruchomić kontrolę zamówienia. Zweryfikuj bieżący stan faktury i realizuj każde zamówienie tylko raz.
status to stan faktury w chwili utworzenia zdarzenia. event_type mówi, co się wydarzyło. payment.received może zawierać processing lub settled; nie oznacza drugiej płatności i nie jest niezależnym sygnałem do realizacji zamówienia.
Jakie zdarzenia i statusy są wysyłane?
| Zdarzenie w ustawieniach/historii | Status w treści | Znaczenie |
|---|---|---|
| invoice.created | new | Faktura została utworzona i oczekuje na płatność. Używane też, gdy kontrolowane ponowne otwarcie przywraca fakturę do new. |
| payment.received | Resulting invoice status | Zarejestrowano płatność lub wzrosła otrzymana kwota. Zwykle processing lub settled; samo to zdarzenie nie jest dowodem rozliczenia. |
| invoice.processing | processing | Wykryto płatność, ale akceptowana kwota lub wymagana ostateczność nie zostały jeszcze osiągnięte. Obejmuje płatności częściowe. |
| invoice.settled | settled | Spełniono politykę rozliczenia lub zaakceptowano ręcznie. Przed realizacją sprawdź resolution i zamówienie. |
| invoice.expired | expired | Termin płatności upłynął. Spóźniona płatność może nadal zmienić status, dopóki trwa monitorowanie. |
| invoice.invalid | invalid | Nie można zaakceptować automatycznie, utracono dowody płatności lub sprzedawca ją odrzucił. Sprawdź fakturę. |
| invoice.cancelled | cancelled | Faktura anulowana. Nie realizuj zamówienia; anulowanie nie zwraca płatności on-chain. |
Dlaczego Ethereum i Solana mogą wysyłać różne sekwencje zdarzeń
Potwierdzenia docierają później (przykład Ethereum)
| Sekwencja | event_type | status |
|---|---|---|
| 1 | invoice.created | new |
| 2 | payment.received | processing |
| 2 | invoice.processing | processing |
| 3 | invoice.settled | settled |
Płatność jest już ostateczna przy wykryciu (przykład Solana)
| Sekwencja | event_type | status |
|---|---|---|
| 1 | invoice.created | new |
| 2 | payment.received | settled |
| 2 | invoice.settled | settled |
To kolejność tworzenia zdarzeń, a nie gwarantowana kolejność dostarczenia. Oba przebiegi mogą wystąpić w innych blockchainach zależnie od czasu wykrycia i polityki rozliczenia. Nie wymagaj zdarzenia processing przed settled.
Realizuj raz: przykład odbiornika i ochrona przed duplikatami
| Podejście | Sposób obsługi |
|---|---|
| Odbiornik oparty na zdarzeniach | Przechowuj oddzielne zdarzenia według podpisanego event_id, a następnie wybierz invoice.settled ze status = settled. Nie odrzucaj tego zdarzenia, jeśli wcześniej dotarło payment.received z tą samą sequence. |
| Skrzynka stanów zamówień SDK | Dostarczone przykłady odbiorników PHP, Python i Node scalają project + invoice_id + sequence. Przetwarzaj zapisany stan niezależnie od event_type, pobierz bieżącą fakturę i zrealizuj zamówienie raz, jeśli ma stan settled. Po tym scaleniu nie dodawaj filtra tylko dla invoice.settled. |
Ponowienie zachowuje event_id i pierwotną treść. Różne zdarzenia mogą mieć wspólną sequence, ale różne wartości event_id. Przy obsłudze zdarzeniowej usuwaj duplikaty dostarczeń według podpisanego event_id; niezależnie zabezpieczaj realizację według skonfigurowanej instalacji/projektu + invoice_id i zamówienia. Późniejsze ponowne rozliczenie nie może zaliczyć wpłaty na zamówienie dwukrotnie.
HTTP receiver:
Verify raw-body signature, timestamp and configured project/store scope.
Save to a durable inbox; deduplicate the signed event_id.
Return HTTP 2xx only after persistence succeeds.
Event-based background worker:
Other events go to status/reconciliation handling, not fulfilment.
Continue here only for event_type = invoice.settled and status = settled.
Fetch the current invoice from your configured API origin.
Check settled status, project/store, order, amount, currency and review policy.
In one database transaction:
Lock the order and check the scoped invoice has not been fulfilled.
Credit/complete once and save the fulfilment record.
Queue any external fulfilment with the same business idempotency key.
SDK order-state worker:
Use the same current-invoice checks and fulfil-once transaction.
Do not filter event_type after collapsing events by invoice revision.Pseudokod, a nie gotowy odbiornik do wklejenia.
Wszystkie stany faktur i wyjątki płatności
| Pole | Wartości | Znaczenie |
|---|---|---|
| status | new, processing, settled, expired, invalid, cancelled | Stan faktury przy utworzeniu zdarzenia; niekoniecznie jej bieżący stan przy dostarczeniu. |
| amount_status | none, partial, paid, overpaid | Otrzymana kwota, z uwzględnieniem akceptowanej tolerancji. paid nie oznacza ostateczności potwierdzeń. |
| timing_status | on_time, late | Czy płatność zmieściła się w terminie faktury. |
| resolution | automatic, manually_settled, manually_invalidated | Czy wynik określiły zwykłe reguły, czy ręczna akceptacja/odrzucenie. |
| requires_review | false, true | Wskazówka dotycząca wyjątku, a nie kolejny status faktury ani automatyczne zezwolenie na realizację/zwrot. |
| Sytuacja | Obsługa |
|---|---|
| Niedopłata / tolerancja | Zgodnie z regułami automatycznymi partial nie oznacza rozliczenia. paid może obejmować zaakceptowaną niedopłatę, ale ostateczność nadal jest wymagana. Używaj statusu faktury, nie samego porównania kwot. |
| Nadpłata | overpaid może współistnieć z settled i requires_review = true. Stosuj swoją politykę nadpłat; nigdy nie zaliczaj wpłaty na zamówienie dwukrotnie ani nie zwracaj automatycznie środków na niezweryfikowany adres. |
| Spóźniona płatność | expired może później się zmienić, dopóki trwa monitorowanie. timing_status = late wskazuje potrzebę sprawdzenia; nie otwieraj automatycznie ponownie ani nie wysyłaj anulowanego zamówienia. |
| Ręczna akceptacja | invoice.settled może mieć resolution = manually_settled bez kwalifikujących się środków on-chain. Zdecyduj, czy integracja akceptuje takie nadpisanie; pola podsumowania płatności mogą mieć wartość null. |
| Reorganizacja / unieważnienie | Nowsza rewizja może unieważnić wcześniejsze dowody płatności. Pobierz bieżący stan i obsłuż cofnięcie przez uzgadnianie płatności. Nie ignoruj go tylko dlatego, że zamówienie było kiedyś rozliczone. |
| Zero potwierdzeń / zerowa kwota | Rozliczenie bez potwierdzeń może nastąpić przy wykryciu i niesie ryzyko reorganizacji. Jawnie dozwolona faktura na zerową kwotę rozlicza się bez płatności. Żaden z tych przypadków nie wymaga wcześniejszego zdarzenia payment.received. |
Do realizacji zamówienia używaj status = settled, a nie amount_status = paid ani przekierowania ze strony płatności. Przy zerowej liczbie wymaganych potwierdzeń rozliczenie może nastąpić przy wykryciu; niesie to ryzyko reorganizacji.
Niedopłata to amount_status = partial; nadpłata to overpaid. paid oznacza otrzymanie akceptowanego minimum, z uwzględnieniem tolerancji niedopłaty faktury. Są to stany kwoty, a nie statusy faktury. late to timing_status, a nie oddzielne zdarzenie.
Typowy przebieg to new → processing → settled, ale stany pośrednie mogą zostać pominięte. Jawnie dozwolona faktura na zerową kwotę rozlicza się bez płatności i zachowuje amount_status = none. Ręczna akceptacja jest oznaczana jako manually_settled.
Wywołania zwrotne są niezmiennymi zapisami stanu, a nie odpowiedziami ze stanem na żywo. Mogą docierać z opóźnieniem, poza kolejnością lub wielokrotnie. Zdarzenia płatności i statusu mogą współdzielić sekwencję faktury i te same pola stanu, ale mają różne podpisane wartości event_id i event_type. Liczba potwierdzeń nie gwarantuje wywołania zwrotnego dla każdego bloku.
Co otrzymujesz
{
"invoice_id": "11111111-2222-4333-8444-555555555555",
"status": "settled",
"amount_status": "paid",
"timing_status": "on_time",
"resolution": "automatic",
"sequence": 3,
"amount": "49.9",
"currency": "EUR",
"order_id": "order-1042",
"payload_version": 2,
"event_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"event_type": "invoice.settled",
"occurred_at": "2026-09-14T12:05:00Z",
"project_id": "11111111-1111-4111-8111-111111111111",
"store_id": "22222222-2222-4222-8222-222222222222",
"description": "Annual plan",
"email": "ada@example.test",
"customer": {
"firstname": "Ada",
"lastname": "Lovelace",
"countryiso2": "GB"
},
"metadata": {
"firstname": "Ada",
"lastname": "Lovelace",
"countryiso2": "GB",
"cart_id": "cart-681"
},
"created_at": "2026-09-14T12:00:00Z",
"updated_at": "2026-09-14T12:05:00Z",
"expires_at": "2026-09-14T12:15:00Z",
"monitoring_expires_at": "2026-09-21T12:15:00Z",
"settled_at": "2026-09-14T12:05:00Z",
"paid_chain": "ethereum",
"paid_asset": "USDC",
"paid_asset_amount": "58.17342",
"paid_asset_amount_received": "58.17342",
"paid_payment_method_id": "33333333-3333-4333-8333-333333333333",
"settlement_exchange_rate": {
"rate": "1.17",
"units": "asset_per_invoice_currency",
"currency": "EUR",
"symbol": "USDC",
"observed_at": "2026-09-14T12:05:00Z",
"as_of": "2026-09-14T12:04:30Z",
"pricing_provider": "kraken",
"asset_provider": "kraken",
"pricing_fetched_at": "2026-09-14T12:04:30Z",
"asset_fetched_at": "2026-09-14T12:04:30Z",
"stale": false,
"is_fixed": false,
"reference_currency": "USD",
"uses_reference_proxy": false
},
"cancelled_at": null,
"exchange_rate_spread_percent": "0.5",
"underpayment_tolerance_percent": "1",
"reason_code": "payment_confirmed",
"requires_review": false,
"links": {
"checkout": "https://pay.example.com/invoice/11111111-2222-4333-8444-555555555555",
"invoice": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555",
"payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments"
},
"payment_info": {
"active_payment_method_id": "33333333-3333-4333-8333-333333333333",
"method_count": 1,
"methods_truncated": false,
"methods": [
{
"payment_method_id": "33333333-3333-4333-8333-333333333333",
"payment_rail": "onchain",
"chain_slug": "ethereum",
"network": "mainnet",
"caip_network_id": "eip155:1",
"asset_id": "44444444-4444-4444-8444-444444444444",
"asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"asset_name": "USD Coin",
"symbol": "USDC",
"asset_kind": "token",
"asset_decimals": 6,
"contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"token_standard": "erc20",
"destination_address": "0x1111111111111111111111111111111111111111",
"destination_tag": null,
"status": "paid",
"amounts": {
"expected_amount": "58.17342",
"expected_amount_atomic": "58173420",
"received_amount": "58.17342",
"received_amount_atomic": "58173420",
"confirmed_amount": "58.17342",
"confirmed_amount_atomic": "58173420",
"unconfirmed_amount": "0",
"unconfirmed_amount_atomic": "0",
"minimum_payment_amount": "57.591686",
"minimum_payment_amount_atomic": "57591686",
"remaining_amount": "0",
"remaining_amount_atomic": "0",
"remaining_to_full_amount": "0",
"remaining_to_full_amount_atomic": "0",
"overpaid_amount": "0",
"overpaid_amount_atomic": "0"
},
"acceptance": {
"finality_mode": "confirmations",
"required_confirmations": 2,
"observed_confirmations": 2,
"underpayment_tolerance_percent": "1"
},
"quote": {
"effective_rate": "1.1658",
"reference_rate": "1.16",
"units": "asset_per_invoice_currency",
"currency": "EUR",
"symbol": "USDC",
"exchange_rate_spread_percent": "0.5",
"quote_expires_at": "2026-09-14T12:15:00Z",
"provenance_available": true,
"rounding": "up",
"unrounded_payment_amount": "58.17342",
"rounding_adjustment": "0",
"pricing_provider": "kraken",
"asset_provider": "kraken",
"pricing_fetched_at": "2026-09-14T11:59:30Z",
"asset_fetched_at": "2026-09-14T11:59:30Z"
},
"market_rate_at_event": {
"rate": "1.17",
"units": "asset_per_invoice_currency",
"currency": "EUR",
"symbol": "USDC",
"observed_at": "2026-09-14T12:05:00Z",
"pricing_provider": "kraken",
"asset_provider": "kraken",
"pricing_fetched_at": "2026-09-14T12:04:30Z",
"asset_fetched_at": "2026-09-14T12:04:30Z",
"as_of": "2026-09-14T12:04:30Z",
"stale": false,
"is_fixed": false,
"reference_currency": "USD",
"uses_reference_proxy": false
},
"payment_count": 1,
"payments_truncated": false,
"payments": [
{
"payment_id": "55555555-5555-4555-8555-555555555555",
"payment_method_id": "33333333-3333-4333-8333-333333333333",
"transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"payment_hash": null,
"event_index": 0,
"payment_rail": "onchain",
"chain_slug": "ethereum",
"network": "mainnet",
"asset_id": "44444444-4444-4444-8444-444444444444",
"asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"symbol": "USDC",
"asset_decimals": 6,
"amount": "58.17342",
"amount_atomic": "58173420",
"status": "final",
"counts_towards_received": true,
"confirmations": 2,
"block_height": 26000000,
"observed_at": "2026-09-14T12:04:30Z",
"chain_time": "2026-09-14T12:04:20Z",
"finalized_at": "2026-09-14T12:05:00Z",
"explorer_name": "Etherscan",
"explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
],
"links": {
"payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments?payment_method_id=33333333-3333-4333-8333-333333333333"
}
}
]
}
}amount to pierwotna suma faktury. payment_info opisuje zaobserwowane przelewy krypto, nadal brakujące kwoty i zablokowane kursy. Wersja 2 podpisuje też nazwę zdarzenia, jego identyfikator i zakres projektu/sklepu.
Wszystkie pola wywołania zwrotnego i dodatkowe dane faktury
| Pole | Typ | Znaczenie |
|---|---|---|
| invoice_id | UUID | Publiczny UUID faktury, używany przez uwierzytelnioną trasę szczegółów faktury |
| status | string | Zapisany stan faktury: new, processing, settled, expired, invalid, cancelled |
| amount_status | string | none, partial, paid lub overpaid; paid obejmuje akceptowaną tolerancję niedopłaty, a nie ostateczność potwierdzeń |
| timing_status | string | on_time lub late |
| resolution | string | automatic, manually_settled lub manually_invalidated |
| sequence | integer | Rosnąca rewizja faktury; różne zdarzenia mogą współdzielić jedną rewizję. Porównuj bez utraty precyzji liczb całkowitych |
| amount | decimal string | Pierwotna suma faktury, nie otrzymana kwota krypto; zachowaj precyzję dziesiętną |
| currency | string | Waluta pola amount, np. EUR dla faktury w EUR opłaconej USDC |
| order_id | string | null | Identyfikator zamówienia sprzedawcy |
| payload_version | integer | 2 dla nowo generowanych zdarzeń w 4.1.0+; brak w zachowanych starszych zdarzeniach |
| event_id | UUID | Podpisana tożsamość zdarzenia, niezmienna przy ponowieniach i ręcznym ponownym dostarczeniu |
| event_type | string | Jedno z siedmiu zdarzeń subskrypcji |
| occurred_at | timestamp | Czas utworzenia tego niezmiennego zdarzenia, nie czas dostarczenia |
| project_id | UUID | Zakres projektu sprzedawcy; dopasuj do skonfigurowanego odbiornika |
| store_id | UUID | Zakres sklepu sprzedawcy; dopasuj do skonfigurowanego odbiornika |
| description | string | null | Pierwotny opis faktury |
| string | null | Opcjonalny e-mail klienta w chwili utworzenia zdarzenia | |
| customer | object | Rozpoznawane opcjonalne pola metadanych klienta; bez odgadywanych lub wzbogacanych danych osobowych |
| metadata | object | Pierwotne metadane sprzedawcy w postaci z chwili utworzenia zdarzenia |
| created_at | timestamp | Czas utworzenia faktury |
| updated_at | timestamp | Czas aktualizacji stanu faktury |
| expires_at | timestamp | Termin płatności faktury |
| monitoring_expires_at | timestamp | Termin zakończenia monitorowania spóźnionych płatności |
| settled_at | timestamp | null | Czas rozliczenia |
| paid_chain | string | null | 4.1.2+: slug blockchaina potwierdzonej metody rozliczenia, np. ethereum; null bez zapisanego kwalifikującego rozliczenia |
| paid_asset | string | null | 4.1.2+: symbol natywnej monety lub tokena, np. BTC, ETH lub USDC; etykieta do wyświetlania, nie unikalna tożsamość aktywa |
| paid_asset_amount | decimal string | null | 5.0.1+: pełna zablokowana żądana kwota w jednostkach paid_asset, przed odjęciem tolerancji; zapisana przy rozliczeniu |
| paid_asset_amount_received | decimal string | null | 5.0.1+: łączna prawidłowa kwota otrzymana zwycięską metodą przy rozliczeniu, z akceptowanymi niedopłatami/nadpłatami; zamrożona, a nie bieżące saldo |
| paid_payment_method_id | UUID | null | 4.1.2+: identyfikator intencji rozliczającej; odpowiada payment_info.methods[].payment_method_id i jej dokładnej sieci/kontraktowi |
| settlement_exchange_rate | object | null | 4.1.2+: zapisany przy rozliczeniu stan rynku przed narzutem kursowym, z jawnymi jednostkami, walutą, znacznikami czasu źródeł i znacznikami jakości; nigdy nie jest ponownie wyceniany przy dostarczeniu |
| cancelled_at | timestamp | null | Czas anulowania |
| exchange_rate_spread_percent | decimal string | Zablokowany narzut kursowy, nie bieżąca wartość domyślna sklepu |
| underpayment_tolerance_percent | decimal string | Zablokowana tolerancja faktury; każda metoda podaje też swoją efektywną tolerancję |
| reason_code | string | null | Przyczyna zmiany stanu w formacie maszynowym |
| requires_review | boolean | Wskazówka dotycząca wyjątku płatności; nie zezwolenie na automatyczną realizację lub zwrot |
| links | object | Adresy URL strony płatności, uwierzytelnionej faktury i płatności w chwili utworzenia zdarzenia. Obowiązują preferencje domen z Sklep → Podstawowe, potem sklep domyślny, a następnie globalna domena główna; używane są tylko aktywne domeny pasujące do roli. Ponowienia zachowują pierwotne podpisane linki; null, jeśli brak aktywnego rekordu hosta. |
| payment_info | object | Rzeczywiście zaobserwowane metody, dokładne kwoty, zablokowana wycena, orientacyjny stan rynku i ograniczona lista obserwacji płatności; zobacz grupy pól poniżej |
Podsumowanie rozliczenia: settlement_exchange_rate
| Pole | Typ | Znaczenie |
|---|---|---|
| rate / units / currency / symbol | strings | Jednostki aktywa przed narzutem kursowym na jedną jednostkę waluty faktury. Ciąg dziesiętny, nie kwota płatności ani wykonana transakcja wymiany. |
| observed_at / as_of | timestamps | Czas zapisania rozliczenia / starszy znacznik czasu źródła. Nie traktuj buforowanych danych jak bieżącego notowania. |
| pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_at | strings / timestamps | Źródła cen waluty fiducjarnej i aktywa oraz czasy ich pobrania, zapisane przy rozliczeniu. |
| stale / is_fixed / uses_reference_proxy / reference_currency | booleans / string | Te same znaczniki jakości co w market_rate_at_event. Stałe ceny projektu są oznaczone; walutą odniesienia jest USD. |
| Missing snapshot or price | null | Bez odgadywania historycznego kursu. Przed rozliczeniem wszystkie pola podsumowania mają wartość null; sam brak cen pozostawia dostępne potwierdzone identyfikatory paid_*. |
Metody płatności: payment_info
| Pole | Typ | Znaczenie |
|---|---|---|
| active_payment_method_id | UUID | null | Zwycięska lub wybrana zaobserwowana metoda. Null przed wykryciem lub po unieważnieniu; domyślna metoda nie jest odgadywana. |
| method_count / methods_truncated | integer / boolean | Łączna liczba zaobserwowanych metod i informacja, czy osadzona lista methods jest niepełna. |
| methods[] | object[] | Najwyżej osiem zaobserwowanych metod, aktywna jako pierwsza. Bez sumowania różnych aktywów. |
| payment_method_id / payment_rail | UUID / string | Tożsamość intencji faktury i transport onchain lub lightning. |
| chain_slug / network / caip_network_id | string | Tożsamość sieci. Zawsze łącz tożsamość tokena z jego siecią. |
| asset_id / asset_key / caip_asset_id | UUID / string / nullable string | Zweryfikowana tożsamość w rejestrze; same symbole nie są unikalne. |
| asset_name / symbol / asset_kind | string | Wyświetlana nazwa aktywa, symbol i rodzaj: natywne lub token. |
| contract_address / token_standard | string | null | Kontrakt lub mint tokena i standard; null dla aktywów natywnych. |
| asset_decimals | integer | Precyzja atomowa; Lightning BTC używa 11. |
| destination_address / destination_tag | string | null | Publiczny adres odbiorczy i wymagane memo/tag. Adres ma wartość null dla Lightning; nigdy nie jest kluczem prywatnym. |
| status | string | Stan metody: pending, partial, paid, overpaid, expired lub invalid. Paid samo w sobie nie oznacza rozliczenia faktury. |
| payment_count / payments_truncated / payments[] | integer / boolean / object[] | Łączna liczba obserwacji i najwyżej pięć najnowszych. Każda obserwacja jest opisana poniżej. |
| links.payments | HTTPS URL | null | Uwierzytelniona, stronicowana historia tej metody na skonfigurowanym origin API. |
Dokładne kwoty: methods[].amounts
| Pole | Typ | Znaczenie |
|---|---|---|
| expected_amount | decimal string | Pełna zablokowana wycena po narzucie kursowym i zaokrągleniu w górę. |
| received_amount / confirmed_amount | decimal strings | Prawidłowo wykryte środki / środki spełniające politykę potwierdzeń lub ostateczności tej metody. |
| unconfirmed_amount | decimal string | max(received - confirmed, 0). Nie jest to dodatkowa kwota do wysłania. |
| minimum_payment_amount | decimal string | Akceptowany próg po uwzględnieniu tolerancji. Może być niższy od pełnej wyceny. |
| remaining_amount | decimal string | max(minimum accepted - received, 0). Dodatkowe środki potrzebne do osiągnięcia akceptowanego progu, nie postęp potwierdzeń. |
| remaining_to_full_amount | decimal string | max(full quote - received, 0), z pominięciem tolerancji. |
| overpaid_amount | decimal string | max(received - full quote, 0). Nie upoważnia do automatycznego zwrotu. |
| Every amount's *_atomic companion | integer string | Dokładna reprezentacja w najmniejszych jednostkach. Używaj bibliotek dziesiętnych lub całkowitoliczbowych; nigdy float ani JavaScript Number dla pieniędzy. |
Polityka potwierdzeń: methods[].acceptance
| Pole | Typ | Znaczenie |
|---|---|---|
| finality_mode / required_confirmations | string / integer | Zablokowana liczba potwierdzeń lub polityka finalized. Zero potwierdzeń jest jawnie dozwolone przez politykę sprzedawcy, nie oznacza powszechnej ostateczności sieci. |
| observed_confirmations | integer | null | Minimum wśród prawidłowych obserwacji, nie tylko najnowszego przelewu. Null dla Lightning lub przy braku prawidłowych obserwacji. |
| underpayment_tolerance_percent | decimal string | Efektywna tolerancja metody. Lightning używa zera, nawet jeśli faktura ma niezerową tolerancję on-chain. |
Kursy: methods[].quote i market_rate_at_event
| Pole | Typ | Znaczenie |
|---|---|---|
| quote.effective_rate / units / currency / symbol | strings | Zablokowany kurs asset_per_invoice_currency z narzutem kursowym; waluta i symbol jawnie określają kierunek. |
| quote.exchange_rate_spread_percent / quote_expires_at | decimal string / timestamp | Zablokowany narzut kursowy i termin wyceny. Nigdy nie zastępują ich bieżące ustawienia sklepu. |
| quote.reference_rate / unrounded_payment_amount / rounding_adjustment | decimal string | null | Wartość odniesienia przed narzutem kursowym, kwota płatności przed zaokrągleniem i korekta w górę w jednostkach aktywa. |
| quote.pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_at | string or timestamp | null | Pierwotne źródła/czasy wyceny waluty i aktywa. Bez kluczy API ani danych dostępu dostawców. |
| quote.provenance_available / rounding | boolean / string | False dla starych faktur bez zapisanego stanu źródeł; zaokrąglanie następuje w górę. |
| market_rate_at_event | object | null | Orientacyjny buforowany stan rynku w chwili utworzenia zdarzenia. Brakujące dane pozostają null; nigdy nie zmienia kwot faktury ani nie czeka na pobranie przez sieć. |
| market_rate_at_event.rate / units / currency / symbol | strings | Kurs rynkowy przed narzutem, z tym samym jawnym kierunkiem co quote. |
| market_rate_at_event.observed_at / as_of / pricing_fetched_at / asset_fetched_at | timestamps | Czas zapisu zdarzenia / starszy z dwóch czasów źródeł / czas każdego źródła. |
| market_rate_at_event.pricing_provider / asset_provider | strings | Buforowane źródła waluty i aktywa, w tym skonfigurowane ceny niestandardowych tokenów. |
| market_rate_at_event.stale / is_fixed / uses_reference_proxy / reference_currency | booleans / string | Czy pamięć podręczna jest nieaktualna, cena tokena stała lub odniesienie USD używa stablecoina jako przybliżenia. Walutą odniesienia jest USD. Nieaktualne dane mają charakter orientacyjny, nigdy nie są świeżą wyceną. |
Zapisy przelewów: methods[].payments[] i GET …/payments
| Pole | Typ | Znaczenie |
|---|---|---|
| payment_id / payment_method_id | UUID | Tożsamość obserwacji / tożsamość nadrzędnej intencji. Używaj payment_id do usuwania duplikatów historii. |
| transaction_id / payment_hash / event_index | string | null / integer | Hash on-chain i indeks przelewu/logu/wyjścia lub hash Lightning. Lightning nie ma transakcji ani linku do eksploratora. |
| payment_rail / chain_slug / network / asset_id / asset_key / caip_asset_id / symbol / asset_decimals | strings / UUID / integer | Te same identyfikatory aktywa i sieci co w metodzie nadrzędnej. |
| amount / amount_atomic | decimal / integer strings | Dokładna wartość tego przelewu, nigdy przeliczenie na walutę fiducjarną. |
| status / counts_towards_received | string / boolean | detected, confirming i final są wliczane; reorged, replaced i invalid nie są. Zachowuj unieważnioną historię do uzgadniania płatności. |
| confirmations / block_height | integer | null | Dane bloku obserwacji; potwierdzenia mają wartość null dla Lightning. |
| observed_at / chain_time / finalized_at | timestamp | null | Pierwsze lokalne wykrycie, zaufany czas blockchaina, jeśli dostępny, i czas osiągnięcia ostateczności według polityki, jeśli nastąpiła. |
| explorer_name / explorer_url | string | null | Zweryfikowane odwołanie do publicznego eksploratora bloków, tam gdzie jest obsługiwane. |
Merchant 5.13.3 wyklucza zweryfikowane wewnętrzne przelewy finansujące gas z sum płatności klientów, payment_info, API płatności faktury, limitów zwrotów i zdarzeń payment.received. Ich zapisy blockchainowe/skarbca pozostają dostępne do księgowania portfeli. Zwykłe przelewy i rzeczywiste nadpłaty nadal są wliczane. Istniejące podpisane treści wywołań zwrotnych nigdy nie są przepisywane. Jeśli historyczne rozliczenie zależało od finansowania wewnętrznego zamiast środków klienta, uzgadnianie emituje invoice.invalid z reason_code internal_gas_funding_excluded; sprawdź je zamiast ponownie realizować zamówienie.
Merchant 4.1.0 dodaje payload_version 2 bez przenoszenia ani zmiany pierwotnych dziewięciu pól. Wcześniej zakolejkowane zdarzenia zachowują pierwotną treść i mogą nie mieć payload_version. event_id, event_type i identyfikatory projektu/sklepu znajdują się teraz w podpisanej treści; transportowe nagłówki zdarzenia/dostarczenia pozostają niepodpisane.
payment_info opisuje zaobserwowane płatności, a nie każdą oferowaną opcję płatności. Przed wykryciem active_payment_method_id ma wartość null, a methods jest puste. Obserwacje po reorganizacji lub unieważnione mogą pozostać w methods nawet po zmianie aktywnej metody na null. Nigdy nie sumuj kwot różnych aktywów ani sieci.
Wszystkie kwoty, atomowe liczby całkowite, kursy i procenty są ciągami znaków. received_amount obejmuje prawidłowe środki oczekujące na potwierdzenie; confirmed_amount spełnia politykę ostateczności tej metody. remaining_amount to max(minimum_payment_amount minus received_amount, 0); remaining_to_full_amount to max(expected_amount minus received_amount, 0). Przykład: oczekiwane 100 USDC, otrzymane 99 i tolerancja 1% oznaczają remaining_amount 0 i remaining_to_full_amount 1. Ostateczność nadal jest wymagana.
quote to zablokowane wyliczenie faktury: jednostki aktywa na jedną jednostkę waluty faktury. Narzut kursowy jest stosowany przed zaokrągleniem w górę. Do dokładnego porównania płatności używaj expected_amount_atomic; sam wyświetlany kurs może nie odtworzyć zaokrąglenia w górę. Stare faktury bez zapisanych informacji o pochodzeniu źródeł udostępniają pola source/reference/rounding jako null i provenance_available false, nigdy dzisiejsze dane przedstawione jako historyczna wycena.
market_rate_at_event to orientacyjne dane z pamięci podręcznej sprzed narzutu kursowego, zamrożone w chwili utworzenia zdarzenia. Zawiera czasy źródeł oraz znaczniki nieaktualności i zastępczego odniesienia; ma wartość null, jeśli brak użytecznej pary w pamięci podręcznej. Żadne żądanie bieżącego kursu nie blokuje powiadomienia, a ta obserwacja rynku nigdy nie zmienia należnej kwoty. Niestandardowe tokeny ze stałą ceną są oznaczone is_fixed; tokeny DEX używają źródła właściwego dla projektu, a nie tokena o tym samym symbolu.
Pola najwyższego poziomu paid_chain, paid_asset, paid_payment_method_id i settlement_exchange_rate (4.1.2+) identyfikują potwierdzoną zwycięską metodę po rozliczeniu, a nie wybraną opcję płatności ani sumę różnych metod. Przed rozliczeniem, po unieważnieniu, dla starszych rozliczeń bez zapisanego stanu lub przy ręcznej akceptacji bez kwalifikujących się środków ostatecznych według polityki pola podsumowania mają wartość null. Symbole są etykietami do wyświetlania: użyj identyfikatora metody, aby ustalić dokładną tożsamość sieci/aktywa/kontraktu.
Merchant 5.0.1 dodaje paid_asset_amount i paid_asset_amount_received jako dokładne ciągi dziesiętne w jednostkach paid_asset; payload_version pozostaje 2. paid_asset_amount to pełna zablokowana wycena z narzutem kursowym i zaokrągleniem w górę, nigdy próg tolerancji ani pozostałe saldo. paid_asset_amount_received to suma prawidłowych wpływów zwycięskiej metody przy rozliczeniu, obejmująca środki oczekujące na potwierdzenie oraz każdą zaakceptowaną niedopłatę lub nadpłatę. Przykład: wycena 100 USDC, otrzymane 99 i zaakceptowane z tolerancją dają 100 i 99, a nie 99 i 99. Oba pola są zamrożone z zapisem rozliczenia; do wpływów przy każdym zdarzeniu używaj payment_info.methods[].amounts, a do bieżących zapisów - API płatności. Mają wartość null bez kwalifikującego zapisu i dla zapisów sprzed 5.0.1; stare zakolejkowane treści zdarzeń pozostają niezmienione. Nigdy nie konwertuj dokładnych ciągów dziesiętnych na liczby zmiennoprzecinkowe do księgowania.
settlement_exchange_rate to buforowana obserwacja rynku przed narzutem kursowym, zapisana przy rozliczeniu, a nie zablokowana wycena faktury ani wykonana transakcja giełdowa. Jej struktura odpowiada market_rate_at_event; 1.17 asset_per_invoice_currency przy EUR/USDC oznacza 1 EUR = 1.17 USDC. Znaczniki czasu źródeł i flagi stale/fixed/proxy opisują jakość. Brak pary pozostawia kurs null, ale potwierdzona metoda nadal ma pola paid_*. Nigdy nie zmienia należnej kwoty ani nie czeka na bieżące wywołanie dostawcy. Późniejsze płatności tą samą metodą, ponowienia i ponowne dostarczenia nie mogą zastąpić zapisanego stanu, także zapisanego kursu null. Rzeczywiste ponowne rozliczenie lub zmiana metody rozliczającej zapisuje nowy stan; observed_at identyfikuje ten zapis, podczas gdy settled_at może zachować czas pierwszego rozliczenia. Stare treści zdarzeń pozostają niezmienione.
Dołączanych jest najwyżej osiem zaobserwowanych metod i pięć najnowszych obserwacji płatności na metodę, wraz z licznikami i znacznikami obcięcia. Limit rozmiaru danych może dalej zmniejszyć te tablice. Obserwacja płatności to jeden przelew/log/wyjście UTXO, niekoniecznie unikalny hash transakcji. Użyj GET /v1/projects/YOUR_PROJECT_ID/invoices/{invoice_id}/payments z payment_method_id, limit i offset, aby uzyskać pełną bieżącą historię. Szczegóły faktury zachowują każdą wycenioną metodę i jej quote_details. Linki API wymagają skonfigurowanego hosta i danych dostępu; nigdy nie przekazuj tokena bearer pod dowolny adres URL podany w wywołaniu zwrotnym.
Lightning używa payment_hash zamiast transaction_id; adres odbiorczy, eksplorator i zaobserwowane potwierdzenia mają wartość null. Dokładna kwota BTC używa 11 miejsc dziesiętnych (millisatoshi), a efektywna tolerancja wynosi zero. Dane nie zawierają preimage płatności BOLT11, klucza portfela, sekretu podpisującego ani danych dostępu dostawcy. Pola klienta/metadanych należą wyłącznie do odpowiedzi dla sprzedawcy i podpisanych wywołań zwrotnych, nigdy do publicznej strony płatności; nie umieszczaj danych dostępu w metadanych.
Odbieraj bezpiecznie
- Przed parsowaniem zweryfikuj dokładną surową treść odpowiednim sekretem. Sklep → IPN udostępnia sekret IPN, także dla dostarczeń pod własny ipn_url. Każdy punkt końcowy w Sklep → Webhooki ma własny sekret. Żaden nie jest tokenem API; rotacja jednego nie rotuje pozostałych.
- Sprawdź podpisany znacznik czasu (domyślnie w SDK: pięć minut w obie strony) i dopasuj podpisane identyfikatory projektu/sklepu do konfiguracji odbiornika, jeśli są obecne. Zapisz trwale do kolejki przed zwróceniem HTTP 2xx. Przy przetwarzaniu poszczególnych zdarzeń event_id w v2 jest podpisany; same identyfikatory nagłówków nie chronią przed powtórzeniem, bo nagłówki nie są podpisane. W skrzynkach stanów zamówień usuwaj duplikaty invoice_id i sequence oraz porównuj pierwotne pola stanu faktury, nie całą treść v2: różne typy/identyfikatory zdarzeń mogą współdzielić rewizję.
- W procesie roboczym pobierz bieżącą fakturę ze skonfigurowanego origin API, a nie dowolnego linku wywołania zwrotnego. Dopasuj zapisane zamówienie, projekt/sklep, kwotę i walutę, wymagaj bieżącego statusu settled i zastosuj swoją politykę ręcznej akceptacji oraz wyjątków. Zablokuj zamówienie i zrealizuj je raz w transakcji bazy danych, niezależnie od usuwania duplikatów zdarzeń.
- Nigdy nie nadpisuj nowszej sequence starszą. Różne zdarzenia mogą współdzielić rewizję; nie łącz deduplikacji na poziomie rewizji z filtrem tylko dla invoice.settled. Ponowne otwarcie/uzgadnianie może zmienić status; aktualizacje porządkuje sequence, nie stały ranking statusów. Zapisuj cofnięcia do sprawdzenia zamiast ponownie realizować zamówienie.
Przykłady odbiorników: PHP · Python · Node.js / TypeScript.
Weryfikacja podpisu i zasady dostarczania
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWhollySignature(rawBody, header, signingSecret, toleranceSeconds = 300) {
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
if (!match) return false;
const timestamp = Number(match[1]);
if (!Number.isSafeInteger(timestamp)) return false;
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > toleranceSeconds) return false;
// rawBody must be the exact request Buffer, before JSON parsing.
const expected = createHmac("sha256", signingSecret)
.update(String(timestamp))
.update(".")
.update(rawBody)
.digest();
const presented = Buffer.from(match[2], "hex");
return timingSafeEqual(expected, presented);
}| Zasada dostarczania | Szczegóły |
|---|---|
| Nagłówki | Wholly-Signature, Wholly-Event-Id i Wholly-Delivery-Id; Content-Type to application/json. |
| Podpis | HMAC-SHA256 dla <unix timestamp>.<exact raw body>; format nagłówka t=<timestamp>,v1=<64 lowercase hex>. |
| Sukces | Dowolna odpowiedź HTTP 2xx. Przekierowania nie są śledzone; odpowiedzi inne niż 2xx oznaczają niepowodzenie. |
| Limity czasu | 5 sekund na połączenie i 10 sekund całkowitego czasu żądania. |
| Harmonogram ponowień | Do 8 prób dla błędów dopuszczających ponowienie: natychmiast, potem po 10 s, 1 min, 5 min, 15 min, 1 h, 6 h i 24 h od zakończenia poprzedniej próby. IPN ponawia automatycznie; automatyczne ponawianie webhooka można wyłączyć dla danego punktu końcowego. |
| Bezpieczeństwo celu | Tylko publiczne HTTPS. DNS jest ponownie weryfikowany i przypinany na czas dostarczenia; cele lokalne/prywatne/zarezerwowane są odrzucane. |
| Przechowywanie zdarzeń | Treści zdarzeń powiadomień i historia dostarczeń mają zaplanowany okres przechowywania 90 dni; zachowane szczegóły są usuwane w ograniczonych partiach. |
| Usuwanie duplikatów | Zapisuj trwale podpisane invoice_id i sequence w zakresie skonfigurowanego projektu. Wholly-Event-Id identyfikuje zdarzenie; Wholly-Delivery-Id identyfikuje zapis dostarczenia (ponowienia używają go ponownie; ręczne ponowne dostarczenie tworzy nowy). Żaden z tych nagłówków identyfikatora nie jest podpisany. |
| Nazewnictwo zdarzeń | Wersja 2 podpisuje event_id i event_type w treści. Starsze zakolejkowane zdarzenia nie mają żadnego z nich. Różne typy zdarzeń mogą współdzielić sequence faktury; uzgadniaj stan faktury według rewizji lub usuwaj duplikaty poszczególnych zdarzeń według podpisanego event_id. |
| Rotacja sekretu | Rotacja nie ma okresu nakładania ani nagłówka wersji i natychmiast zmienia podpisy zakolejkowanych, ponawianych i ręcznych dostarczeń. |
| Wstrzymane dostarczenia | Niewystarczające środki na przetwarzanie wstrzymują IPN/webhooki, w tym ponowienia. Płatności przychodzące nadal działają; zakolejkowane powiadomienia wznawiają się po doładowaniu, w okresie przechowywania ich treści. |
Asystenci AI · MCP
Podłącz asystenta do swojej instalacji sprzedawcy.
Merchant 5.0.0 zawiera opcjonalnie włączany serwer MCP w skonfigurowanej domenie API. Działa wewnątrz Twojej instalacji, nie przez wspólny przekaźnik Wholly Crypto.
- Otwórz Ustawienia → Dostęp API. Utwórz oddzielne dane dostępu, przypisz tylko projekty potrzebne asystentowi i zacznij od dostępu tylko do odczytu. Na koncie hostowanym przez operatora to operator najpierw włącza usługę MCP instalacji; Ty zarządzasz tylko własnymi danymi dostępu i zezwoleniami.
- W Połączenia AI · MCP włącz MCP, wybierz dane dostępu i zapisz ich dostęp MCP. Istniejące dane dostępu nie mają dostępu MCP, dopóki nie zostanie jawnie włączony.
- Skopiuj adres URL serwera MCP do ustawień zdalnego serwera HTTP klienta. W przypadku OAuth zaloguj się do panelu sprzedawcy, sprawdź nazwę klienta i adres powrotny, wybierz dane dostępu i zatwierdź. Dotychczasowe zabezpieczenia Basic Auth i TOTP nadal obowiązują.
- Tworzenie faktur wymaga dodatkowo danych dostępu z prawem odczytu i zapisu, opcji Odczyt + tworzenie faktur w polityce MCP, zakresu OAuth mcp:invoice:create i jawnej zgody. Połączenie OAuth nigdy nie uzyskuje dostępu do projektów dodanych do danych dostępu po zatwierdzeniu.
{
"mcpServers": {
"whollycrypto": {
"url": "https://api.example.com/mcp"
}
}
}| Narzędzie | Dostęp | Cel |
|---|---|---|
| list_projects | Odczytaj | Włączone projekty przypisane do połączenia; stronicowanie limit/offset. |
| list_stores | Odczytaj | Sklepy, identyfikatory i stan włączenia w project_id; stronicowanie limit/offset. |
| list_payment_methods | Odczytaj | Skonfigurowane metody blockchainowe, tokenowe i Lightning dla project_id + store_id. |
| get_wallet_balances | Odczytaj | Adresy odbiorcze i buforowane salda z polami aktualności/dostępności; nigdy sekrety portfeli. |
| list_invoices | Odczytaj | Faktury projektu, filtrowane według sklepu, statusu lub wyszukiwania; stronicowanie limit/offset. |
| get_invoice | Odczytaj | Pełne szczegóły faktury i link płatniczy przy użyciu project_id + invoice_id. |
| get_delivery_history | Odczytaj | Statusy IPN/webhooków sklepu, próby i wyniki HTTP. Opcjonalne filtry invoice_id/kind; bez sekretów ani treści wywołań zwrotnych. |
| convert_amount | Odczytaj | Buforowane przeliczenie referencyjne przy użyciu from, to i kwoty jako ciągu dziesiętnego; nie wycena faktury. |
| create_invoice | Jawny zapis | project_id, store_id, idempotency_key i invoice (istniejąca treść tworzenia faktury). invoice.payment_methods filtruje włączone metody sklepu; 5.4.0+ pomija nieaktywne/nieakceptowane opcje i wraca do domyślnych ustawień sklepu, jeśli żadna nie pasuje. Wybór samego blockchaina obejmuje wszystkie aktywne akceptowane aktywa. asset_tickers ograniczone do blockchaina są obsługiwane od 5.3.0. Zwraca zwykłą odpowiedź faktury. |
Protokół, OAuth i bezpieczeństwo
Używaj Streamable HTTP przez HTTPS. Wynegocjuj ogłaszaną wersję protokołu i dodawaj MCP-Protocol-Version do kolejnych żądań POST. Wysyłaj Content-Type: application/json i Accept: application/json, text/event-stream. Odpowiedzi to skończone JSON; ponowne połączenia nie wymagają identyfikatora sesji MCP.
OAuth używa krótkotrwałych tokenów dostępu (15 minut), jednorazowych kodów S256 PKCE (5 minut) i rotowanych tokenów odświeżania (czas życia połączenia 30 dni). Ponowne użycie wykorzystanego tokena odświeżania unieważnia to połączenie. Po wygaśnięciu, rotacji danych dostępu, zmianie polityki lub kanonicznej domeny API połącz się ponownie.
Wykrywanie OAuth jest publiczne tylko przy włączonym MCP. Parametr resource musi być równy kanonicznemu adresowi URL zwróconemu przez wykrywanie, wraz z /mcp. Rejestracja dynamiczna jest obsługiwana; zdalne dokumenty metadanych identyfikatora klienta i sekrety klientów nie są.
Klienci obsługujący własne nagłówki Authorization mogą zamiast tego użyć tokena API sprzedawcy z włączonym MCP jako Bearer. Zachowuje on oddzielne uprawnienia REST; do połączenia ograniczonego do MCP preferuj OAuth. Nigdy nie wklejaj danych dostępu do czatu, adresów URL, argumentów narzędzi ani repozytorium kodu.
MCP współdzieli minutowy limit REST danych dostępu i dokładne ograniczenia źródłowego IP, a także ograniczenia IP hosta API. OAuth nie omija listy dozwolonych adresów. Dla zdalnych klientów AI zezwól na udokumentowane wyjściowe adresy IP lub świadomie pozostaw to ograniczenie wyłączone. Do tras MCP/OAuth nie należy stosować wyzwań bezpieczeństwa WWW ani buforowania.
Błędy HTTP: 401 wymaga uwierzytelnienia, 403 odmawia origin/IP/uprawnień, 404 oznacza wyłączone MCP lub błędny host, 405 nakazuje użyć POST, 413 oznacza limit treści 32 KiB, 429 zawiera Retry-After. Błędy JSON-RPC używają error.code; błędy narzędzi używają result.isError=true nawet przy HTTP 200. Udane wyniki zawierają content i structuredContent.
Listy domyślnie zawierają 25 wierszy, maksymalnie 100; offset jest ograniczony do 1000000. Odpowiedzi narzędzi są ograniczone do 2 MiB. Wygasłe zezwolenia, żądania autoryzacji i przedziały limitów są automatycznie usuwane; ustawienia pokazują najwyżej 100 aktywnych połączeń OAuth.
Wyłączonych projektów/sklepów nie można obsługiwać przez MCP. Połączenie może wyświetlić stan włączenia sklepu, ale odczyt jego metod płatności, historii dostarczania lub tworzenie faktur wymaga włączonego sklepu. Zwykli użytkownicy projektów w panelu nie mogą administrować MCP.
Używaj nowego idempotency_key dla nowej faktury; po przekroczeniu czasu oczekiwania ponów próbę z tymi samymi danymi dostępu, kluczem i identycznym obiektem invoice. Kwoty dziesiętne, narzut kursowy, tolerancja, potwierdzenia i wygląd strony płatności podlegają kontraktowi faktury REST. MCP nigdy nie omija polityki płatności ani salda sprzedawcy.
Początkowy zestaw narzędzi nie może ujawniać kluczy prywatnych/fraz odzyskiwania, wysyłać środków ani wykonywać sweep, zwrotów, ponownych wywołań zwrotnych, zmieniać metod płatności, edytować kont/domen ani zarządzać rozliczeniami. Traktuj opisy faktur, pola klientów i metadane jako niezaufane dane, nie instrukcje dla agenta. Podłączeni dostawcy AI otrzymują dane, których odczyt zatwierdzisz.
| Metoda | Ścieżka | Kontrakt |
|---|---|---|
| POST | /mcp | Uwierzytelnione JSON-RPC: initialize, ping, tools/list, tools/call. Żądania powiadomień zwracają 202; partie żądań są odrzucane. |
| GET / DELETE | /mcp | Uwierzytelnione 405: skończone odpowiedzi JSON, bez samodzielnego strumienia SSE i bez sesji MCP po stronie serwera. |
| GET | /.well-known/oauth-protected-resource/mcp | Kanoniczny adres URL zasobu i wykrywanie serwera autoryzacji; dostępne też pod /.well-known/oauth-protected-resource. |
| GET | /.well-known/oauth-authorization-server | Punkty końcowe OAuth, authorization_code/refresh_token, S256 PKCE i obsługiwane zakresy. |
| POST | /mcp/oauth/register | Rejestracja klienta publicznego: client_name i dokładne redirect_uris. Tylko HTTPS lub HTTP pętli zwrotnej. Bez sekretu klienta ani pobierania zdalnych metadanych. |
| GET | /mcp/oauth/authorize | client_id, redirect_uri, response_type=code, resource, code_challenge, code_challenge_method=S256, opcjonalne scope/state; przekierowuje do zatwierdzenia w panelu. |
| POST | /mcp/oauth/token | Zakodowane jako formularz authorization_code + code + code_verifier + redirect_uri lub refresh_token + refresh_token. Zawsze dołączaj client_id i resource. |
| POST | /mcp/oauth/revoke | client_id i token zakodowane jako formularz. Unieważnia pasujące połączenie tokena dostępu/odświeżania. |
Przykład bezpośredniego żądania narzędzia
Najpierw zainicjuj i wynegocjuj protokół przez klienta MCP. To przykład kolejnego żądania.
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/mcp" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'MCP-Protocol-Version: 2025-11-25' \
--header 'Accept: application/json, text/event-stream' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}`;
const response = await fetch("https://api.example.com/mcp", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"MCP-Protocol-Version": "2025-11-25",
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}
JSON;
$ch = curl_init("https://api.example.com/mcp");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "MCP-Protocol-Version: 2025-11-25", "Accept: application/json, text/event-stream", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"MCP-Protocol-Version": "2025-11-25",
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}""".encode("utf-8")
request = Request("https://api.example.com/mcp",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))API operatora
Twórz hostowane konta sprzedawców z oddzielnymi kluczami serwerowymi o ograniczonym zakresie.
Hostuj wiele firm i automatyzuj ich konfigurację przez api.example.com/v1/operator. Dostępne od 7.4.0 wyłącznie w trybie Operator. Zwykłe API Merchant pozostaje bez zmian.
- Otwórz Operator → Ustawienia → API Operator i włącz je (domyślnie wyłączone). Utwórz oddzielne dane dostępu obejmujące tylko wymagane uprawnienia i hostowanych sprzedawców.
- Przechowuj klucz wc_operator_ na serwerze. Używaj nazwy hosta API, a nie nazwy hosta panelu Operator ani klucza sprzedawcy.
- Przed każdym żądaniem POST Operator zapisuj trwale Idempotency-Key i dokładną treść żądania. Przy niepewnym wyniku odczytaj konto ponownie; nigdy nie zastępuj klucza tylko po to, by ponowić próbę.
- Utwórz sprzedawcę z onboarding: direct i hasłem albo onboarding: invitation bez hasła. Następnie utwórz projekty/sklepy i wydaj klucz sprzedawcy ograniczony do projektu dla jego integracji płatności.
| Zakres | Dostęp |
|---|---|
| merchants.read / merchants.write | Listowanie/odczyt i tworzenie/aktualizacja hostowanych sprzedawców. |
| users.read / users.write / users.security | Odczyt/tworzenie/aktualizacja użytkowników; zmiana haseł i unieważnianie sesji oddzielnie. Nigdy nie tworzy administratora operatora. |
| invitations.read / invitations.write | Listowanie/odczyt, tworzenie, zastępowanie i unieważnianie jednorazowych linków zaproszenia/resetu. Nowi użytkownicy wymagają też users.write; resety wymagają też users.security. |
| credits.read / credits.write / fees.write | Odczyt sald/księgi; przyznawanie lub korygowanie lokalnych środków; ustawianie przyszłych opłat. Niezerowe saldo początkowe wymaga credits.write. |
| topups.read / topups.write | Odczyt lub tworzenie żądań płatności za doładowanie hostowanego sprzedawcy. Żadna operacja API nie może oznaczyć ich jako opłaconych. |
| projects.read / projects.write / reports.read | Konfiguracja projektów, sklepów, wyglądu i ustawień płatności sprzedawcy; odczyt faktur, sald portfeli i raportów finansowych. |
| merchant_credentials.read / merchant_credentials.write | Zarządzanie zwykłymi kluczami sprzedawcy o ograniczonym zakresie. Duże uprawnienia: po wydaniu te klucze działają niezależnie. |
| events.read / webhooks.write / audit.read / health.read | Odczyt historii cyklu życia; konfiguracja podpisanych wywołań zwrotnych cyklu życia; odczyt audytu/możliwości/stanu węzłów. |
Wdrażanie kont, saldo, uprawnienia i bezpieczne ponawianie
| Temat | Zasada |
|---|---|
| Dane dostępu | Opcjonalny termin ważności i dokładna lista dozwolonych IPv4/IPv6; domyślnie 60 żądań/minutę, konfigurowalne 1–600. Każde żądanie sprawdza administratora wystawiającego i bieżące zakresy. HTTP 429 zawiera Retry-After. |
| Izolacja | Klucze mają dostęp tylko do przypisanych hostowanych sprzedawców. Tworzenie sprzedawców i przeglądanie raportów całej instalacji wymaga dostępu do wszystkich sprzedawców. Własna działalność operatora jest wykluczona. |
| Pierwsze logowanie | Konta bezpośrednie potwierdzają, że host może uzyskać dostęp do ich kluczy portfeli. require_password_change dodaje zmianę hasła przy pierwszym logowaniu. Przyjęcie zaproszenia wymaga wyraźnego potwierdzenia powiernictwa, a następnie zwykłego logowania. Basic Auth i istniejące TOTP pozostają w mocy. |
| Zaproszenia | Linki dla nowych użytkowników są ważne 48 godzin; linki resetu hasła - godzinę. Tokeny są jednorazowe. Ponowne wystawienie unieważnia stary link. Przyjęcie przez SMTP nie gwarantuje dostarczenia do skrzynki; sprawdź email_delivery. |
| Bezpieczne ponawianie | Każdy POST Operator wymaga klucza o długości 16–128 znaków (litery, cyfry, -, _ lub .). Ten sam klucz oraz dokładnie ten sam URL i treść zwracają zapisany wynik. Inne bajty zwracają 409. Sekrety/linki są pomijane przy odtworzeniu; w razie potrzeby rotuj lub wystaw je ponownie przez nową jawną operację. |
| Niepewne wyniki | operator_request_in_progress oznacza, że operacja trwa lub została przerwana przed zapisaniem potwierdzenia. Sprawdź zasób i audyt; nie wysyłaj w ciemno nowego klucza. Zakończone potwierdzenia są kompaktowane po 30 dniach; starych kluczy nadal nie można uruchomić ponownie. |
| Saldo i opłaty | Ciągi dziesiętne, najwyżej sześć miejsc po przecinku. starting_credit to jednorazowe lokalne przyznanie środków. Korekty wymagają kwoty ze znakiem, notatki i request_id oraz klucza ponowień HTTP. fee_bps=100 oznacza 1%; zmiany dotyczą przyszłych faktur. Przyznanie środków nie doładowuje własnego salda przedpłaconego instalacji. |
| Wstrzymywanie | enabled=false wyłącza hostowane konto i unieważnia sesje panelu. payments_paused=true zatrzymuje nowe faktury. Monitorowanie istniejących płatności trwa dalej. Tworzenie projektów/sklepów i automatyzacja zachowują politykę salda instalacji. |
| Nieudostępniane funkcje | Bez sekretów portfeli, podpisywania, wysyłania, zwrotów, trwałego usuwania, resetowania TOTP, zmian domen ani konfiguracji serwera. Zwykłe żądania faktur nadal używają klucza sprzedawcy i API Merchant. |
Webhooki cyklu życia Operator
| Zdarzenie | Dane |
|---|---|
| merchant.created / merchant.updated | merchant_id, enabled, payments_paused, fee_bps. |
| user.created / user.updated | merchant_id, user_id, enabled. Zdarzenie aktualizacji obejmuje zmiany e-maila, stanu włączenia i roli administratora. |
| invitation.accepted / password_reset.completed | merchant_id, user_id, invitation_id. |
| topup.settled / credit.balance_changed | merchant_id, ledger_id, kind, amount i balance. Przy uzgadnianiu odczytaj walutę salda sprzedawcy lub szczegóły księgi. |
Zdarzenia cyklu życia Operator są oddzielne od IPN faktur/webhooków sklepu. Subskrypcja należy do danych dostępu Operator, które ją utworzyły, z limitem 10 punktów końcowych na klucz. Kolejkowane są tylko przyszłe pasujące zdarzenia; zachowaną historię pobierz przez GET /events.
Treść zawiera event_id, event_type, merchant_id, occurred_at i data. Weryfikuj Wholly-Signature dla dokładnej surowej treści za pomocą jednorazowo ujawnianego signing_secret punktu końcowego: HMAC-SHA256(secret, timestamp + '.' + raw_body), nagłówek t=...,v1=.... Wymuszaj krótką tolerancję znacznika czasu.
Używaj ogólnego weryfikatora podpisów SDK, a nie parsera powiadomień faktur. Następnie zweryfikuj merchant_id i event_type, transakcyjnie zapisz/usuń duplikaty event_id i zwróć 2xx dopiero po trwałym przyjęciu. Wholly-Event-Id musi zgadzać się z podpisaną treścią. Nie traktuj niepodpisanych nagłówków jako danych biznesowych.
Dostarczanie odbywa się co najmniej raz, może być poza kolejnością i obejmuje do 8 prób. Odczytuj bieżące zasoby do uzgodnienia; occurred_at nie jest sekwencją monotoniczną. Przed dostarczeniem ponownie sprawdzane są zakres oraz ustawienia włączenia/ważności. Wyłączone subskrypcje wstrzymują już zakolejkowane operacje, ale podczas wyłączenia nie kolejkują nowych zdarzeń.
Zdarzenia i historia dostarczeń są przechowywane przez 30 dni. Polityka automatyzacji instalacji może wstrzymać dostarczanie. GET /webhooks/{id}/deliveries pokazuje wynik i niezmienną treść; publiczne API nie wymusza dostarczenia wygasłego zapisu.
{
"event_id": "55555555-5555-4555-8555-555555555555",
"event_type": "merchant.created",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"occurred_at": "2026-10-01T12:00:00Z",
"data": {
"merchant_id": "11111111-1111-4111-8111-111111111111",
"enabled": true,
"payments_paused": false,
"fee_bps": 300
}
}API platformy handlowej
Jedna płatność z chronionymi udziałami sprzedających i kontrolowanymi wypłatami.
Jedna faktura klienta, dokładne udziały sprzedających i kontrolowane wypłaty w tym samym aktywie. Włączane osobno dla projektu. Wersja 8.0.0 obsługuje sieć główną Bitcoin oraz skonfigurowane obsługiwane natywne monety EVM / standardowe tokeny ERC-20, a nie wszystkie sieci odbiorcze.
- Włącz Marketplace w projekcie, wybierz uczestniczące sklepy i pozostaw wypłaty wstrzymane podczas konfiguracji.
- Zarejestruj sprzedających i niezależnie zweryfikuj ich adresy wypłat. Utworzony adres docelowy oczekuje na zatwierdzenie; zatwierdzenie wymaga destinations.approve.
- Utwórz oddzielne dane dostępu Marketplace w Ustawienia → Dostęp API. Zwykłe dane dostępu Merchant, Operator i MCP nie mogą wydawać środków Marketplace.
- Utwórz fakturę z 1–100 dodatnimi przydziałami jako ciągi dziesiętne, których suma dokładnie równa się kwocie faktury. Każdy sprzedający potrzebuje zatwierdzonego adresu docelowego we wspólnej obsługiwanej sieci sklepu.
- Poczekaj na zweryfikowaną dostępność przydziałów. Przygotuj wypłatę, odczytaj niezmiennych odbiorców i limity kosztów, a następnie zatwierdź jej rewizję i dokładny plan_hash. Odpytuj wypłatę lub weryfikuj podpisane zdarzenia.
| Temat | Zasada |
|---|---|
| Powiernictwo | Środki klientów najpierw trafiają do portfeli kontrolowanych przez projekt. Właściciel platformy handlowej/serwera kontroluje te klucze do wypłacenia sprzedającym. Nie są to bezpośrednie płatności klient–sprzedający, escrow ani system logowania sprzedających. |
| Trzech sprzedających | Faktura na 300 USD z trzema udziałami po 100 USD i prowizją 4% przydziela każdemu sprzedającemu równowartość 96 USD w wycenionym krypto, zachowując równowartość 12 USD prowizji brutto. Plan gwarantuje atomowe jednostki krypto, nie przyszłą wartość w walucie fiducjarnej. |
| Opłaty | Istniejąca opłata za przetwarzanie jest naliczana raz od pierwotnej kwoty/waluty rozliczonej faktury. Przy skonfigurowanym 1% to 3 USD środków przedpłaconych, co pozostawia równowartość 9 USD prowizji przed opłatami blockchaina. Wypłaty sprzedającym nie tworzą dodatkowych opłat od sprzedaży klientom. |
| Przydział | Podział metodą największych reszt zachowuje każdą jednostkę atomową. Prowizja jest zaokrąglana w dół; kwota netto sprzedającego to reszta. Nadpisania przydziału, faktury, sprzedającego oraz ustawienia domyślne sklepu/projektu są zapisywane w niezmiennym stanie. Przy wypłacie nie stosuje się nowego kursu. |
| Chronione środki | Zwykłe wysyłanie, sweep, wpłaty na giełdy i automatyczne doładowania salda wykluczają adresy odbiorcze Marketplace. Opłaty sieciowe i gas tokenów wymagają oddzielnych wolnych monet natywnych. Buforowane wartości portfeli są orientacyjne; przed podpisaniem niezależnie sprawdzane jest bieżące pokrycie. |
| Ostateczność | Dowód wypłaty Marketplace wymaga dodatniego minimalnego progu blockchaina i dwóch niezależnych zgodnych dostawców, nawet jeśli strona płatności akceptuje zero potwierdzeń lub jeden skaner. Przerwy dostawców odraczają weryfikację płatności/wypłatę, a nie tworzenie faktur poprawnych pod innymi względami. |
| Wyjątki | Niedopłaty zaakceptowane przez zwykłą tolerancję płatności są wstrzymywane, nie przydziela się nadmiernych kwot. Uprzywilejowane zwolnienie może zatwierdzić dokładny mniejszy podział z pełnym pokryciem. Sama nadpłata nigdy nie blokuje wycenionego podziału sprzedających w BTC ani obsługiwanych metodach natywnych EVM/ERC-20. Nadwyżka pozostaje oddzielnie wstrzymana. Bitcoin zwraca chronioną resztę na adres faktury; oddzielne środki projektu pokrywają opłaty i ewentualne uzupełnienie do progu dust. Mieszane metody, spóźnione/niejednoznaczne/podlegające reorganizacji płatności i brak pokrycia wymagają sprawdzenia. |
| Zwroty | Przygotuj pełny zwrot w tym samym aktywie dla jednej jednoznacznej potwierdzonej metody odbioru, a następnie oddzielnie zatwierdź go jako wypłatę. Niewypłacone przydziały i prowizja zostają odwrócone. Po wypłaceniu wszystkim sprzedającym zasil główny adres portfela oddzielnie; nie ma odbierania już wypłaconych środków. Częściowe partie wypłat sprzedającym i zwroty w mieszanych aktywach wymagają najpierw uzgodnienia. Zwroty częściowych kwot i wypłaty prowizji nie są udostępnione w 8.0.0. |
| Ponowienia | Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik. |
| Rewizje | Modyfikowalne rekordy wymagają bieżącej rewizji. Zatwierdzenie/wznowienie wymaga też expected_plan_hash i confirm:true. Przygotowanie rezerwuje środki na 15 minut; zatwierdzenie daje godzinę. Wygasłe niepodpisane operacje bezpiecznie zwalniają rezerwacje. Podpisane/niepewne przelewy zachowują tożsamości i rezerwacje. |
| Automatyczne wypłaty | Domyślnie wyłączone. Polityki dla poszczególnych aktywów autoryzują zatwierdzone adresy docelowe, dodatnie minimum, limity kwoty głównej na wypłatę i w ruchomym okresie 24 godzin, limity opłat natywnych/gas, interwał i potwierdzenia. Zmiana/cofnięcie upoważnienia zatrzymuje niewysłane operacje; obserwacja trwa dalej. Limity obejmują plany zarezerwowane i niepewne. Polityki wstrzymane przez rozliczenia są ponownie planowane sprawiedliwie. Nieprawidłowa faktura jest wstrzymywana do sprawdzenia bez blokowania innych kwalifikujących się grup faktur. |
| Wstrzymanie i odzyskiwanie | Niskie saldo i zabezpieczenia przelewów nadal wstrzymują wydawanie środków. Monitorowanie i uzgadnianie księgi trwają dalej. Wznowienie sprawdza ten sam zachowany plan. Kanoniczne cofnięcie EVM potwierdzone przez dwóch niezależnych dostawców może zostać zastąpione po wyraźnym zatwierdzeniu, w pozostałym budżecie opłat; pierwotne hashe i opłaty pozostają zapisane. Nieznane wyniki lub rozbieżności dostarczenia tokenów pozostają wstrzymane. Twórz kopie całej bazy danych i kluczy; po przywróceniu uzgodnij wysłane hashe przed zezwoleniem na wypłaty. |
| Identyfikatory i stronicowanie | Używaj UUID projektu z Ustawień projektu i UUID sklepu z Sklepy → Podstawowe → Identyfikatory API. To API zwraca identyfikatory sprzedających/wypłat/aktywów. invoice_id to publiczny UUID faktury. Zasoby stronicowane zwracają data i pagination {page,per_page,total,pages}; wartości domyślne 1/25, maksymalnie 100 wierszy. Dokładne wartości pieniężne są ciągami znaków. |
| Zakres danych dostępu | Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych. |
Uprawnienia Marketplace
marketplace.read · vendors.write · destinations.write · destinations.approve · invoices.write · policies.write · commissions.override · payouts.write · payouts.approve · webhooks.write · reconciliation.write
Stany przydziałów
pending · held · available · reserved · paid · refunding · refunded · shortfall
Stany wypłat
awaiting_approval · queued · funding_gas · sending · confirming · partially_paid · paid · needs_attention · cancelled · expired
Zdarzenia platformy handlowej
Oddzielny sekret podpisujący Marketplace, korzystający z tych samych nagłówków podpisu Wholly i algorytmu weryfikacji HMAC surowej treści co wywołania zwrotne faktur. Weryfikuj znacznik czasu/podpis, usuwaj duplikaty event_id i szybko zwracaj 2xx. Dostarczanie odbywa się co najmniej raz, do ośmiu prób; historia pozwala ponownie dostarczyć to samo zdarzenie. Edycja punktu końcowego anuluje stare niewysłane dostarczenia zamiast przekierowywać dane klientów. Rozliczenie faktury nie oznacza zakończenia wypłat sprzedającym. Nigdy nie wysyłaj pieniędzy wyłącznie dlatego, że zewnętrzne wywołanie zwrotne tak nakazuje.
marketplace.invoice.createdmarketplace.allocations.availablemarketplace.allocations.heldmarketplace.payout.approvedmarketplace.payout.broadcastmarketplace.payout.confirmedmarketplace.payout.partialmarketplace.payout.failedmarketplace.payout.cancelledmarketplace.refund.preparedmarketplace.refund.confirmed
{
"event_id": "11111111-1111-4111-8111-111111111111",
"event_type": "marketplace.payout.confirmed",
"payload_version": 1,
"project_id": "YOUR_PROJECT_ID",
"occurred_at": "2026-10-06T12:00:00Z",
"data": {
"payout_id": "YOUR_PAYOUT_ID",
"asset_id": "YOUR_ASSET_ID",
"amount_atomic": "28800000",
"transactions": [
{
"transaction_id": "EXAMPLE_TRANSACTION_ID",
"explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
}
]
}
}Skonfiguruj płatności dla wielu sprzedających · Utwórz fakturę Marketplace
Błędy i limity
Obsługuj walidację, limity i ponowienia w przewidywalny sposób.
Sprawdź status HTTP i Content-Type przed parsowaniem odpowiedzi. W przypadku 429, przed ponowieniem odczekaj co najmniej czas określony przez Retry-After .
| Limit | Szczegóły |
|---|---|
| Częstotliwość żądań | Limit na dane dostępu: domyślnie 120 żądań na minutę UTC, konfigurowalne od 1 do 6000 w Ustawienia → API. Wszystkie uwierzytelnione odczyty i zapisy v1, w tym idempotentne ponowienia oraz błędy autoryzacji/walidacji po uwierzytelnieniu, współdzielą limit między domenami, projektami i procesami. Nieprawidłowe dane dostępu, trasy panelu i publiczna strona płatności go nie zużywają. |
| Nagłówki limitu zapytań | Uwierzytelnione odpowiedzi v1 zawierają X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (sekundy Unix na początku następnej minuty UTC). Nadmiarowe żądania zwracają JSON 429 rate_limit_exceeded i Retry-After w całkowitych sekundach. Odczekaj co najmniej tyle i dodaj losowy rozrzut ponowień. Stałe okna dopuszczają skoki na granicach minut; nie jest to gwarancja liczby żądań na sekundę. |
| Treść żądania Merchant | Maksymalnie 32 KiB w routerze aplikacji. Warstwa brzegowa może odrzucić zbyt duże żądanie przed utworzeniem odpowiedzi błędu JSON. |
| Lista faktur | limit domyślnie wynosi 50 i akceptuje 1–100; offset akceptuje 0–1 000 000. Wyszukiwanie ma najwyżej 100 znaków. Wyniki są od najnowszych i zawierają metadane total/has_more. |
| Metody sklepu | Najwyżej 64 wybrane aktywa na sklep, co wystarcza na wszystkie 30 natywnych blockchainów i ograniczony katalog zweryfikowanych tokenów. Tworzenie faktur nadal zależy od polityki projektu, możliwości skanera i gotowego portfela blockchaina z wykonaną kopią zapasową. |
| Wykrywanie tokenów | Limit kandydatów domyślnie wynosi 50 i akceptuje 1–100. Wyniki wykrywania nie są aktywami płatniczymi, dopóki weryfikacja on-chain się nie powiedzie. |
| Zarejestrowane tokeny projektu | Najwyżej 20 trwale zapisanych aktywów tokenowych na projekt. Już zarejestrowane aktywa można wykorzystać ponownie bez zajmowania kolejnego miejsca. |
| Idempotencja | Wymagana do tworzenia faktur. 1–128 widocznych znaków ASCII bez spacji; klucze są unikalne w obrębie sklepu, a odtworzenie musi używać pierwotnych danych dostępu i dokładnej surowej treści. |
| Metadane | Wyłącznie obiekt JSON, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia. |
| Wywołania zwrotne | Publiczny adres HTTPS do 2048 bajtów. Treści żądań powiadomień mają limit 256 KiB; zachowane treści zdarzeń faktur mają limit 64 KiB z ograniczoną historią płatności. |
| Materiały strony płatności | Odpowiedzi QR SVG są prywatne i no-store, ponieważ niedopłata zmienia dokładną pozostałą kwotę. Wersjonowane logo PNG jest publicznie buforowane przez rok i niezmienne. |
| Warstwa brzegowa API | Zarządzane żądania do upstream API mają 30-sekundowy limit czasu odczytu. Projektuj klientów z jawnymi limitami czasu krótszymi od budżetu czasowego ich zadania. |
| Błędy inne niż JSON | Nieprawidłowe pobieranie UUID/parametrów zapytania, niewłaściwe metody i kontrola długości 32 KiB mogą zwracać tekst frameworka lub puste odpowiedzi. Nieznane ścieżki /v1 obecnie zwracają 404 z HTML panelu; przed parsowaniem sprawdzaj status i Content-Type. |
Opis błędów
| HTTP | Kod błędu | Znaczenie |
|---|---|---|
| 400 | invalid_reconciliation_action | Nieprawidłowy status wyjątku, przyczyna, wyszukiwanie lub filtr strony historii. |
| 500 | reconciliation_unavailable | Nie udało się załadować kolejki wyjątków lub dowodów. Ponów odczyt ze zwiększanym odstępem. |
| 402 | billing_required | Każda nowa faktura wymaga zweryfikowanego sparowanego konta salda przedpłaconego i bieżącej autoryzacji. Niewystarczające środki przedpłacone nie blokują tworzenia ani płatności przychodzących: zamiast tego wstrzymują IPN, webhooki i Sweep, podczas gdy opłaty nadal narastają. Tworzenie pozostaje zablokowane dla kont zawieszonych, wygasłej/nieprawidłowej weryfikacji rozliczeń, niedostępnej usługi salda lub nieautoryzowanej podstawy faktury w walucie fiducjarnej. Opłaty wykorzystują pierwotną kwotę faktury w walucie fiducjarnej, nie otrzymane krypto, narzut kursowy, nadpłatę ani opłaty sieciowe. Ta kwota i niezależne przeliczenie są rejestrowane przed utworzeniem strony płatności. Istniejące monitorowanie i pobieranie faktur działają podczas awarii. Po doładowaniu zakolejkowane powiadomienia wznawiają się w zwykłym okresie przechowywania treści, a włączone reguły sweep są wznawiane. Sprawdź Ustawienia → Opłaty i ponów nieudane tworzenie z tym samym Idempotency-Key. |
| 400 | invalid_json | Nieprawidłowy JSON, nieznane pole lub treść niezgodna z udokumentowanym żądaniem. |
| 400 | idempotency_key_required | W żądaniu tworzenia faktury pominięto Idempotency-Key. |
| 400 | invalid_idempotency_key | Klucz jest pusty, przekracza 128 bajtów, nie jest ASCII, zawiera białe znaki lub bajt sterujący. |
| 400 | invalid_payment_request | Weryfikowane pole lub wybrana aktywna metoda nie przeszły kontroli. Odczytaj error.message i error.details.payment_methods (PaymentMethodIssue[]), aby poznać dokładną przeszkodę. SDK 2.4.0+ dodaje bezpieczne, praktyczne podsumowania wyjątków i pomocniki problemów; starsze SDK PHP udostępniają getApiMessage(). |
| 400 | invalid_invoice_status | Status listy nie mieści się w sześciu udokumentowanych stanach faktury. |
| 400 | invalid_callback_url | Obowiązujący cel IPN nie przeszedł weryfikacji HTTPS, publicznego adresu, DNS lub SSRF. |
| 400 | invalid_wallet_request | Nieprawidłowe dane wejściowe przygotowania portfela/adresu. |
| 400 | invalid_token_asset | Nieprawidłowy blockchain tokena, zapytanie o kandydatów, tożsamość CoinGecko, metadane katalogu lub kontrakt/mint. |
| 401 | authentication_required | Token bearer jest nieobecny, nieprawidłowy, wyłączony, wymieniony przez rotację lub nieznany. |
| 403 | source_ip_denied | Ograniczenie IP danych dostępu nie obejmuje dokładnego publicznego adresu źródłowego żądania. |
| 403 | source_ip_not_allowed | Ograniczenie źródłowego IP nazwy hosta wyklucza tego klienta. Administrator może zarządzać listami dozwolonych adresów aktywnych hostów w Ustawienia → System; obowiązują one dodatkowo obok ograniczeń IP danych dostępu. |
| 503 | source_access_unavailable | Weryfikacja dostępu do nazwy hosta jest tymczasowo niedostępna. Spróbuj później; przy błędzie ograniczenia blokują dostęp. |
| 403 / 409 / 500 | merchant_api_access_denied | Autoryzacja nie powiodła się: uprawnienia/zakres projektu mogą zwrócić 403, wyłączony projekt/sklep 409, a błąd backendu autoryzacji 500. Portfele odbiorcze Operator są zarezerwowane dla panelu Operator, nie dla danych dostępu API sprzedawcy ani MCP, nawet ze starszym jawnym przydziałem projektu. |
| 403 | project_access_denied | Transakcyjna ponowna kontrola przy tworzeniu wykryła, że dane dostępu nie mają już dostępu do projektu. |
| 404 | invoice_not_found | W autoryzowanym projekcie nie ma faktury o tym publicznym identyfikatorze lub strona płatności nie może jej ujawnić. |
| 404 | payment_resource_not_found | Projekt, sklep, aktywo lub portfel potrzebny podczas przygotowywania faktury już nie istnieje. |
| 404 | token_candidate_not_found | Projekt jest niedostępny lub token nie występuje już w bieżącym dopasowanym katalogu wykrywania. |
| 409 | idempotency_conflict | Klucz w zakresie sklepu już istnieje, a dane dostępu lub dokładne surowe bajty żądania różnią się. |
| 409 | store_unavailable | Projekt/sklep jest wyłączony lub niedostępny. |
| 409 | no_ready_payment_methods | Żadna metoda sklepu nie jest gotowa. Odczytaj error.message i error.details.payment_methods dla chain_slug, asset_ticker i reason_code. Kopia zapasowa/aktywacja portfela, zainstalowany adapter i wycena muszą być prawidłowe. Od 6.0.6 przerwy skanera, nieudane lub nieaktualne kontrole stanu i brak kworum dostawców nie blokują tworzenia. |
| 409 | payment_method_unavailable | Wybrana metoda stała się niedostępna podczas atomowej ponownej kontroli przy tworzeniu. |
| 409 | store_payment_method_not_selected | Zażądano nadpisania potwierdzeń sklepu dla aktywa, które nie jest obecnie wybrane w tym sklepie. |
| 409 | wallet_unavailable | Portfel płatniczy stał się niedostępny podczas atomowej ponownej kontroli przy tworzeniu. |
| 409 | ipn_secret_required | Istnieje obowiązujący URL IPN, ale sklep nie ma sekretu podpisującego IPN. |
| 409 | payment_resource_not_ready | Wymagane aktywo płatnicze lub portfel jest wyłączone, nie ma kopii zapasowej, oczekuje na dowód aktywacji współdzielonego konta, jest wyczerpane lub niegotowe z innej przyczyny. |
| 409 | account_activation_unverified | Nie udało się potwierdzić aktywacji konta XRP Ledger lub Stellar przez skonfigurowaną liczbę sprawnych punktów końcowych sieci głównej (domyślnie 2, opcjonalnie 1); zasil dokładnie to konto i ponów weryfikację. |
| 400 | invalid_monero_wallet_rpc | Nieprawidłowy punkt końcowy HTTPS, dokładny główny adres sieci głównej, etykieta lub kompletne dane uwierzytelniania Digest/Basic/nagłówkiem. |
| 404 | monero_wallet_rpc_not_found | Powiązanie wallet-RPC Monero w zakresie projektu nie istnieje. |
| 409 | monero_wallet_rpc_not_ready | Aktywo Monero, kworum dwóch demonów, niezmienne powiązanie lub jawne poświadczenie kopii zapasowej/trybu tylko do podglądu nie jest gotowe. |
| 409 | monero_wallet_rpc_unavailable | Tworzenie faktur wymaga aktywnego, zweryfikowanego i poświadczonego powiązania wallet-RPC Monero projektu z prawidłowymi danymi dostępu po stronie serwera. |
| 503 | lightning_unavailable | Jedyną gotową metodą sklepu jest Lightning i nie udało się zweryfikować portfela lub wyceny. Ponów próbę z tym samym kluczem idempotencji. Gdy istnieje inna gotowa metoda on-chain, niedostępna metoda Lightning jest zamiast tego pomijana. |
| 422 | monero_wallet_rpc_verification_failed | Kontrola dokładnego portfela, przypięcia HTTPS, synchronizacji, kworum demonów sieci głównej lub dowodu odmowy metod przez bramę nie powiodła się. |
| 503 | monero_wallet_rpc_failed | Zewnętrzny wallet-RPC tylko do obserwacji nie mógł bezpiecznie utworzyć i ponownie odczytać podadresu faktury; nie jest wymyślany żaden adres zastępczy. |
| 409 | token_chain_not_ready | Natywne aktywo blockchaina jest wyłączone, mapowanie wykrywania zmieniło się podczas weryfikacji lub projekt ma już aktualne maksimum 20 zarejestrowanych aktywów tokenowych. |
| 503 | dex_price_unavailable | Dostawca DEX jest niedostępny, zajęty, ograniczony limitem, zwrócił nieaktualną odpowiedź lub nieprawidłowe dane. Ponów po minucie; stała wycena pozostaje dostępna. |
| 422 | invalid_dex_price | Nieprawidłowa kombinacja trybu ceny lub wybrana pula nie może dostarczyć kwalifikującej ceny dla dokładnego kontraktu. Wybierz inną pulę lub stałą cenę w USD. |
| 422 | token_verification_failed | Żaden kwalifikujący się węzeł nie przeszedł weryfikacji tożsamości blockchaina, kodu kontraktu, liczby miejsc dziesiętnych, zapytania o saldo lub mint. |
| 422 | invalid_store_confirmation_policy | Nadpisanie sklepu jest niedostępne w tym trybie ostateczności, wykracza poza zwrócone granice właściwe dla blockchaina lub żąda nieobsługiwanej akceptacji bez potwierdzeń. |
| 409 | invoice_not_payable | Faktura strony płatności jest w stanie końcowym lub jej termin płatności upłynął. |
| 409 | invoice_payment_method_locked | Prawidłowa płatność wybrała już inne aktywo; kontynuuj z active_payment_method_id. |
| 409 | payment_method_not_payable | Wybrana metoda jest zakończona lub nie przyjmuje już kolejnej płatności. |
| 422 | payment_qr_unavailable | Żądanie płatności jest zbyt duże, aby zakodować je jako obraz QR SVG. |
| 503 | payment_rates_unavailable | Brak świeżej wiarygodnej wyceny dla jakiejkolwiek gotowej metody płatności. |
| 500 | authentication_unavailable | Uwierzytelnianie bearer nie mogło bezpiecznie odczytać lub zweryfikować zapisanych danych dostępu. |
| 429 | rate_limit_exceeded | Te dane dostępu wyczerpały limit bieżącej minuty UTC. Odczekaj co najmniej Retry-After sekund; ponów tworzenie faktury z tym samym kluczem idempotencji. |
| 500 | database_error / internal_error | Przejściowy błąd serwera; ponów bezpiecznie z tym samym kluczem idempotencji. |
Przegląd API
Wybierz punkt końcowy, aby zobaczyć jego pola, przykłady i odpowiedź.
Faktury
POSTUtwórz fakturę/v1/projects/{project_id}/stores/{store_id}/invoicesGETLista faktur/v1/projects/{project_id}/invoicesGETPobierz fakturę/v1/projects/{project_id}/invoices/{invoice_id}GETLista płatności faktury/v1/projects/{project_id}/invoices/{invoice_id}/paymentsMetody płatności
GETLista aktywów płatniczych projektu/v1/projects/{project_id}/payment-assetsPUTZaktualizuj politykę aktywów projektu/v1/projects/{project_id}/payment-assets/{asset_id}GETPrzeglądaj kandydatów na tokeny płatnicze/v1/projects/{project_id}/payment-token-candidatesPOSTZweryfikuj i zarejestruj token/v1/projects/{project_id}/payment-token-assetsGETZnajdź pule DEX niestandardowego tokena/v1/projects/{project_id}/payment-token-dex-poolsPOSTDodaj niestandardowy token lub zmień jego cenę/v1/projects/{project_id}/payment-token-assets/customGETLista metod płatności sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTZastąp metody płatności sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTUstaw politykę potwierdzeń sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policyPortfele
GETLista portfeli i sald projektu/v1/projects/{project_id}/walletsUzgadnianie płatności
GETLista wyjątków płatności/v1/projects/{project_id}/reconciliationGETOdczytaj dowody uzgodnienia/v1/projects/{project_id}/reconciliation/{invoice_id}API platformy handlowej
GETMożliwości/v1/marketplace/capabilitiesGETRaport platformy handlowej/v1/marketplace/overviewGETUstawienia projektu/v1/marketplace/settingsPOSTZapisz ustawienia projektu/v1/marketplace/settingsGETLista sprzedających/v1/marketplace/vendorsPOSTUtwórz sprzedającego/v1/marketplace/vendorsGETPobierz sprzedającego/v1/marketplace/vendors/{vendor_id}POSTZaktualizuj sprzedającego/v1/marketplace/vendors/{vendor_id}/updatePOSTZarchiwizuj sprzedającego/v1/marketplace/vendors/{vendor_id}/archiveGETAdresy docelowe sprzedającego/v1/marketplace/vendors/{vendor_id}/destinationsPOSTDodaj adres wypłaty/v1/marketplace/vendors/{vendor_id}/destinationsPOSTZatwierdź adres docelowy/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approvePOSTWyłącz adres docelowy/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableGETSalda sprzedającego/v1/marketplace/vendors/{vendor_id}/balancesGETFaktury platformy handlowej/v1/marketplace/invoicesPOSTUtwórz fakturę dla wielu sprzedających/v1/marketplace/invoicesGETFaktura i przydziały/v1/marketplace/invoices/{invoice_id}GETDowody płatności faktury/v1/marketplace/invoices/{invoice_id}/paymentsGETPrzydziały faktury/v1/marketplace/invoices/{invoice_id}/allocationsPOSTAnuluj nieopłaconą fakturę/v1/marketplace/invoices/{invoice_id}/cancelPOSTWstrzymaj przydziały/v1/marketplace/invoices/{invoice_id}/allocations/holdPOSTSprawdź i zwolnij przydziały/v1/marketplace/invoices/{invoice_id}/allocations/releasePOSTZmień powiązanie nieopłaconego adresu docelowego/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationPOSTPrzygotuj pełny zwrot/v1/marketplace/invoices/{invoice_id}/refundGETZnajdź przydziały wypłat/v1/marketplace/allocationsGETSalda księgi projektu/v1/marketplace/balancesGETNiezmienny dziennik/v1/marketplace/ledgerGETHistoria wypłat/v1/marketplace/payoutsPOSTPodgląd planu przydziałów/v1/marketplace/payouts/previewPOSTPrzygotuj wypłatę/v1/marketplace/payoutsGETSzczegóły wypłaty/v1/marketplace/payouts/{payout_id}POSTZatwierdź i wyślij/v1/marketplace/payouts/{payout_id}/approvePOSTSprawdź i wznów wypłatę/v1/marketplace/payouts/{payout_id}/resumePOSTAnuluj niepodpisane operacje/v1/marketplace/payouts/{payout_id}/cancelGETPolityki automatycznych wypłat/v1/marketplace/policiesPOSTAutoryzuj politykę wypłat/v1/marketplace/policiesGETWebhooki platformy handlowej/v1/marketplace/webhooksPOSTUtwórz webhook platformy handlowej/v1/marketplace/webhooksPOSTZaktualizuj webhook platformy handlowej/v1/marketplace/webhooks/{webhook_id}/updatePOSTWyłącz webhook platformy handlowej/v1/marketplace/webhooks/{webhook_id}/disableGETZdarzenia platformy handlowej/v1/marketplace/eventsGETOdczytaj zachowane zdarzenie/v1/marketplace/events/{event_id}GETHistoria dostarczania platformy handlowej/v1/marketplace/webhook-deliveriesGETSzczegóły dostarczenia/v1/marketplace/webhook-deliveries/{delivery_id}POSTDostarcz ponownie to samo zdarzenie/v1/marketplace/webhook-deliveries/{delivery_id}/resendAPI operatora
GETMożliwości/v1/operator/capabilitiesGETStan usługi/v1/operator/healthGETLista sprzedawców/v1/operator/merchantsPOSTUtwórz sprzedawcę/v1/operator/merchantsGETPobierz sprzedawcę/v1/operator/merchants/{merchant_id}POSTZaktualizuj sprzedawcę/v1/operator/merchants/{merchant_id}GETLista użytkowników/v1/operator/merchants/{merchant_id}/usersPOSTUtwórz użytkownika/v1/operator/merchants/{merchant_id}/usersGETPobierz użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}POSTZaktualizuj użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}POSTUstaw hasło użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordPOSTUnieważnij sesje użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsGETLista zaproszeń/v1/operator/merchants/{merchant_id}/invitationsPOSTUtwórz zaproszenie/v1/operator/merchants/{merchant_id}/invitationsGETPobierz zaproszenie/v1/operator/invitations/{invitation_id}POSTWyślij zaproszenie ponownie/v1/operator/invitations/{invitation_id}/resendPOSTUnieważnij zaproszenie/v1/operator/invitations/{invitation_id}/revokeGETPobierz saldo przedpłacone/v1/operator/merchants/{merchant_id}/creditsGETLista wpisów księgi salda przedpłaconego/v1/operator/merchants/{merchant_id}/credits/ledgerPOSTSkoryguj saldo przedpłacone/v1/operator/merchants/{merchant_id}/credits/adjustmentsGETLista doładowań/v1/operator/merchants/{merchant_id}/topupsPOSTUtwórz doładowanie/v1/operator/merchants/{merchant_id}/topupsGETPobierz doładowanie/v1/operator/merchants/{merchant_id}/topups/{topup_id}GETRaporty/v1/operator/reportsGETLista wpisów audytu/v1/operator/auditGETLista zdarzeń/v1/operator/eventsGETLista webhooków/v1/operator/webhooksPOSTUtwórz webhook/v1/operator/webhooksPOSTZaktualizuj webhook/v1/operator/webhooks/{webhook_id}POSTRotuj sekret webhooka/v1/operator/webhooks/{webhook_id}/rotateGETLista dostarczeń webhooków/v1/operator/webhooks/{webhook_id}/deliveriesGETLista projektów/v1/operator/merchants/{merchant_id}/projectsPOSTUtwórz projekt/v1/operator/merchants/{merchant_id}/projectsGETPobierz projekt/v1/operator/merchants/{merchant_id}/projects/{project_id}POSTZaktualizuj projekt/v1/operator/merchants/{merchant_id}/projects/{project_id}GETLista sklepów/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesPOSTUtwórz sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesGETPobierz sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}POSTZaktualizuj sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}GETPobierz wygląd sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearancePOSTZaktualizuj wygląd sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceGETLista aktywów płatniczych sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsPOSTZaktualizuj aktywa płatnicze sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsGETLista webhooków sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTUtwórz webhook sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTZaktualizuj webhook sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}GETLista faktur/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesGETPobierz fakturę/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}GETLista portfeli/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsGETLista adresów portfeli/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesGETLista danych dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentialsPOSTUtwórz dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentialsPOSTZaktualizuj dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}POSTRotuj dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotatePOSTUnieważnij dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokePOSTSprawdź token zaproszenia/v1/onboarding/invitations/checkPOSTPrzyjmij zaproszenie lub reset hasła/v1/onboarding/invitations/acceptStrona płatności
GETSzkielet strony płatności/GETHostowana strona płatności/invoice/{invoice_id}GETBezpieczne dane faktury dla strony płatności/checkout-api/invoices/{invoice_id}GETPodgląd strony płatności sklepu/invoice/preview/{project_id}GETDane podglądu płatności/checkout-api/previews/{project_id}GETObraz strony płatności sklepu/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngGETObraz podglądu sklepu/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngGETWersjonowane logo podglądu/checkout-api/previews/{project_id}/logo/{revision}/image.pngGETObraz QR płatności/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgGETWersjonowane logo strony płatności/checkout-api/invoices/{invoice_id}/logo/{revision}/image.pngUsługa
GETWykrywanie usług API/GETStan usługi/healthzGETMożliwości/v1/operator/capabilitiesTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/capabilities" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/capabilities", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/capabilities");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/capabilities",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"api_version": "v1",
"operator_version": "7.4.0",
"scopes": [
"health.read"
],
"all_merchants": false,
"merchant_ids": [
"11111111-1111-4111-8111-111111111111"
],
"onboarding": [
"direct",
"invitation"
],
"write_methods": [
"POST"
],
"idempotency_required": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga health.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETStan usługi/v1/operator/healthTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/health" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/health", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/health");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/health",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"version": "7.4.0",
"nodes": []
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga health.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista sprzedawców/v1/operator/merchantsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchants.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz sprzedawcę/v1/operator/merchantsOdczyt + zapis
Utwórz hostowanego sprzedawcę i pierwszego administratora atomowo, bezpośrednio z hasłem lub przez zaproszenie.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Example shop",
"email": "admin@example.test",
"onboarding": "direct",
"password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
"require_password_change": true,
"currency": "EUR",
"starting_credit": "0",
"external_id": "customer-1042"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Example shop",
"email": "admin@example.test",
"onboarding": "direct",
"password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
"require_password_change": true,
"currency": "EUR",
"starting_credit": "0",
"external_id": "customer-1042"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Example shop",
"email": "admin@example.test",
"onboarding": "direct",
"password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
"require_password_change": true,
"currency": "EUR",
"starting_credit": "0",
"external_id": "customer-1042"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Example shop",
"email": "admin@example.test",
"onboarding": "direct",
"password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
"require_password_change": true,
"currency": "EUR",
"starting_credit": "0",
"external_id": "customer-1042"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
onboardingdirect | invitationwymaganedirect wymaga password i nie wysyła e-maila z zaproszeniem. invitation pomija password.
passwordstring · direct only12–128 znaków (najwyżej 512 bajtów UTF-8); nigdy nie jest zwracane ani wysyłane e-mailem. Dla haseł tymczasowych używaj require_password_change.
require_password_changebooleanopcjonalneWymaga nowego hasła przy pierwszym logowaniu. Każde bezpośrednio utworzone konto musi potwierdzić powiernictwo hostowanego portfela.
currencyfiat codeopcjonalneWaluta konta przedpłaconego; domyślnie waluta regionalna, której później nie można zmienić.
fee_bpsintegeropcjonalne0–10000; 100 oznacza 1%. Przy pominięciu używa wartości domyślnej operatora. Wymaga fees.write.
starting_creditdecimal stringopcjonalneDokładne jednorazowe lokalne przyznanie środków. Niezerowa wartość wymaga credits.write. Nie uzupełnia salda instalacji operatora.
send_invitation_emailbooleanopcjonalneTylko zaproszenie. Wymaga skonfigurowanego SMTP; odpowiedź rozróżnia przyjęcie przez przekaźnik i utworzenie konta.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"merchant_id": "11111111-1111-4111-8111-111111111111",
"user_id": "22222222-2222-4222-8222-222222222222",
"merchant": {
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example shop",
"currency": "EUR",
"balance": "0"
},
"onboarding": "direct",
"access_link": null,
"email_delivery": {
"status": "not_requested"
},
"custody_acceptance_required": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchants.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Wymagany globalny dostęp do sprzedawców. Jawne nadpisania opłat wymagają też fees.write; niezerowe starting_credit wymaga credits.write. Wdrażanie przez zaproszenie wymaga też invitations.write. Bez automatycznego logowania, omijania Basic Auth ani wstecznego przyznawania środków przy ponowieniu.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz sprzedawcę/v1/operator/merchants/{merchant_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example shop",
"currency": "EUR",
"balance": "10",
"fee_bps": 300,
"enabled": true,
"payments_paused": false,
"external_id": "customer-1042"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchants.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj sprzedawcę/v1/operator/merchants/{merchant_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"payments_paused": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"payments_paused": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"payments_paused": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"payments_paused": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
namefieldsopcjonalneWyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.Szczegóły
Wyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.
enabledfieldsopcjonalneWyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.Szczegóły
Wyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.
payments_pausedfieldsopcjonalneWyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.Szczegóły
Wyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.
fee_bpsfieldsopcjonalneWyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.Szczegóły
Wyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.
external_idfieldsopcjonalneWyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.Szczegóły
Wyłączenie unieważnia sesje. payments_paused blokuje nowe faktury, nie skanowanie istniejących płatności. Edycja opłat wymaga fees.write i dotyczy przyszłych faktur; waluty konta nie można zmienić.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example shop",
"currency": "EUR",
"balance": "10",
"fee_bps": 300,
"enabled": true,
"payments_paused": false
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchants.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista użytkowników/v1/operator/merchants/{merchant_id}/usersTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga users.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz użytkownika/v1/operator/merchants/{merchant_id}/usersOdczyt + zapis
Dodaj administratora sprzedawcy lub użytkownika ograniczonego do wybranych projektów.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
require_password_changesame as merchant creationTworzenie zaproszenia wymaga dodatkowo invitations.write.
send_invitation_emailsame as merchant creationTworzenie zaproszenia wymaga dodatkowo invitations.write.
access_leveladmin | projectsopcjonalneadmin to wyłącznie administrator tego sprzedawcy, nigdy administrator instalacji/operatora.
project_ids[]UUID[]Tylko projekty należące do sprzedawcy. Wybór wymagany dla dostępu ograniczonego do projektów; nigdy między dzierżawcami.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"user": {
"id": "22222222-2222-4222-8222-222222222222",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"email": "admin@example.test",
"display_name": "Shop administrator",
"access_level": "admin",
"project_ids": [],
"enabled": true,
"password_setup_required": false,
"custody_acceptance_required": true,
"password_change_required": true
},
"user_id": "22222222-2222-4222-8222-222222222222",
"access_link": null,
"email_delivery": {
"status": "not_requested"
},
"merchant_id": "11111111-1111-4111-8111-111111111111"
}Pola odpowiedzi
userobject
user_idstringaccess_linkJSON | nullmerchant_idstringUwagi dotyczące użycia
- Wymaga users.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "22222222-2222-4222-8222-222222222222",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"email": "admin@example.test",
"display_name": "Shop administrator",
"access_level": "admin",
"project_ids": [],
"enabled": true,
"password_setup_required": false,
"custody_acceptance_required": true,
"password_change_required": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga users.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"display_name": "Store manager"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"display_name": "Store manager"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"display_name": "Store manager"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"display_name": "Store manager"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
emailfieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
display_namefieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
enabledfieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
access_levelfieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
project_idsfieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
default_timezonefieldsopcjonalneAktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "22222222-2222-4222-8222-222222222222",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"email": "admin@example.test",
"display_name": "Shop administrator",
"access_level": "admin",
"project_ids": [],
"enabled": true,
"password_setup_required": false,
"custody_acceptance_required": true,
"password_change_required": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga users.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUstaw hasło użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordOdczyt + zapis
Ustaw hasło hostowanego konta i unieważnij sesje. Istniejące TOTP zostaje zachowane.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"user_id": "11111111-1111-4111-8111-111111111111",
"sessions_revoked": true,
"totp_preserved": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga users.security; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUnieważnij sesje użytkownika/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"user_id": "11111111-1111-4111-8111-111111111111",
"sessions_revoked": true,
"totp_preserved": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga users.security; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista zaproszeń/v1/operator/merchants/{merchant_id}/invitationsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invitations.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz zaproszenie/v1/operator/merchants/{merchant_id}/invitationsOdczyt + zapis
Utwórz lub zastąp jednorazowy link zaproszenia lub resetu hasła.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
user_idUUID, booleanWystaw/zastąp jednorazowy link dla istniejącego konta. Aktywowani użytkownicy otrzymują link resetu ważny godzinę i wymagają users.security.
send_emailUUID, booleanWystaw/zastąp jednorazowy link dla istniejącego konta. Aktywowani użytkownicy otrzymują link resetu ważny godzinę i wymagają users.security.
new user fieldsalternative to user_idUżyj email, display_name, access_level i project_ids, aby utworzyć zapraszanego użytkownika; wymaga users.write.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"user_id": "22222222-2222-4222-8222-222222222222",
"email": "admin@example.test",
"kind": "invitation",
"expires_at": "2026-10-03T12:00:00Z",
"url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invitations.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz zaproszenie/v1/operator/invitations/{invitation_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
invitation_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"user_id": "22222222-2222-4222-8222-222222222222",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"kind": "invitation",
"status": "pending",
"created_at": "2026-10-01T12:00:00Z",
"expires_at": "2026-10-03T12:00:00Z"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invitations.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTWyślij zaproszenie ponownie/v1/operator/invitations/{invitation_id}/resendOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
invitation_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"send_email": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"send_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"send_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"send_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
send_emailbooleanopcjonalneZastępuje poprzedni token, nigdy nie dodaje środków. Zwraca nowo wygenerowany link jeden raz. Już aktywowane konto wymaga users.security.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"user_id": "22222222-2222-4222-8222-222222222222",
"email": "admin@example.test",
"kind": "invitation",
"expires_at": "2026-10-03T12:00:00Z",
"url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invitations.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUnieważnij zaproszenie/v1/operator/invitations/{invitation_id}/revokeOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
invitation_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"revoked": true,
"invitation_id": "44444444-4444-4444-8444-444444444444"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invitations.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz saldo przedpłacone/v1/operator/merchants/{merchant_id}/creditsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example shop",
"currency": "EUR",
"balance": "10",
"fee_bps": 300,
"enabled": true,
"payments_paused": false,
"external_id": "customer-1042"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga credits.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista wpisów księgi salda przedpłaconego/v1/operator/merchants/{merchant_id}/credits/ledgerTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
qopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga credits.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTSkoryguj saldo przedpłacone/v1/operator/merchants/{merchant_id}/credits/adjustmentsOdczyt + zapis
Dopisz uzasadnione przyznanie środków lub korektę do księgi salda przedpłaconego tego sprzedawcy.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
amountsigned decimal stringwymaganeDodatnie przyznanie lub ujemna korekta, do sześciu miejsc dziesiętnych w walucie salda sprzedawcy. Nie jest to przelew on-chain.
request_idUUIDwymaganeZapisz trwale wraz z kwotą i uzasadnieniem, dodatkowo obok HTTP Idempotency-Key.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"balance": "25"
}Pola odpowiedzi
balancestringUwagi dotyczące użycia
- Wymaga credits.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista doładowań/v1/operator/merchants/{merchant_id}/topupsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga topups.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz doładowanie/v1/operator/merchants/{merchant_id}/topupsOdczyt + zapis
Utwórz stronę płatności za środki przedpłacone; nigdy nie oznaczaj jej ręcznie jako opłaconej.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"invoice_id": "33333333-3333-4333-8333-333333333333",
"checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga topups.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz doładowanie/v1/operator/merchants/{merchant_id}/topups/{topup_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"merchant_id": "11111111-1111-4111-8111-111111111111",
"invoice_id": "33333333-3333-4333-8333-333333333333",
"amount": "25",
"currency": "EUR",
"status": "pending",
"invoice_status": "new",
"checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga topups.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETRaporty/v1/operator/reportsTylko odczyt
Odczytaj przegląd finansowy Operator. Wymaga dostępu do wszystkich hostowanych sprzedawców.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry zapytania
periodopcjonalneFiltry finansowe. period domyślnie ma wartość last30; użyj custom z start/end w formacie YYYY-MM-DD. Tylko dane dostępu obejmujące wszystkich sprzedawców.
startopcjonalneFiltry finansowe. period domyślnie ma wartość last30; użyj custom z start/end w formacie YYYY-MM-DD. Tylko dane dostępu obejmujące wszystkich sprzedawców.
endopcjonalneFiltry finansowe. period domyślnie ma wartość last30; użyj custom z start/end w formacie YYYY-MM-DD. Tylko dane dostępu obejmujące wszystkich sprzedawców.
currencyopcjonalneFiltry finansowe. period domyślnie ma wartość last30; użyj custom z start/end w formacie YYYY-MM-DD. Tylko dane dostępu obejmujące wszystkich sprzedawców.
merchant_idopcjonalneFiltry finansowe. period domyślnie ma wartość last30; użyj custom z start/end w formacie YYYY-MM-DD. Tylko dane dostępu obejmujące wszystkich sprzedawców.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/reports" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/reports", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/reports");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/reports",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"summary": {
"fees": "10",
"costs": "3",
"margin": "7",
"credits": "25",
"pending": 0,
"missing_rates": 0
},
"merchants": [],
"filters": {
"period": "last30",
"currency": "EUR",
"timezone": "UTC"
},
"basis": "first_settlement_latest_net_fees"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga reports.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Wiersze, koszty i liczniki własnej działalności są wykluczane przed obliczeniem sum. Filtr merchant_id własnej działalności zwraca 404. Raporty używają strefy czasowej instalacji.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista wpisów audytu/v1/operator/auditTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry zapytania
merchant_idopcjonalneFiltruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.
searchopcjonalneFiltruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/audit" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/audit", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/audit");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/audit",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga audit.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista zdarzeń/v1/operator/eventsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry zapytania
merchant_idopcjonalneFiltruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.
event_typeopcjonalneFiltruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/events" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/events", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/events");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/events",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista webhooków/v1/operator/webhooksTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/webhooks" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/webhooks", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/webhooks",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz webhook/v1/operator/webhooksOdczyt + zapis
Subskrybuj przyszłe zdarzenia cyklu życia Operator. To nie webhook płatności sklepu.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/webhooks" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
urlpublic HTTPS URLwymaganeBez danych dostępu, prywatnych IP ani przekierowań. DNS/IP są ponownie sprawdzane przy dostarczaniu.
events[]string[]wymaganeWybierz zdarzenia cyklu życia z przewodnika Operator, nie wywołania zwrotne faktur.
merchant_ids[]UUID[]opcjonalnePusta wartość oznacza wszystkich sprzedawców dozwolonych dla tych danych dostępu. Bieżące ograniczenia zakresu są ponownie sprawdzane.
enabledbooleanopcjonalneWstrzymane punkty końcowe zachowują zakolejkowane dostarczenia; ponowne włączenie wznawia ważne zachowane operacje.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"id": "11111111-1111-4111-8111-111111111111",
"signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga webhooks.write + events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj webhook/v1/operator/webhooks/{webhook_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
webhook_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
urlpublic HTTPS URLwymaganeBez danych dostępu, prywatnych IP ani przekierowań. DNS/IP są ponownie sprawdzane przy dostarczaniu.
events[]string[]wymaganeWybierz zdarzenia cyklu życia z przewodnika Operator, nie wywołania zwrotne faktur.
merchant_ids[]UUID[]opcjonalnePusta wartość oznacza wszystkich sprzedawców dozwolonych dla tych danych dostępu. Bieżące ograniczenia zakresu są ponownie sprawdzane.
enabledbooleanopcjonalneWstrzymane punkty końcowe zachowują zakolejkowane dostarczenia; ponowne włączenie wznawia ważne zachowane operacje.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"signing_secret": null
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga webhooks.write + events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTRotuj sekret webhooka/v1/operator/webhooks/{webhook_id}/rotateOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
webhook_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "11111111-1111-4111-8111-111111111111",
"signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga webhooks.write + events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista dostarczeń webhooków/v1/operator/webhooks/{webhook_id}/deliveriesTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
webhook_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga events.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista projektów/v1/operator/merchants/{merchant_id}/projectsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz projekt/v1/operator/merchants/{merchant_id}/projectsOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
namestringswymaganeNazwa i unikalny stabilny identyfikator projektu. Tworzy lokalne portfele przy użyciu istniejącej inicjalizacji projektu, nigdy nie przenosi środków.
slugstringswymaganeNazwa i unikalny stabilny identyfikator projektu. Tworzy lokalne portfele przy użyciu istniejącej inicjalizacji projektu, nigdy nie przenosi środków.
enabledopcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
reporting_timezoneopcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
checkout_titleopcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
checkout_descriptionopcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
checkout_themeopcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
checkout_accent_coloropcjonalneenabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"id": "33333333-3333-4333-8333-333333333333",
"slug": "example-shop",
"name": "Example shop",
"enabled": false,
"reporting_currency": "EUR",
"reporting_timezone": "Europe/Berlin",
"stores": []
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz projekt/v1/operator/merchants/{merchant_id}/projects/{project_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "33333333-3333-4333-8333-333333333333",
"slug": "example-shop",
"name": "Example shop",
"enabled": false,
"reporting_currency": "EUR",
"reporting_timezone": "Europe/Berlin",
"stores": []
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj projekt/v1/operator/merchants/{merchant_id}/projects/{project_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"enabled": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
nameopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
enabledopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
reporting_currencyopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
reporting_timezoneopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
checkout_titleopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
checkout_descriptionopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
checkout_themeopcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
checkout_accent_coloropcjonalneCzęściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "33333333-3333-4333-8333-333333333333",
"slug": "example-shop",
"name": "Example shop",
"enabled": false,
"reporting_currency": "EUR",
"reporting_timezone": "Europe/Berlin",
"stores": []
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista sklepów/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
default_currencyopcjonalneDla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.
invoice_expiry_minutesopcjonalneDla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.
exchange_rate_spread_percentopcjonalneDla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.
underpayment_tolerance_percentopcjonalneDla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.
enabledopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
is_defaultopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
allow_zero_amount_invoicesopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
allow_underpaymentsopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
allow_overpaymentsopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
allowed_chain_slugsopcjonalneKonfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.
ipn_enabledopcjonalneAdresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.
default_ipn_urlopcjonalneAdresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.
default_redirect_urlopcjonalneAdresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.
default_cancel_urlopcjonalneAdresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.
redirect_automaticallyopcjonalneAdresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.
checkout_languageopcjonalneUżywaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.
embed_enabledopcjonalneUżywaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.
allowed_embed_originsopcjonalneUżywaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.
domainsopcjonalneUżywaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "33333333-3333-4333-8333-333333333333",
"slug": "online",
"name": "Online shop",
"enabled": false,
"default_currency": "EUR",
"invoice_expiry_minutes": 60
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "33333333-3333-4333-8333-333333333333",
"slug": "online",
"name": "Online shop",
"enabled": false,
"default_currency": "EUR",
"invoice_expiry_minutes": 60
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj sklep/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"enabled": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "33333333-3333-4333-8333-333333333333",
"slug": "online",
"name": "Online shop",
"enabled": false,
"default_currency": "EUR",
"invoice_expiry_minutes": 60
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz wygląd sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"revision": 1,
"settings": {
"inherit_default_store": true
},
"effective": {
"title": "Pay securely"
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj wygląd sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceOdczyt + zapis
Zapisz zweryfikowany projekt wyglądu sklepu chroniony rewizją.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
revisionintegerwymaganeNajpierw odczytaj bieżącą rewizję przez GET. Nieaktualna rewizja kończy się błędem bez nadpisywania pracy innego edytora.
settingsobjectwymagane
Zweryfikowany wygląd strony płatności, w tym inherit_default_store, identyfikacja wizualna, wstęp/zakończenie, rozmiary czcionek i widoczność. Bez dowolnego HTML/JavaScript. Przesyłanie bajtów obrazu jest dostępne tylko w panelu.Szczegóły
Zweryfikowany wygląd strony płatności, w tym inherit_default_store, identyfikacja wizualna, wstęp/zakończenie, rozmiary czcionek i widoczność. Bez dowolnego HTML/JavaScript. Przesyłanie bajtów obrazu jest dostępne tylko w panelu.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
},
"revision": 2
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista aktywów płatniczych sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": []
}Pola odpowiedzi
data[]arrayUwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj aktywa płatnicze sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
assets[]object[]wymagane
Pełne zastąpienie metod on-chain: UUID asset_id i display_order. [] usuwa akceptowane aktywa on-chain. Tylko zweryfikowane aktywa projektu; nie konfiguruje Lightning.Szczegóły
Pełne zastąpienie metod on-chain: UUID asset_id i display_order. [] usuwa akceptowane aktywa on-chain. Tylko zweryfikowane aktywa projektu; nie konfiguruje Lightning.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": []
}Pola odpowiedzi
data[]arrayUwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista webhooków sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz webhook sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
namestrings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
urlstrings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
event_types[]strings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
enabledbooleansopcjonalneTworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.
automatic_redeliverybooleansopcjonalneTworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"signing_secret": "EXAMPLE_ONLY_SAVE_ONCE",
"endpoint": {
"id": "44444444-4444-4444-8444-444444444444",
"name": "Orders",
"enabled": true
},
"secret_visible_once": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj webhook sklepu/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
store_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
webhook_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
namestrings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
urlstrings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
event_types[]strings / arraywymaganePubliczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.
enabledbooleansopcjonalneTworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.
automatic_redeliverybooleansopcjonalneTworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "44444444-4444-4444-8444-444444444444",
"name": "Orders",
"enabled": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga projects.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista faktur/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Parametry zapytania
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"limit": 25,
"offset": 0,
"total": 0,
"has_more": false
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga reports.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETPobierz fakturę/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}Tylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
invoice_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"invoice_id": "44444444-4444-4444-8444-444444444444",
"project_id": "33333333-3333-4333-8333-333333333333",
"amount": "25",
"currency": "EUR",
"status": "new",
"metadata": {},
"payment_intents": []
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga reports.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
- invoice_id to publiczny identyfikator faktury zwracany przy tworzeniu i w wywołaniach zwrotnych, nie wewnętrzne id.
Błędy
GETLista portfeli/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsTylko odczyt
Odczytuj buforowane publiczne salda portfeli, nigdy klucze prywatne ani frazy odzyskiwania.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga reports.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Salda są buforowanymi obserwacjami z polami aktualności, nie gwarancją dostępnego do wydania salda. Wysyłanie i eksport kluczy nie są dostępne przez to API.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista adresów portfeli/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
project_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
wallet_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
limitopcjonalneLimit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.Szczegóły
Limit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.
beforeopcjonalneLimit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.Szczegóły
Limit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.
searchopcjonalneLimit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.Szczegóły
Limit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.
has_balanceopcjonalneLimit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.Szczegóły
Limit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.
hide_small_balancesopcjonalneLimit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.Szczegóły
Limit 1–50, domyślnie 25. Przekaż next_cursor jako before dla następnej strony. Pomiń before dla strony 1. has_balance=false i hide_small_balances=false uwzględniają puste/małe salda.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"wallet": {
"id": "22222222-2222-4222-8222-222222222222",
"chain_slug": "ethereum"
},
"items": [],
"total": 0,
"total_pages": 1,
"next_cursor": null,
"reporting_currency": "EUR",
"has_balance": true,
"hide_small_balances": true,
"small_balance_threshold": {
"amount": "0.20",
"currency": "EUR"
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga reports.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETLista danych dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentialsTylko odczyt
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Parametry zapytania
pageopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
searchopcjonalneNumer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.Szczegóły
Numer strony od 1, 25 elementów na stronę. Wyszukiwanie jest obsługiwane dla sprzedawców, użytkowników, projektów, sklepów, portfeli, danych dostępu i webhooków; natywne listy zdarzeń używają własnych filtrów.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchant_credentials.read; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUtwórz dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentialsOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
merchant_idUUIDwymaganeKanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
access_levelread_only | read_writeopcjonalneOdczyt/zapis włącza istniejący kontrakt API sprzedawcy.
project_ids[]UUID[]Tylko projekty należące do wybranego sprzedawcy; pusta lista podlega istniejącej polityce wszystkich projektów sprzedawcy.
enabledopcjonalneIstniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.
ip_restriction_enabledopcjonalneIstniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.
allowed_ips[]opcjonalneIstniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.
requests_per_minuteopcjonalneIstniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.
Odpowiedź 201 or 200 application/json
Przykładowa odpowiedź
{
"credential": {
"id": "22222222-2222-4222-8222-222222222222",
"name": "Checkout",
"access_level": "read_only",
"project_ids": [
"33333333-3333-4333-8333-333333333333"
],
"enabled": true
},
"token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchant_credentials.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTZaktualizuj dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}Odczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
namefieldswymaganeWyślij pełną bieżącą konfigurację danych dostępu ze zmianami. project_ids domyślnie wynosi []; requests_per_minute domyślnie odpowiada limitowi API sprzedawcy.
access_levelfieldswymaganeWyślij pełną bieżącą konfigurację danych dostępu ze zmianami. project_ids domyślnie wynosi []; requests_per_minute domyślnie odpowiada limitowi API sprzedawcy.
enabledfieldswymaganeWyślij pełną bieżącą konfigurację danych dostępu ze zmianami. project_ids domyślnie wynosi []; requests_per_minute domyślnie odpowiada limitowi API sprzedawcy.
ip_restriction_enabledfieldswymaganeWyślij pełną bieżącą konfigurację danych dostępu ze zmianami. project_ids domyślnie wynosi []; requests_per_minute domyślnie odpowiada limitowi API sprzedawcy.
allowed_ips[]fieldswymaganeWyślij pełną bieżącą konfigurację danych dostępu ze zmianami. project_ids domyślnie wynosi []; requests_per_minute domyślnie odpowiada limitowi API sprzedawcy.
project_ids[]arrayOdpowiedź 200 application/json
Przykładowa odpowiedź
{
"id": "22222222-2222-4222-8222-222222222222",
"name": "Checkout",
"access_level": "read_only",
"project_ids": [
"33333333-3333-4333-8333-333333333333"
],
"enabled": true
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchant_credentials.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTRotuj dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotateOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"credential": {
"id": "22222222-2222-4222-8222-222222222222",
"name": "Checkout",
"access_level": "read_only",
"project_ids": [
"33333333-3333-4333-8333-333333333333"
],
"enabled": true
},
"token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga merchant_credentials.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTUnieważnij dane dostępu sprzedawcy/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokeOdczyt + zapis
Zarządzaj wskazanym zasobem hostowanego sprzedawcy lub sprawdzaj go przy użyciu oddzielnych danych dostępu Operator.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_OPERATOR_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"revoked": true
}Pola odpowiedzi
revokedbooleanUwagi dotyczące użycia
- Wymaga merchant_credentials.write; tylko dozwoleni hostowani sprzedawcy. Klucze Operator nie mają dostępu do przestrzeni własnej działalności właściciela.
- Przed wysłaniem zapisz trwale unikalny Idempotency-Key i dokładną treść. Ponowienia nigdy nie powtarzają zatwierdzonej operacji. Pola sekretów są pomijane przy odtworzeniu; jeśli odpowiedź z sekretem zaginęła, sprawdź utworzony zasób i jawnie rotuj/wystaw go ponownie. 409 operator_request_in_progress może oznaczać przerwane żądanie o nieznanym wyniku: sprawdź zasób/audyt; nie ponawiaj w ciemno z nowym kluczem.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTSprawdź token zaproszenia/v1/onboarding/invitations/checkPubliczne
Wdrażanie konta tylko przez token. Nie przyjmuje klucza Operator ani nie loguje automatycznie. Logowanie do panelu nadal wymaga Basic Auth witryny i istniejącego TOTP.
Uwierzytelnianie i nagłówki
Publiczne
Żądanie
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/onboarding/invitations/check" \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}'// Node.js 18+ · run on your server, never in browser code.
const body = `{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}`;
const response = await fetch("https://api.example.com/v1/onboarding/invitations/check", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$body = <<<'JSON'
{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}
JSON;
$ch = curl_init("https://api.example.com/v1/onboarding/invitations/check");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
body = """{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/onboarding/invitations/check",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"kind": "invitation",
"email": "admin@example.test",
"merchant_name": "Example shop"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Zaproszenie ważne 48 godzin; link resetu hasła ważny godzinę. Jednorazowe hashowane tokeny. Ponowne wystawienie unieważnia wcześniejszy link. Przyjęcie zachowuje TOTP i unieważnia stare sesje.
- Bez automatycznych ponowień. Jeśli przyjęcie przekroczy limit czasu, sprawdź stan linku i spróbuj się zalogować; nie zakładaj niepowodzenia. Limitowane według zaobserwowanego źródłowego IP. Odbiorca musi sam potwierdzić powiernictwo.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
POSTPrzyjmij zaproszenie lub reset hasła/v1/onboarding/invitations/acceptPubliczne
Wdrażanie konta tylko przez token. Nie przyjmuje klucza Operator ani nie loguje automatycznie. Logowanie do panelu nadal wymaga Basic Auth witryny i istniejącego TOTP.
Uwierzytelnianie i nagłówki
Publiczne
Żądanie
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/onboarding/invitations/accept" \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}'// Node.js 18+ · run on your server, never in browser code.
const body = `{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}`;
const response = await fetch("https://api.example.com/v1/onboarding/invitations/accept", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$body = <<<'JSON'
{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/onboarding/invitations/accept");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
body = """{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/onboarding/invitations/accept",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"password_set": true
}Pola odpowiedzi
password_setbooleanUwagi dotyczące użycia
- Zaproszenie ważne 48 godzin; link resetu hasła ważny godzinę. Jednorazowe hashowane tokeny. Ponowne wystawienie unieważnia wcześniejszy link. Przyjęcie zachowuje TOTP i unieważnia stare sesje.
- Bez automatycznych ponowień. Jeśli przyjęcie przekroczy limit czasu, sprawdź stan linku i spróbuj się zalogować; nie zakładaj niepowodzenia. Limitowane według zaobserwowanego źródłowego IP. Odbiorca musi sam potwierdzić powiernictwo.
- Przykładowe odpowiedzi pokazują wybrane pola. Traktuj dodatkowe pola odpowiedzi jako rozszerzenia.
Błędy
GETMożliwości/v1/marketplace/capabilitiesTylko odczyt
Uczestniczące sklepy, skonfigurowane aktywa, obsługiwane kanały wypłat, natywne aktywo opłat i przyczyny gotowości. Tymczasowa dostępność skanera nie rozszerza zbioru dozwolonych aktywów.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETRaport platformy handlowej/v1/marketplace/overviewTylko odczyt
Filtruj store_id, asset_id, from i to (włącznie, YYYY-MM-DD, UTC; domyślnie ostatnie 30 dni; do dziesięciu lat). Dokładne salda kont na datę końcową i zmiany w okresie. Bez szacunkowych zarobków w walucie fiducjarnej. Filtr sklepu wyklucza opłaty całego projektu bez faktury.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETUstawienia projektu/v1/marketplace/settingsTylko odczyt
Zwraca enabled, payouts_paused, commission_percent, revision i uczestniczące sklepy.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZapisz ustawienia projektu/v1/marketplace/settingsOdczyt + zapis
Zastąp wybór uczestniczących sklepów. revision 0 inicjalizuje ustawienia; późniejsze zmiany wymagają zwróconej rewizji. Prowizja jest procentem dziesiętnym, 0–100 z najwyżej dwoma miejscami po przecinku.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | policies.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/settings" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 0,
"enabled": true,
"payouts_paused": true,
"commission_percent": "4",
"stores": [
{
"store_id": "YOUR_STORE_ID",
"enabled": true,
"commission_percent": null
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 0,
"enabled": true,
"payouts_paused": true,
"commission_percent": "4",
"stores": [
{
"store_id": "YOUR_STORE_ID",
"enabled": true,
"commission_percent": null
}
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/settings", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 0,
"enabled": true,
"payouts_paused": true,
"commission_percent": "4",
"stores": [
{
"store_id": "YOUR_STORE_ID",
"enabled": true,
"commission_percent": null
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/settings");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 0,
"enabled": true,
"payouts_paused": true,
"commission_percent": "4",
"stores": [
{
"store_id": "YOUR_STORE_ID",
"enabled": true,
"commission_percent": null
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/settings",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga policies.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETLista sprzedających/v1/marketplace/vendorsTylko odczyt
Stronicowana lista sprzedających. Szukaj przez q według nazwy, zewnętrznego identyfikatora lub e-maila; status active, suspended lub archived.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTUtwórz sprzedającego/v1/marketplace/vendorsOdczyt + zapis
Nazwa wymagana (160 znaków); external_id opcjonalny i unikalny w projekcie (128); email opcjonalny (254); description do 2000. commission_percent null dziedziczy wartość sklepu. Nadpisanie inne niż null wymaga też commissions.override. Sprzedający nie są hostowanymi kontami sprzedawców.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | vendors.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga vendors.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETPobierz sprzedającego/v1/marketplace/vendors/{vendor_id}Tylko odczyt
Zwróć jednego sprzedającego, rewizję i nadpisanie prowizji.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZaktualizuj sprzedającego/v1/marketplace/vendors/{vendor_id}/updateOdczyt + zapis
Zaktualizuj dane sprzedającego; status active lub suspended. Zmiana lub usunięcie commission_percent wymaga też commissions.override; niezmienione wartości wymagają tylko vendors.write. Przywrócenie zarchiwizowanego sprzedającego wymaga też reconciliation.write. Zmiany finansowe w panelu wymagają ponownego uwierzytelnienia konta. Istniejące przydziały zachowują pierwotną prowizję i adresy docelowe.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | vendors.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga vendors.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZarchiwizuj sprzedającego/v1/marketplace/vendors/{vendor_id}/archiveOdczyt + zapis
Archiwizuj dopiero po uregulowaniu zobowiązań z nieopłaconych i otwartych faktur; w przeciwnym razie zwraca 409 vendor_has_obligations. Historia zostaje zachowana. Tymczasowo użyj statusu suspended lub przywróć wcześniej zarchiwizowanego sprzedającego trasą aktualizacji z reconciliation.write.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | vendors.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga vendors.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETAdresy docelowe sprzedającego/v1/marketplace/vendors/{vendor_id}/destinationsTylko odczyt
Wersjonowane adresy docelowe i stany pending/approved/disabled. Zatwierdzenie nie dowodzi własności.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTDodaj adres wypłaty/v1/marketplace/vendors/{vendor_id}/destinationsOdczyt + zapis
Zarejestruj prawidłowy adres sieci głównej BTC lub obsługiwanego EVM, oczekujący na zatwierdzenie. Adresy należące do projektu, niewłaściwa sieć i zerowe adresy EVM są odrzucane.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | destinations.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga destinations.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZatwierdź adres docelowy/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approveOdczyt + zapis
Najpierw niezależnie zweryfikuj własność. Najpierw wyłącz istniejący zatwierdzony adres docelowy tego sprzedającego w tej sieci; stare zapisane stany nie są przekierowywane.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | destinations.approve |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga destinations.approve. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTWyłącz adres docelowy/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableOdczyt + zapis
Zatrzymaj nowe/niewysłane operacje korzystające z tej wersji. Podpisanej transakcji nie można unieważnić.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | destinations.approve |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga destinations.approve. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETSalda sprzedającego/v1/marketplace/vendors/{vendor_id}/balancesTylko odczyt
Dokładne zachowane kwoty księgi pogrupowane według niezmiennej tożsamości aktywa i typu konta; nie bieżące dostępne do wydania salda portfeli.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETFaktury platformy handlowej/v1/marketplace/invoicesTylko odczyt
Stronicowane faktury; q przeszukuje zamówienie, e-mail, opis, metadane i UUID faktury. Filtruj store_id, vendor_id i status Marketplace. Zwykłe faktury są wykluczone.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTUtwórz fakturę dla wielu sprzedających/v1/marketplace/invoicesOdczyt + zapis
Użyj zwykłych pól InvoiceCreateInput oraz store_id i allocations. Każdy sprzedający występuje raz, 1–100 dodatnich udziałów, suma dokładnie równa amount. Opcjonalne commission_percent faktury/przydziału wymaga commissions.override i ponownego uwierzytelnienia w panelu dla żądań sesyjnych. Zwraca data.invoice_id i links.checkout. Brak zgodnej wspólnej metody zwraca szczegółowy błąd; bez zastępowania niezgodnym aktywem.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | invoices.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"store_id": "YOUR_STORE_ID",
"amount": "300.00",
"currency": "USD",
"order_id": "cart-1042",
"allocations": [
{
"vendor_id": "VENDOR_A_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_B_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_C_UUID",
"gross_amount": "100.00"
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"store_id": "YOUR_STORE_ID",
"amount": "300.00",
"currency": "USD",
"order_id": "cart-1042",
"allocations": [
{
"vendor_id": "VENDOR_A_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_B_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_C_UUID",
"gross_amount": "100.00"
}
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"store_id": "YOUR_STORE_ID",
"amount": "300.00",
"currency": "USD",
"order_id": "cart-1042",
"allocations": [
{
"vendor_id": "VENDOR_A_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_B_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_C_UUID",
"gross_amount": "100.00"
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"store_id": "YOUR_STORE_ID",
"amount": "300.00",
"currency": "USD",
"order_id": "cart-1042",
"allocations": [
{
"vendor_id": "VENDOR_A_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_B_UUID",
"gross_amount": "100.00"
},
{
"vendor_id": "VENDOR_C_UUID",
"gross_amount": "100.00"
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
amountstringwymaganeZwykły ciąg dziesiętny bez znaku; bez znaku ani wykładnika, do 48 cyfr części całkowitej i 30 miejsc dziesiętnych. Domyślnie musi być dodatni. Sklep może zezwolić na faktury zerowe w Sklepy → Faktura; zerowe sumy rozliczają się bez otrzymania środków, przydzielania adresów ani opłat za przetwarzanie.Szczegóły
Zwykły ciąg dziesiętny bez znaku; bez znaku ani wykładnika, do 48 cyfr części całkowitej i 30 miejsc dziesiętnych. Domyślnie musi być dodatni. Sklep może zezwolić na faktury zerowe w Sklepy → Faktura; zerowe sumy rozliczają się bez otrzymania środków, przydzielania adresów ani opłat za przetwarzanie.
currencystring | nullopcjonalneObsługiwana trzyliterowa waluta fiducjarna, normalizowana do wielkich liter. Pominięcie lub null dziedziczy walutę faktur sklepu. Tworzenie wymaga też niezależnie dostępnego kursu przeliczenia rozliczeń.Szczegóły
Obsługiwana trzyliterowa waluta fiducjarna, normalizowana do wielkich liter. Pominięcie lub null dziedziczy walutę faktur sklepu. Tworzenie wymaga też niezależnie dostępnego kursu przeliczenia rozliczeń.
payment_methods[]object[] | nullopcjonalne
Wybierz dla tej faktury metody włączone w sklepie. Merchant 5.4.0+: pomijaj nieznane/nieaktywne/nieakceptowane opcje; jeśli żadna nie pasuje, użyj ustawień domyślnych sklepu. Pominięcie/null też używa ustawień domyślnych; [] jest nieprawidłowe. Nigdy nie włącza metody ani nie zmienia ustawień sklepu. Zobacz schemat wyboru poniżej.Szczegóły
Wybierz dla tej faktury metody włączone w sklepie. Merchant 5.4.0+: pomijaj nieznane/nieaktywne/nieakceptowane opcje; jeśli żadna nie pasuje, użyj ustawień domyślnych sklepu. Pominięcie/null też używa ustawień domyślnych; [] jest nieprawidłowe. Nigdy nie włącza metody ani nie zmienia ustawień sklepu. Zobacz schemat wyboru poniżej.
chain_slugstringwymaganeSkopiuj chain_slug w Projekt → Sklepy → Metody płatności lub odczytaj go z GET /v1/projects/{project_id}/stores/{store_id}/payment-assets, np. ethereum, base lub bitcoin. Para blockchain/kanał może wystąpić tylko raz.Szczegóły
Skopiuj chain_slug w Projekt → Sklepy → Metody płatności lub odczytaj go z GET /v1/projects/{project_id}/stores/{store_id}/payment-assets, np. ethereum, base lub bitcoin. Para blockchain/kanał może wystąpić tylko raz.
asset_ids[]UUID[] | nullopcjonalneUUID asset.id aktywów on-chain, nie adresy kontraktów ani identyfikatory metod płatności faktury. Użyj tego LUB asset_tickers. Pomiń oba selektory, aby wybrać wszystkie aktywne akceptowane aktywa tego blockchaina. [] i zduplikowane/zerowe identyfikatory są nieprawidłowe. W 5.4.0+ pomijaj identyfikatory nieaktywne/nieakceptowane w tym blockchainie i sklepie; całkowicie niedopasowany wybór używa ustawień domyślnych sklepu.Szczegóły
UUID asset.id aktywów on-chain, nie adresy kontraktów ani identyfikatory metod płatności faktury. Użyj tego LUB asset_tickers. Pomiń oba selektory, aby wybrać wszystkie aktywne akceptowane aktywa tego blockchaina. [] i zduplikowane/zerowe identyfikatory są nieprawidłowe. W 5.4.0+ pomijaj identyfikatory nieaktywne/nieakceptowane w tym blockchainie i sklepie; całkowicie niedopasowany wybór używa ustawień domyślnych sklepu.
asset_tickers[]string[] | nullopcjonalneMerchant 5.3.0+. Symbole takie jak BTC, USDC lub PEPE, ograniczone do chain_slug i tego sklepu. 1–64 unikalne symbole; przycinanie/bez rozróżniania wielkości liter, 1–40 znaków ASCII: liter/cyfr/kropek/podkreśleń/łączników. Użyj tego LUB asset_ids. W 5.4.0+ pomijaj nieznane/nieaktywne/nieakceptowane symbole. Niejednoznaczne akceptowane symbole nadal powodują błąd: użyj asset_ids. Aktywne wybrane metody wymagają prawidłowych portfeli i wyceny; tymczasowe awarie skanera on-chain nie blokują tworzenia od 6.0.6. Lightning opcjonalnie akceptuje tylko BTC.Szczegóły
Merchant 5.3.0+. Symbole takie jak BTC, USDC lub PEPE, ograniczone do chain_slug i tego sklepu. 1–64 unikalne symbole; przycinanie/bez rozróżniania wielkości liter, 1–40 znaków ASCII: liter/cyfr/kropek/podkreśleń/łączników. Użyj tego LUB asset_ids. W 5.4.0+ pomijaj nieznane/nieaktywne/nieakceptowane symbole. Niejednoznaczne akceptowane symbole nadal powodują błąd: użyj asset_ids. Aktywne wybrane metody wymagają prawidłowych portfeli i wyceny; tymczasowe awarie skanera on-chain nie blokują tworzenia od 6.0.6. Lightning opcjonalnie akceptuje tylko BTC.
payment_railonchain | lightningopcjonalneDomyślnie onchain. Aby wybrać Bitcoin Lightning, użyj {chain_slug: bitcoin, payment_rail: lightning} bez asset_ids; asset_tickers może opcjonalnie wynosić [BTC]. Bitcoin on-chain nie obejmuje Lightning. Połączenie Lightning sklepu musi już być włączone i gotowe.Szczegóły
Domyślnie onchain. Aby wybrać Bitcoin Lightning, użyj {chain_slug: bitcoin, payment_rail: lightning} bez asset_ids; asset_tickers może opcjonalnie wynosić [BTC]. Bitcoin on-chain nie obejmuje Lightning. Połączenie Lightning sklepu musi już być włączone i gotowe.
order_idstring | nullopcjonalneIdentyfikator zamówienia sprzedawcy, 1–128 znaków po przycięciu; znaki sterujące są odrzucane.
emailstring | nullopcjonalneE-mail klienta tylko dla sprzedawcy, normalizowany do praktycznego adresu ASCII o długości najwyżej 254 znaków. Pominięcie lub null nie zapisuje e-maila.
descriptionstring | nullopcjonalneOpis widoczny dla klienta, 1–500 znaków; dozwolone są podziały wierszy i tabulatory.
expires_in_secondsinteger | nullopcjonalneCzas ważności wyceny faktury od 300 do 86 400 sekund; pominięcie lub null dziedziczy politykę sklepu.
exchange_rate_spread_percentdecimal string | nullopcjonalneNarzut wyceny od 0 do 100, z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu; "0" wyłącza go dla tej faktury. Stosowany przed zaokrągleniem w górę, potem blokowany. Nie zmienia kwoty faktury w walucie fiducjarnej ani podstawy opłaty za przetwarzanie.Szczegóły
Narzut wyceny od 0 do 100, z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu; "0" wyłącza go dla tej faktury. Stosowany przed zaokrągleniem w górę, potem blokowany. Nie zmienia kwoty faktury w walucie fiducjarnej ani podstawy opłaty za przetwarzanie.
underpayment_tolerance_percentdecimal string | nullopcjonalneAkceptowana niedopłata od 0 do 99.99 z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu.
ipn_urlstring | nullopcjonalnePubliczne wywołanie zwrotne HTTPS, najwyżej 2048 bajtów, bez danych dostępu ani fragmentu. Zastępuje wartość domyślną sklepu; null/pominięcie ją dziedziczy.
redirect_urlstring | nullopcjonalneAdres HTTPS sukcesu używany po rozliczeniu, najwyżej 2048 bajtów, bez osadzonych danych dostępu. Pominięcie lub null dziedziczy wartość domyślną sklepu i nie może jej wyczyścić.
cancel_urlstring | nullopcjonalneAdres powrotny HTTPS używany po zakończeniu płatności bez sukcesu. Pominięcie lub null dziedziczy wartość domyślną sklepu i nie może jej wyczyścić.
redirect_automaticallyboolean | nullopcjonalnePominięcie lub null dziedziczy politykę sklepu. true wymaga obowiązującego redirect_url.
languagestring | nullopcjonalneJęzyk klienta: en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja. pt oznacza portugalski brazylijski, a zh - chiński uproszczony. Obsługiwane znaczniki regionalne, takie jak de-DE, są normalizowane do wymienionego języka. Pominięcie lub null dziedziczy język sklepu. Język panelu jest oddzielny.Szczegóły
Język klienta: en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja. pt oznacza portugalski brazylijski, a zh - chiński uproszczony. Obsługiwane znaczniki regionalne, takie jak de-DE, są normalizowane do wymienionego języka. Pominięcie lub null dziedziczy język sklepu. Język panelu jest oddzielny.
checkout_appearanceobject | nullopcjonalne
Częściowe ustawienia prezentacji tej faktury. Pominięcie/null używa bieżącego wyglądu sklepu. Obiekt, w tym {}, zamraża wynikowy wygląd i obrazy przy tworzeniu. Zobacz schemat nadpisania poniżej; bez ustawień finansowych, HTML, CSS, JavaScript ani zdalnych adresów obrazów.Szczegóły
Częściowe ustawienia prezentacji tej faktury. Pominięcie/null używa bieżącego wyglądu sklepu. Obiekt, w tym {}, zamraża wynikowy wygląd i obrazy przy tworzeniu. Zobacz schemat nadpisania poniżej; bez ustawień finansowych, HTML, CSS, JavaScript ani zdalnych adresów obrazów.
inherit_default_storebooleanopcjonalnetrue wybiera wygląd domyślnego sklepu projektu jako bazę; w przeciwnym razie używa efektywnego wyglądu sklepu docelowego. Następnie nadpisania są stosowane i zapisywane niezależnie; wynikowa flaga faktury to false.Szczegóły
true wybiera wygląd domyślnego sklepu projektu jako bazę; w przeciwnym razie używa efektywnego wyglądu sklepu docelowego. Następnie nadpisania są stosowane i zapisywane niezależnie; wynikowa flaga faktury to false.
introstringopcjonalneZwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.Szczegóły
Zwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.
outrostringopcjonalneZwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.Szczegóły
Zwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.
intro_font_sizeintegeropcjonalnePiksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.
outro_font_sizeintegeropcjonalnePiksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.
accent_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
background_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
card_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
button_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
imagesobjectopcjonalne
Klucze logo_light, logo_dark, favicon. Pominięty klucz zachowuje obraz bazowy; null go usuwa. Obiekt {store_id: UUID, kind?: logo_light|logo_dark|favicon} wykorzystuje efektywny przesłany obraz tego sklepu w TYM SAMYM projekcie. kind domyślnie odpowiada kluczowi docelowemu. Najpierw prześlij w Sklep → Strona płatności; skopiuj identyfikator API sklepu z Podstawowe → Identyfikatory API. Brak obrazów lub identyfikatory z innego projektu zwracają 400. Zewnętrzne URL ani dane obrazów nie są akceptowane.Szczegóły
Klucze logo_light, logo_dark, favicon. Pominięty klucz zachowuje obraz bazowy; null go usuwa. Obiekt {store_id: UUID, kind?: logo_light|logo_dark|favicon} wykorzystuje efektywny przesłany obraz tego sklepu w TYM SAMYM projekcie. kind domyślnie odpowiada kluczowi docelowemu. Najpierw prześlij w Sklep → Strona płatności; skopiuj identyfikator API sklepu z Podstawowe → Identyfikatory API. Brak obrazów lub identyfikatory z innego projektu zwracają 400. Zewnętrzne URL ani dane obrazów nie są akceptowane.
logo_lightobject | nullopcjonalne
logo_darkobject | nullopcjonalne
show_order_idbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
show_descriptionbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
details_expandedbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
show_project_namebooleanopcjonalneMerchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.Szczegóły
Merchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.
show_store_namebooleanopcjonalneMerchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.Szczegóły
Merchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.
featured_chains[]string[]opcjonalneUporządkowane slugi blockchainów, najwyżej 60 unikalnych wartości (małe litery, cyfry, łączniki; do 64 znaków). [] czyści. Zmieniana jest kolejność tylko dostępnych metod faktury.Szczegóły
Uporządkowane slugi blockchainów, najwyżej 60 unikalnych wartości (małe litery, cyfry, łączniki; do 64 znaków). [] czyści. Zmieniana jest kolejność tylko dostępnych metod faktury.
featured_asset_ids[]UUID[]opcjonalneDo 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.Szczegóły
Do 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.
default_asset_idUUID|nullopcjonalneDo 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.Szczegóły
Do 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.
messagesobjectopcjonalne
Obiekty językowe z kluczami en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja, zawierające zwykłe ciągi waiting, confirming, paid, underpaid, expired (po 500 znaków). Zmieniają się tylko podane języki/stany; {} czyści wszystkie komunikaty, {en:{}} czyści angielski, a pusty ciąg stanu czyści ten stan. Angielski jest językiem awaryjnym. Nie zastępuje rzeczywistego statusu.Szczegóły
Obiekty językowe z kluczami en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja, zawierające zwykłe ciągi waiting, confirming, paid, underpaid, expired (po 500 znaków). Zmieniają się tylko podane języki/stany; {} czyści wszystkie komunikaty, {en:{}} czyści angielski, a pusty ciąg stanu czyści ten stan. Angielski jest językiem awaryjnym. Nie zastępuje rzeczywistego statusu.
enobjectopcjonalne
deobjectopcjonalne
esobjectopcjonalne
pt-BRobjectopcjonalne
itobjectopcjonalne
ruobjectopcjonalne
zh-CNobjectopcjonalne
frobjectopcjonalne
koobjectopcjonalne
support_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
terms_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
privacy_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
return_button_textstringopcjonalneEtykieta do 60 znaków. Do zachowania faktury używaj najwyższego poziomu redirect_url/cancel_url/redirect_automatically/language.
show_return_buttonbooleanopcjonalnePokaż ręczny przycisk Powrót do sprzedawcy/anulowania na stronie płatności, także w stanach końcowych. Pomiń, aby odziedziczyć wygląd sklepu (domyślnie true); false go ukrywa. Nie anuluje faktury, nie ukrywa adresów URL w JSON ani nie wyłącza automatycznych przekierowań po sukcesie. W razie potrzeby oddzielnie ustaw redirect_automatically najwyższego poziomu na false. Wymaga oprogramowania sprzedawcy 8.1.4 lub nowszego.Szczegóły
Pokaż ręczny przycisk Powrót do sprzedawcy/anulowania na stronie płatności, także w stanach końcowych. Pomiń, aby odziedziczyć wygląd sklepu (domyślnie true); false go ukrywa. Nie anuluje faktury, nie ukrywa adresów URL w JSON ani nie wyłącza automatycznych przekierowań po sukcesie. W razie potrzeby oddzielnie ustaw redirect_automatically najwyższego poziomu na false. Wymaga oprogramowania sprzedawcy 8.1.4 lub nowszego.
metadataobject | nullopcjonalne
Obiekt JSON tylko dla sprzedawcy; pominięcie lub null staje się {}, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia. firstname, lastname, street, street2, zip, city, country, countryiso2, company i vatid są walidowane, normalizowane i odwzorowywane w polach podsumowania klienta.Szczegóły
Obiekt JSON tylko dla sprzedawcy; pominięcie lub null staje się {}, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia. firstname, lastname, street, street2, zip, city, country, countryiso2, company i vatid są walidowane, normalizowane i odwzorowywane w polach podsumowania klienta.
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
allocations[]object[]
[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]Szczegóły
[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"invoice_id": "YOUR_INVOICE_ID",
"status": "new",
"marketplace": {
"state": "pending",
"allocations": []
}
},
"links": {
"checkout": "https://pay.example.com/invoice/YOUR_INVOICE_ID"
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga invoices.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETFaktura i przydziały/v1/marketplace/invoices/{invoice_id}Tylko odczyt
Zwykłe szczegóły faktury oraz stan marketplace, revision, hold_reason, zamrożone przydziały, zapis polityki, najnowsze 200 płatności i najnowsze 100 powiązanych wypłat ze znacznikami obcięcia. Publiczna strona płatności nie ujawnia danych sprzedających.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETDowody płatności faktury/v1/marketplace/invoices/{invoice_id}/paymentsTylko odczyt
Zwykłe dowody płatności z page/per_page. Obserwacje nie są wypłatami sprzedającym.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETPrzydziały faktury/v1/marketplace/invoices/{invoice_id}/allocationsTylko odczyt
Niezmienne zapisy udziału/prowizji/adresu docelowego i dokładne atomowe wartości brutto, prowizji i netto po kwalifikującym rozliczeniu.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTAnuluj nieopłaconą fakturę/v1/marketplace/invoices/{invoice_id}/cancelOdczyt + zapis
Tylko nieopłacona faktura new lub expired. Spóźnione wpływy są wstrzymywane do sprawdzenia. Rewizja to rewizja faktury Marketplace.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | invoices.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga invoices.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTWstrzymaj przydziały/v1/marketplace/invoices/{invoice_id}/allocations/holdOdczyt + zapis
Wstrzymaj niepodpisane przydziały bez usuwania zobowiązań. Podpisane lub niepewne wypłaty pozostają śledzone.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | reconciliation.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga reconciliation.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTSprawdź i zwolnij przydziały/v1/marketplace/invoices/{invoice_id}/allocations/releaseOdczyt + zapis
Sprawdź ponownie pokrycie/ostateczność. Opcjonalne approved_amount_atomic jawnie akceptuje zmniejszony podział z pełnym pokryciem przed zamrożeniem przydziałów; nigdy nie tworzy fikcyjnych wpływów.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | reconciliation.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga reconciliation.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZmień powiązanie nieopłaconego adresu docelowego/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationOdczyt + zapis
Wymagana rewizja przydziału. Tylko niezarezerwowane/niepodpisane operacje i oddzielnie zatwierdzona wersja dla tego samego sprzedającego w pierwotnej sieci. Rejestrowane w audycie; podpisanych operacji nie można zmienić.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | reconciliation.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga reconciliation.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTPrzygotuj pełny zwrot/v1/marketplace/invoices/{invoice_id}/refundOdczyt + zapis
Przygotuj oddzielnie zatwierdzany pełny zwrot otrzymanej kwoty w tym samym aktywie. Przed wypłatą sprzedającym zarezerwuj niewypłacone środki i odwróć prowizję po potwierdzeniu. Po wszystkich wypłatach sprzedającym użyj oddzielnych wolnych środków głównego adresu. Nigdy nie wyprowadzaj adresu zwrotu klienta z adresu nadawcy.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | reconciliation.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"payment_method_id": "YOUR_PAYMENT_METHOD_ID",
"destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
"reason": "Customer cancellation",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"payment_method_id": "YOUR_PAYMENT_METHOD_ID",
"destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
"reason": "Customer cancellation",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"payment_method_id": "YOUR_PAYMENT_METHOD_ID",
"destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
"reason": "Customer cancellation",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"payment_method_id": "YOUR_PAYMENT_METHOD_ID",
"destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
"reason": "Customer cancellation",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga reconciliation.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETZnajdź przydziały wypłat/v1/marketplace/allocationsTylko odczyt
Stronicowani kandydaci; filtruj status (available itd.), asset_id, vendor_id, store_id i q (sprzedający/zamówienie/faktura).
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETSalda księgi projektu/v1/marketplace/balancesTylko odczyt
Dokładne pogrupowane sumy aktywów/kont, w tym held, available, reserved, paid, prowizje, zwroty i opłaty sieciowe. Zewnętrzne konto bilansujące jest wykluczone.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETNiezmienny dziennik/v1/marketplace/ledgerTylko odczyt
Stronicowane ruchy księgowe tylko do dopisywania; q dla identyfikatora/konta oraz filtry asset_id i vendor_id. Kwoty są atomowymi ciągami; żadnego wpisu nie można edytować ani ręcznie oznaczyć jako opłacony.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETHistoria wypłat/v1/marketplace/payoutsTylko odczyt
Stronicowane rekordy nadrzędne; filtruj state, asset_id, vendor_id lub q dla ID/symbolu. Paid oznacza niezależne potwierdzenie, nie samo rozgłoszenie.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTPodgląd planu przydziałów/v1/marketplace/payouts/previewOdczyt + zapis
Plan księgowy tylko do odczytu, bez rezerwacji ani upoważnienia do wydania środków. Maksymalna opłata to limit użytkownika, nie szacowana rzeczywista opłata. Przygotowanie później wykonuje kontrole na żywo.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | payouts.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/payouts/preview" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/preview", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/preview");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/preview",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga payouts.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTPrzygotuj wypłatę/v1/marketplace/payoutsOdczyt + zapis
Zarezerwuj 1–100 dostępnych identyfikatorów przydziałów w jednym aktywie/portfelu. BTC wymaga wszystkich niewypłaconych udziałów każdej wybranej faktury w jednej partii z wieloma wyjściami. Budżety są atomowymi ciągami w natywnym aktywie opłat. Tworzy plan awaiting_approval, nie rozgłasza transakcji.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | payouts.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/payouts" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"id": "YOUR_PAYOUT_ID",
"state": "awaiting_approval",
"revision": 1,
"plan_hash": "RETAINED_PLAN_HASH",
"plan": {
"amount_atomic": "28800000",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"items": []
},
"transactions": []
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga payouts.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETSzczegóły wypłaty/v1/marketplace/payouts/{payout_id}Tylko odczyt
Niezmienny plan/hash, rewizja, termin ważności, pozycje odbiorców, zachowane próby podrzędne, postęp, dokładne opłaty i linki do eksploratora. Nigdy klucze prywatne ani podpisane bajty.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"id": "YOUR_PAYOUT_ID",
"state": "awaiting_approval",
"revision": 1,
"plan_hash": "RETAINED_PLAN_HASH",
"plan": {
"amount_atomic": "28800000",
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"items": []
},
"transactions": []
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZatwierdź i wyślij/v1/marketplace/payouts/{payout_id}/approveOdczyt + zapis
Jawnie autoryzuj dokładny zachowany plan przed jego wygaśnięciem. Zakolejkuj ograniczone finansowanie gas i transakcje sprzedających w tle.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | payouts.approve |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga payouts.approve. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTSprawdź i wznów wypłatę/v1/marketplace/payouts/{payout_id}/resumeOdczyt + zapis
Tylko needs_attention. Użyj ponownie zachowanego planu/hash; potwierdzonym odbiorcom nigdy nie wysyła się ponownie. Dwóch niezależnych dostawców musi udowodnić kanoniczne, wystarczająco potwierdzone cofnięcie EVM, zanim nieudaną operację podrzędną będzie można zastąpić. Poprzednie opłaty nadal zużywają zatwierdzony budżet, a wszystkie hashe pozostają w historii. Nieznane/częściowe dostarczenie tokena zwraca payout_recovery_unverified; rezerwacje pozostają zatrzymane.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | payouts.approve |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga payouts.approve. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTAnuluj niepodpisane operacje/v1/marketplace/payouts/{payout_id}/cancelOdczyt + zapis
Zwolnij wyłącznie rezerwacje, o których bezpiecznie wiadomo, że nie zostały podpisane/wysłane. Potwierdzeni odbiorcy i audyt pozostają. Podpisanych/niepewnych operacji nie można anulować. Jawnie odzyskane, potwierdzone cofnięcie nie blokuje już anulowania pozostałych niepodpisanych operacji.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | payouts.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga payouts.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETPolityki automatycznych wypłat/v1/marketplace/policiesTylko odczyt
Odczytaj polityki aktywów, revision, next_attempt_at, last_checked_at i bezpieczne last_error, gdy przygotowanie lub autoryzacja wymagają uwagi.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": []
}Pola odpowiedzi
data[]arrayUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTAutoryzuj politykę wypłat/v1/marketplace/policiesOdczyt + zapis
Dokładne ciągi atomowe; minimum <= transfer <= dzienny limit kwoty głównej, limity opłat/gas <= ich dzienne budżety. interval_seconds 60–604800; minimum_confirmations 1–100000 z uwzględnieniem minimum blockchaina. Rewizja 0 tworzy. Włączone polityki mogą wysyłać bez dalszych kliknięć; pozostaw false do sprawdzenia.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | policies.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/policies" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"asset_id": "YOUR_ASSET_ID",
"revision": 0,
"enabled": false,
"minimum_atomic": "100000",
"transfer_limit_atomic": "10000000",
"daily_limit_atomic": "30000000",
"fee_limit_atomic": "10000",
"daily_fee_limit_atomic": "30000",
"gas_limit_atomic": "0",
"daily_gas_limit_atomic": "0",
"interval_seconds": 3600,
"minimum_confirmations": 2
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"asset_id": "YOUR_ASSET_ID",
"revision": 0,
"enabled": false,
"minimum_atomic": "100000",
"transfer_limit_atomic": "10000000",
"daily_limit_atomic": "30000000",
"fee_limit_atomic": "10000",
"daily_fee_limit_atomic": "30000",
"gas_limit_atomic": "0",
"daily_gas_limit_atomic": "0",
"interval_seconds": 3600,
"minimum_confirmations": 2
}`;
const response = await fetch("https://api.example.com/v1/marketplace/policies", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"asset_id": "YOUR_ASSET_ID",
"revision": 0,
"enabled": false,
"minimum_atomic": "100000",
"transfer_limit_atomic": "10000000",
"daily_limit_atomic": "30000000",
"fee_limit_atomic": "10000",
"daily_fee_limit_atomic": "30000",
"gas_limit_atomic": "0",
"daily_gas_limit_atomic": "0",
"interval_seconds": 3600,
"minimum_confirmations": 2
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/policies");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"asset_id": "YOUR_ASSET_ID",
"revision": 0,
"enabled": false,
"minimum_atomic": "100000",
"transfer_limit_atomic": "10000000",
"daily_limit_atomic": "30000000",
"fee_limit_atomic": "10000",
"daily_fee_limit_atomic": "30000",
"gas_limit_atomic": "0",
"daily_gas_limit_atomic": "0",
"interval_seconds": 3600,
"minimum_confirmations": 2
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/policies",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga policies.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETWebhooki platformy handlowej/v1/marketplace/webhooksTylko odczyt
Do 20 punktów końcowych oraz obsługiwane event_types. Nigdy nie zwraca zaszyfrowanych ani jawnych sekretów podpisujących.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"endpoints": [],
"event_types": [
"marketplace.invoice.created",
"marketplace.allocations.available",
"marketplace.allocations.held",
"marketplace.payout.approved",
"marketplace.payout.broadcast",
"marketplace.payout.confirmed",
"marketplace.payout.partial",
"marketplace.payout.failed",
"marketplace.payout.cancelled",
"marketplace.refund.prepared",
"marketplace.refund.confirmed"
]
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTUtwórz webhook platformy handlowej/v1/marketplace/webhooksOdczyt + zapis
Tylko publiczne HTTPS, bez danych dostępu, prywatnych celów ani przekierowań. Zwraca signing_secret raz na zachowaną idempotentną odpowiedź utworzenia; przechowuj bezpiecznie. Oddzielny od sekretu IPN sklepu.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | webhooks.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/webhooks" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga webhooks.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTZaktualizuj webhook platformy handlowej/v1/marketplace/webhooks/{webhook_id}/updateOdczyt + zapis
Zmiany anulują stare niewysłane dostarczenia. Sekret pozostaje niezmieniony; stare niezmienne treści nigdy nie są przekierowywane na nowy URL.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | webhooks.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga webhooks.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTWyłącz webhook platformy handlowej/v1/marketplace/webhooks/{webhook_id}/disableOdczyt + zapis
Zatrzymaj nowe dostarczenia; zachowana historia zdarzeń pozostaje.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | webhooks.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga webhooks.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETZdarzenia platformy handlowej/v1/marketplace/eventsTylko odczyt
Stronicowane niezmienne odwołania do zdarzeń. q przeszukuje typ/identyfikator; status filtruje event_type.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETOdczytaj zachowane zdarzenie/v1/marketplace/events/{event_id}Tylko odczyt
Zwraca niezmienną pierwotną treść zdarzenia, nie odtworzenie na podstawie bieżących sald.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"event_id": "11111111-1111-4111-8111-111111111111",
"event_type": "marketplace.payout.confirmed",
"payload_version": 1,
"project_id": "YOUR_PROJECT_ID",
"occurred_at": "2026-10-06T12:00:00Z",
"data": {
"payout_id": "YOUR_PAYOUT_ID",
"asset_id": "YOUR_ASSET_ID",
"amount_atomic": "28800000",
"transactions": [
{
"transaction_id": "EXAMPLE_TRANSACTION_ID",
"explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
}
]
}
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETHistoria dostarczania platformy handlowej/v1/marketplace/webhook-deliveriesTylko odczyt
Stronicowane dostarczenia, typ zdarzenia, próby i ostatni wynik. Filtruj status pending/sending/succeeded/failed/cancelled; q według typu zdarzenia.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}Pola odpowiedzi
Uwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETSzczegóły dostarczenia/v1/marketplace/webhook-deliveries/{delivery_id}Tylko odczyt
Pierwotny URL, zachowana treść, wynik HTTP i bezpieczny błąd; bez sekretu podpisującego.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | marketplace.read |
Parametry zapytania
project_idUUIDwymaganeAutoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.
pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
per_pageopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
qopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
statusopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
store_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
vendor_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
asset_idopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
fromopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
toopcjonalneUżywaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga marketplace.read. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
POSTDostarcz ponownie to samo zdarzenie/v1/marketplace/webhook-deliveries/{delivery_id}/resendOdczyt + zapis
Tylko zakończone dostarczenia i niezmieniony aktywny punkt końcowy; do 20 ręcznych ponowień. Używa ponownie event_id. Nieudane powiadomienie nigdy nie upoważnia do drugiej płatności.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MARKETPLACE_API_TOKEN |
| Idempotency-Key | wymagane | 16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem |
| Parametr | Typ / lokalizacja | Zasada |
|---|---|---|
| permission | credential scope | webhooks.write |
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: marketplace-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {}
}Pola odpowiedzi
dataobjectUwagi dotyczące użycia
- Wymaga webhooks.write. Przykładowe odpowiedzi pokazują wybrane pola; użyj GET zasobu, aby uzyskać pełne zachowane dowody.
- Każdy POST wymaga trwale zapisanego Idempotency-Key o długości 16–128 znaków (litery, cyfry, -, _ lub .). Po przekroczeniu czasu oczekiwania użyj ponownie tego samego klucza i instrukcji JSON. Inne instrukcje zwracają 409. Zakończone odpowiedzi są przechowywane przez 30 dni; stare klucze stają się znacznikami blokującymi ponowne użycie. Nigdy nie zmieniaj klucza tylko po to, aby ominąć niepewny wynik.
- Klucze mają listy projektów, opcjonalne ograniczenia sklepów faktur, termin ważności, listę dozwolonych IP i limit 1–600/minutę (domyślnie 60). HTTP 429 zawiera Retry-After. Klucze ograniczone do sklepu nie widzą sprzedających, sald projektu, księgi, wypłat ani ustawień. Dane dostępu do wydawania środków przechowuj wyłącznie na zaufanych serwerach, nigdy w przeglądarkach ani dystrybuowanych aplikacjach mobilnych.
Błędy
GETLista wyjątków płatności/v1/projects/{project_id}/reconciliationTylko odczyt
Jedna stronicowana kolejka przeglądu niedopłat, nadpłat, płatności spóźnionych, podlegających reorganizacji lub niejednoznacznych, nieudanych dostarczeń oraz wyłączonych/wygasłych metod. Sprawy potwierdzone przez operatora otwierają się ponownie po pojawieniu się nowych dowodów.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
Parametry ścieżki
Parametry zapytania
reasonstringunderpaid, overpaid, late, reorged, ambiguous, delivery_failed, disabled_method lub expired_method.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{"data":[],"pagination":{"page":1,"per_page":25,"total":0,"has_more":false},"counts":{"open":0,"resolved":0}}Pola odpowiedzi
data[]object[]zawsze
Najpierw ostatnio zaktualizowane sprawy. W adresach szczegółów dla sprzedawcy używaj invoice_id, nie wewnętrznego id.
idUUIDzawszeWewnętrzny identyfikator rekordu / UUID faktury widoczny dla klienta. invoice_id odpowiada treściom wywołań zwrotnych.
invoice_idUUIDzawszeWewnętrzny identyfikator rekordu / UUID faktury widoczny dla klienta. invoice_id odpowiada treściom wywołań zwrotnych.
paginationobjectzawsze
page (1–40001), per_page (25), łączna liczba pasujących wierszy, has_more.
Uwagi dotyczące użycia
- Tylko odczyt, w zakresie projektu i objęte limitem danych dostępu. Decyzje finansowe i zwroty pozostają dostępne wyłącznie w panelu.
- Wiersze zawierają id (wewnętrzny UUID), invoice_id (publiczny UUID, ten sam co w wywołaniach zwrotnych), dane sklepu, pierwotną kwotę/walutę fiducjarną, invoice_status, status sprawy, reasons, revision i updated_at. Używaj invoice_id w punkcie końcowym szczegółów sprzedawcy.
- Automatyczne wykrywanie działa w pierwotnym oknie monitorowania faktury; Ponowne skanowanie wydłuża obserwację o godzinę bez włączania strony płatności. Metody po rozliczeniu/anulowaniu nadal są monitorowane w tym oknie.
Błędy
GETOdczytaj dowody uzgodnienia/v1/projects/{project_id}/reconciliation/{invoice_id}Tylko odczyt
Zwraca fakturę, sprawę, dokładne sumy metod i dostępne kwoty zwrotów, zaobserwowane transakcje, historię dostarczeń, decyzje sprzedawcy i powiązane przelewy zwrotów. Nigdy nie ujawnia kluczy podpisujących ani sekretów wywołań zwrotnych.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
Parametry ścieżki
Parametry zapytania
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{"invoice":{"invoice_id":"YOUR_PUBLIC_INVOICE_ID","status":"processing"},"case":{"status":"open","reasons":["underpaid"],"revision":1},"methods":[],"history":[],"history_pagination":{"page":1,"per_page":25,"total":0},"refunds":[],"observations":[],"deliveries":[]}Pola odpowiedzi
invoiceobjectzawsze
Pełna faktura sprzedawcy: pola podsumowania, prywatne metadane i payment_intents. Bez opakowania w data.
idUUIDzawszeWewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.
invoice_idUUIDzawszePubliczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.
emailstring | nullzawszeE-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.
customer_namestring | nullzawszeNazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.
customer_addressstring | nullzawszeJednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.
exchange_rate_spread_percentdecimal stringzawszeZablokowany narzut wyceny: nadpisanie przy tworzeniu lub wartość domyślna sklepu przy pominięciu. Stosowany przed zaokrągleniem w górę; nigdy nie zmienia się na tej fakturze.
underpayment_tolerance_percentdecimal stringzawszeNiezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.
amount_statusamount statuszawszenone, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.
winning_payment_intent_idUUID | nullzawszeMetoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.
monitoring_expires_atRFC 3339 timestampzawszeNajpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.
ipn_urlstring | nullzawszeObowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.
cancel_urlstring | nullzawszeObowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.
redirect_automaticallybooleanzawszeCzy strona płatności powinna automatycznie przekierować po sukcesie.
metadataobjectzawszeMetadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.Szczegóły
Metadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.
payment_intents[]object[]zawsze
Wycenione metody płatności i stan monitorowania.
payment_railonchain | lightningzawszeTransport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.Szczegóły
Transport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.
bolt11string | nullzawszeŻądanie płatności Lightning, w innym przypadku null. Opłać to żądanie portfelem Lightning; nigdy nie wysyłaj środków on-chain na jego hash płatności.
asset_decimalsintegerzawszePrecyzja jednostek atomowych. Lightning BTC używa 11 (millisatoshi), a nie 8 jak Bitcoin on-chain. Wyceny są w pełnych satoshi; wpływy zachowują precyzję millisatoshi.
quote_ratedecimal stringzawszeJednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.
quote_detailsobject | nullzawszePochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.Szczegóły
Pochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.
expected_amountdecimal stringzawszeDokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.Szczegóły
Dokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.
minimum_payment_amountdecimal stringzawszeNajmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.
minimum_payment_amount_atomicinteger stringzawszeDokładny akceptowany próg w najmniejszej jednostce aktywa.
destination_addressstringzawszeAdres odbiorczy on-chain lub 64-znakowy hash płatności dla Lightning. Do płacenia Lightning używaj bolt11; jego hash nie jest adresem Bitcoin.
destination_tagstring | nullzawszeWymagany publiczny identyfikator płatności, jeśli kanał go używa: tag docelowy XRP, identyfikator memo Stellar lub komentarz faktury TON. Null dla kanałów z unikalnymi adresami.
derivation_indexintegerzawszeZarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.
monitoring_expires_atRFC 3339 timestampzawszeKoniec monitorowania spóźnionych płatności dla tej metody.
caseobject | nullzawsze
Bieżąca sprawa ze statusem, przyczynami, rewizją i znacznikami czasu; null, gdy nie ma wyjątku. Wewnętrzne dowody są wykluczone.
methods[]object[]zawszeid, wallet_id, asset_id, symbol, chain, decimals, expected_atomic, received_atomic, confirmed_atomic, refundable_atomic, address, tag, monitor_error, last_checked_at, monitoring_expires_at i spending_supported. Kwoty atomowe są ciągami znaków.Szczegóły
id, wallet_id, asset_id, symbol, chain, decimals, expected_atomic, received_atomic, confirmed_atomic, refundable_atomic, address, tag, monitor_error, last_checked_at, monitoring_expires_at i spending_supported. Kwoty atomowe są ciągami znaków.
history[]object[]zawszeNajnowsze 25 decyzji na tej stronie: id, action, note, actor, result, created_at.
history_paginationobjectzawsze
page, per_page (25), total. Tylko historia decyzji jest stronicowana przez page.
refunds[]object[]zawszeNajnowsze 100 zwrotów: id, payment_intent_id, amount_atomic, destination, status, request, treasury_intent_id, transfer_status, created_at i transactions (id/status). Zlecanie zwrotów tylko w panelu.Szczegóły
Najnowsze 100 zwrotów: id, payment_intent_id, amount_atomic, destination, status, request, treasury_intent_id, transfer_status, created_at i transactions (id/status). Zlecanie zwrotów tylko w panelu.
observations[]object[]zawszeNajnowsze 100: payment_intent_id, transaction_id, event_index, amount, status, confirmations, observed_at, symbol, chain i disabled_at_detection. explorer_name/explorer_url są dołączane tam, gdzie obsługiwane.Szczegóły
Najnowsze 100: payment_intent_id, transaction_id, event_index, amount, status, confirmations, observed_at, symbol, chain i disabled_at_detection. explorer_name/explorer_url są dołączane tam, gdzie obsługiwane.
deliveries[]object[]zawszeNajnowsze 50: id, kind, status, attempts, response_status, error, next_attempt_at, event_type i created_at. Bez sekretów wywołań zwrotnych.
Uwagi dotyczące użycia
- case ma wartość null, gdy faktura nie wygenerowała wyjątku. Zwracanych jest 100 najnowszych obserwacji i 50 dostarczeń; historia decyzji jest stronicowana.
- refundable_atomic wymaga co najmniej jednego potwierdzenia sieciowego, wyklucza istniejące rezerwacje zwrotów i nie obiecuje dostępnych do wydania środków w portfelu. Bieżąca wycena dodatkowo weryfikuje gotowość portfela, salda źródłowe i opłaty.
- Rozgłoszony zwrot oznacza wysłanie do punktu końcowego blockchaina, nie niezależnie potwierdzony odbiór przez klienta. Opłaty są dodatkowe, a opłaty za przetwarzanie w walucie fiducjarnej nie są automatycznie zwracane przy zleceniu zwrotu.
- Menu projektu w panelu → Wymaga uwagi udostępnia anulowanie, akceptację, odrzucenie, ponowne otwarcie, przegląd, notatki, Ponowne skanowanie, ponowienie dostarczenia i zwroty w obsługiwanych blockchainach. Decyzje używają sesji chronionych przed CSRF, unikalnego request_id, bieżącej rewizji sprawy, wymaganej notatki i wyraźnego potwierdzenia; tokeny bearer nie mogą wywołać tych zmian.
Błędy
GETWykrywanie usług API/Publiczne
Odpowiedź warstwy brzegowej zarządzanego hosta API potwierdzająca rolę publicznego API v1. Odpowiedź generuje zarządzane proxy, a nie router Axum sprzedawcy.
Uwierzytelnianie i nagłówki
Publiczne
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/"// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://api.example.com/", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://api.example.com/");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://api.example.com/",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"service": "Wholly Crypto API",
"status": "ready",
"version": "v1"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Tylko zarządzana nazwa hosta API gwarantuje dokładnie taką odpowiedź dla ścieżki głównej.
Błędy
GETStan usługi/healthzPubliczne
Sprawdza dostępność aplikacji i wykonuje ping bazy danych z limitem dwóch sekund. Używaj do monitorowania, nie zamiast statusu faktury.
Uwierzytelnianie i nagłówki
Publiczne
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/healthz"// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://api.example.com/healthz", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://api.example.com/healthz");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://api.example.com/healthz",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 healthy; 503 database unavailable
Przykładowa odpowiedź
{
"status": "ok",
"database": "ok",
"version": "0.1.0"
}Pola odpowiedzi
Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Wartość wersji to wersja działającego pakietu, nie wersja ścieżki API.
Błędy
GETLista aktywów płatniczych projektu/v1/projects/{project_id}/payment-assetsTylko odczyt
Wyświetla natywne aktywa i zweryfikowane tokeny z polityką projektu, gotowością portfela blockchaina oraz zainstalowanymi możliwościami skanera/salda. scanner_ready to warunek obecności adaptera w kompilacji, nie wynik bieżącego kworum punktów końcowych. Od 6.0.6 tworzenie zachowuje skonfigurowane metody podczas przestoju skanera. Weryfikacja odbioru nadal wymaga skonfigurowanego progu sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1).
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{
"asset": {
"id": "10000000-0000-4000-8000-000000000003",
"asset_key": "eip155:1/slip44:60",
"chain_slug": "ethereum",
"network": "mainnet",
"caip_network_id": "eip155:1",
"caip_asset_id": "eip155:1/slip44:60",
"asset_kind": "native",
"payment_rail": "evm-native",
"symbol": "ETH",
"name": "Ethereum",
"decimals": 18,
"contract_address": null,
"coingecko_id": "ethereum",
"icon_path": "/assets/coingecko/ethereum.png",
"token_standard": null,
"metadata_verified_at": null,
"payment_supported": true,
"scanner_ready": true,
"balance_ready": true,
"default_finality_mode": "confirmations",
"default_required_confirmations": 12,
"default_monitoring_minutes": 60
},
"policy": {
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 12,
"monitoring_minutes": 60,
"late_monitoring_days": 30
},
"wallet": null,
"wallet_readiness": "wallet_missing",
"receive_readiness": { "ready": false, "invoice_creatable": false, "checked_at": "2026-09-16T09:00:00Z", "issues": [{ "chain_slug": "ethereum", "asset_id": "10000000-0000-4000-8000-000000000003", "asset_ticker": "ETH", "reason_code": "wallet_missing", "message": "ethereum / ETH: Create a project wallet for this chain.", "action": "wallets" }] }
}
]
}Pola odpowiedzi
data[]object[]
assetobjectzawsze
Trwale zapisane aktywo natywne lub zweryfikowany token.
asset_kindnative | tokenzawszeCzy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.
payment_railstringzawszeKanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.
coingecko_idstring | nullzawszeTożsamość wykrywania/wyceny. Null dla niestandardowych kontraktów; nigdy nie wnioskuj ceny rynkowej z ich symbolu. Same metadane CoinGecko nigdy nie umożliwiają wyboru tokena.
custom_tokenbooleanzawszeNiestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.
token_standarderc20 | spl-token | nullzawszeZweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.
metadata_verified_attimestamp | nullzawszeCzas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.
payment_supportedbooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
scanner_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
balance_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
default_finality_modeconfirmations | finalizedzawszeDomyślny model ostateczności dziedziczony przez nową politykę projektu.
policyobject | nullzawsze
Polityka aktywacji/ostateczności projektu lub null, jeśli nieskonfigurowana. Zawiera custom_price_mode (fixed/dex), custom_price_usd (stały ciąg dziesiętny lub null), custom_dex_pair (wybrana pula lub null) i custom_dex (dex_id, quote_symbol, bieżące price_usd lub null, liquidity_usd, fetched_at, last_error). Niestandardową wycenę współdzielą sklepy w tym projekcie.Szczegóły
Polityka aktywacji/ostateczności projektu lub null, jeśli nieskonfigurowana. Zawiera custom_price_mode (fixed/dex), custom_price_usd (stały ciąg dziesiętny lub null), custom_dex_pair (wybrana pula lub null) i custom_dex (dex_id, quote_symbol, bieżące price_usd lub null, liquidity_usd, fetched_at, last_error). Niestandardową wycenę współdzielą sklepy w tym projekcie.
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
walletobject | nullzawsze
Niepowierniczy portfel projektu w tym blockchainie. Tokeny współdzielą natywny portfel swojego blockchaina.
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
wallet_readinessreadiness enumzawszeunsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required lub ready.Szczegóły
unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required lub ready.
receive_readinessobject | null5.5.0+
Wspólna ocena konfiguracji odbioru projektu. Obejmuje kontrole portfela i niezależnych dostawców skanera, oddzielnie od aktualności salda i gas do wysyłania. Null, jeśli brak polityki projektu. Waluta/kursy faktury są sprawdzane przy jej tworzeniu.Szczegóły
Wspólna ocena konfiguracji odbioru projektu. Obejmuje kontrole portfela i niezależnych dostawców skanera, oddzielnie od aktualności salda i gas do wysyłania. Null, jeśli brak polityki projektu. Waluta/kursy faktury są sprawdzane przy jej tworzeniu.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
Uwagi dotyczące użycia
- Token może być globalnie widoczny na liście, ale nadal niemożliwy do wybrania, gdy scanner_ready lub payment_supported ma wartość false.
- Macierz możliwości operatora wymaga też dokładnej roli punktu końcowego skanera; sprawny punkt końcowy udostępniający niezgodne API nie jest wliczany.
- Tokeny współdzielą portfel projektu swojego natywnego blockchaina; nie tworzą kolejnej frazy odzyskiwania.
- Osadzone podsumowania portfeli dotyczą wyłącznie gotowości i pozostawiają salda puste; użyj GET /v1/projects/{project_id}/wallets, aby uzyskać rozszerzone salda.
Błędy
PUTZaktualizuj politykę aktywów projektu/v1/projects/{project_id}/payment-assets/{asset_id}Odczyt + zapis
Tworzy lub zastępuje politykę projektu dla jednego trwałego aktywa i zwraca odświeżoną listę aktywów projektu. Wyłączenie natywnego blockchaina sprawia, że jego natywne aktywo i tokeny są niedostępne dla nowych faktur, ale zachowuje polityki tokenów, portfele i wybory sklepów, aby można było je później wznowić.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Content-Type | wymagane | application/json |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request PUT \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{ "asset": { "id": "ASSET_UUID", "symbol": "USDC", "asset_kind": "token", "scanner_ready": true }, "policy": { "enabled": true, "finality_mode": "confirmations", "required_confirmations": 2, "monitoring_minutes": 60, "late_monitoring_days": 30 }, "wallet_readiness": "ready" }
]
}Pola odpowiedzi
data[]object[]
assetobjectzawsze
Trwale zapisane aktywo natywne lub zweryfikowany token.
asset_kindnative | tokenzawszeCzy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.
payment_railstringzawszeKanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.
coingecko_idstring | nullzawszeTożsamość wykrywania/wyceny. Null dla niestandardowych kontraktów; nigdy nie wnioskuj ceny rynkowej z ich symbolu. Same metadane CoinGecko nigdy nie umożliwiają wyboru tokena.
custom_tokenbooleanzawszeNiestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.
token_standarderc20 | spl-token | nullzawszeZweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.
metadata_verified_attimestamp | nullzawszeCzas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.
payment_supportedbooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
scanner_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
balance_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
default_finality_modeconfirmations | finalizedzawszeDomyślny model ostateczności dziedziczony przez nową politykę projektu.
policyobject | nullzawsze
Polityka aktywacji/ostateczności projektu lub null, jeśli nieskonfigurowana. Zawiera custom_price_mode (fixed/dex), custom_price_usd (stały ciąg dziesiętny lub null), custom_dex_pair (wybrana pula lub null) i custom_dex (dex_id, quote_symbol, bieżące price_usd lub null, liquidity_usd, fetched_at, last_error). Niestandardową wycenę współdzielą sklepy w tym projekcie.Szczegóły
Polityka aktywacji/ostateczności projektu lub null, jeśli nieskonfigurowana. Zawiera custom_price_mode (fixed/dex), custom_price_usd (stały ciąg dziesiętny lub null), custom_dex_pair (wybrana pula lub null) i custom_dex (dex_id, quote_symbol, bieżące price_usd lub null, liquidity_usd, fetched_at, last_error). Niestandardową wycenę współdzielą sklepy w tym projekcie.
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
walletobject | nullzawsze
Niepowierniczy portfel projektu w tym blockchainie. Tokeny współdzielą natywny portfel swojego blockchaina.
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
wallet_readinessreadiness enumzawszeunsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required lub ready.Szczegóły
unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required lub ready.
receive_readinessobject | null5.5.0+
Wspólna ocena konfiguracji odbioru projektu. Obejmuje kontrole portfela i niezależnych dostawców skanera, oddzielnie od aktualności salda i gas do wysyłania. Null, jeśli brak polityki projektu. Waluta/kursy faktury są sprawdzane przy jej tworzeniu.Szczegóły
Wspólna ocena konfiguracji odbioru projektu. Obejmuje kontrole portfela i niezależnych dostawców skanera, oddzielnie od aktualności salda i gas do wysyłania. Null, jeśli brak polityki projektu. Waluta/kursy faktury są sprawdzane przy jej tworzeniu.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
Uwagi dotyczące użycia
- Treść całkowicie zastępuje politykę i odrzuca nieznane pola.
- Włączenie w projekcie samo w sobie nie wybiera aktywa dla żadnego sklepu.
Błędy
GETPrzeglądaj kandydatów na tokeny płatnicze/v1/projects/{project_id}/payment-token-candidatesTylko odczyt
Przeszukuje lokalnie buforowane mapowania kontraktów CoinGecko tylko w blockchainach z zaimplementowanym skanerem faktur tokenowych i adapterem salda. Wyniki to kandydaci wykrywania, nie zaufane aktywa płatnicze.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Parametry zapytania
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{
"coingecko_id": "usd-coin",
"chain_slug": "ethereum",
"symbol": "USDC",
"name": "USDC",
"contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"market_cap_rank": 7,
"icon_path": "/assets/coingecko/usd-coin.png",
"current_price_usd": "1.0001",
"token_standard": "erc20",
"scanner_ready": true,
"registered_asset_id": null,
"project_enabled": false
}
]
}Pola odpowiedzi
data[]object[]
contract_addressstringzawszeDopasowany kontrakt lub mint; jest weryfikowany on-chain przed rejestracją.
market_cap_rankinteger | nullzawszePozycja wykrywania, nie sygnał zaufania ani gotowości płatności.
token_standarderc20 | spl-tokenzawszeStandard tokena obsługiwany przez wybrany adapter blockchaina.
scanner_readybooleanzawszeTrue tylko dla kandydatów na kanale tokenów zaimplementowanym w tej kompilacji.
Uwagi dotyczące użycia
- Obsługiwane adaptery tokenów: ERC-20 w Ethereum, Base, BNB Chain, HyperEVM, Avalanche, Polygon, Arbitrum i Optimism; SPL w Solana.
- Nieobsługiwane blockchainy katalogu są odrzucane zamiast pojawiać się jako możliwe do wyboru.
- Pozycja, ikona i cena CoinGecko to orientacyjne dane wykrywania.
Błędy
POSTZweryfikuj i zarejestruj token/v1/projects/{project_id}/payment-token-assetsOdczyt + zapis
Dodaje jednego bieżącego kandydata do trwałego rejestru płatności dopiero po zweryfikowaniu przez skonfigurowane węzły tożsamości blockchaina, kontraktu/mint, liczby miejsc dziesiętnych i użytecznego zapytania o saldo. Rejestracja nigdy nie ufa samym metadanym CoinGecko, a każdy projekt ma limit 20 zarejestrowanych aktywów tokenowych.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Content-Type | wymagane | application/json |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
chain_slugstringwymaganeethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism lub solana.
coingecko_idstringwymaganeDokładna tożsamość kandydata zwrócona przez wyszukiwanie tokenów. Zachowaj początkowe podkreślenia lub łączniki, takie jak _ lub -6. Nie wyprowadzaj tego identyfikatora z nazwy ani symbolu tokena.Szczegóły
Dokładna tożsamość kandydata zwrócona przez wyszukiwanie tokenów. Zachowaj początkowe podkreślenia lub łączniki, takie jak _ lub -6. Nie wyprowadzaj tego identyfikatora z nazwy ani symbolu tokena.
Odpowiedź 201 application/json
Przykładowa odpowiedź
{
"data": {
"asset_id": "44444444-4444-4444-8444-444444444444",
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"token_standard": "erc20",
"symbol": "USDC",
"name": "USDC",
"decimals": 6,
"enabled": true,
"metadata_verified_at": "2026-08-31T18:00:00Z"
}
}Pola odpowiedzi
dataobject
Uwagi dotyczące użycia
- Włącz natywne aktywo projektu w danym blockchainie przed rejestracją jego tokenów.
- Projekt może zarejestrować najwyżej 20 aktywów tokenowych; nowy kandydat ponad ten limit zwraca token_chain_not_ready (409). Ponowne użycie już zarejestrowanego aktywa nie zajmuje kolejnego miejsca.
- Weryfikacja węzła może trwać dłużej niż odczyt katalogu; używaj jawnego limitu czasu klienta.
- Po rejestracji wybierz aktywo dla każdego sklepu, który ma je oferować.
Błędy
GETZnajdź pule DEX niestandardowego tokena/v1/projects/{project_id}/payment-token-dex-poolsTylko odczyt
Znajdź do 12 kwalifikujących się pul według dokładnego blockchaina i kontraktu tokena bazowego przez DEX Screener, uporządkowanych według płynności. Nie rejestruje to ani nie włącza tokena.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
Parametry ścieżki
Parametry zapytania
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{"data":[{"pair_address":"0x2222222222222222222222222222222222222222","dex_id":"uniswap","quote_symbol":"WETH","price_usd":"0.25","liquidity_usd":"250000.00","fetched_at":"2026-09-09T12:00:00Z","url":"https://dexscreener.com/ethereum/0x2222222222222222222222222222222222222222"}]}Pola odpowiedzi
data[]object[]
pair_addressstringzawszeDokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.
dex_idstringzawszeDokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.
quote_symbolstringzawszeDokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.
price_usddecimal stringzawszeCena USD żądanego tokena bazowego i całkowita płynność puli. Wymagane jest co najmniej 10 000 USD płynności i transakcja w ostatniej godzinie.
liquidity_usddecimal stringzawszeCena USD żądanego tokena bazowego i całkowita płynność puli. Wymagane jest co najmniej 10 000 USD płynności i transakcja w ostatniej godzinie.
fetched_atRFC 3339 timestampzawszeCzas pobrania obserwacji dostawcy przez serwer, nie znacznik czasu transakcji on-chain.
Uwagi dotyczące użycia
- Pusta tablica data oznacza brak kwalifikującej się puli. Zwracane są tylko pule, w których dokładny żądany kontrakt jest tokenem bazowym; ceny USD po stronie kwotowanej nigdy nie są zakładane.
- Obecność na DEX nie jest audytem bezpieczeństwa. Minimalna płynność i niedawna aktywność ograniczają bezużyteczne wyceny, ale nie zapobiegają manipulacji rynkiem.
- Uniswap, PancakeSwap i inne indeksowane DEX są obsługiwane tam, gdzie istniejący skaner blockchaina obsługuje tokeny. Dostęp API pozostaje ograniczony do projektu i limitowany. Wywołania dostawcy są też wykonywane kolejno i ograniczane częstotliwościowo.
Błędy
POSTDodaj niestandardowy token lub zmień jego cenę/v1/projects/{project_id}/payment-token-assets/customOdczyt + zapis
Weryfikuje niestandardowy kontrakt przez skonfigurowane węzły blockchaina i rejestruje go bez wymagania obecności w CoinGecko. Stała cena USD lub wybrana automatyczna pula DEX należy do tego projektu, nie do symbolu ani innych projektów. Ponowienie tej samej tożsamości aktualizuje cenę w projekcie bez zmiany istniejącej polityki włączenia/wyłączenia.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Content-Type | wymagane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
chain_slugstringwymaganeethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism lub solana. Stałe dla tego kontraktu.
contract_addressstringwymaganeKontrakt ERC-20 (0x i 40 znaków szesnastkowych) lub klasyczny mint SPL. Węzły weryfikują tożsamość sieci i dokładną liczbę miejsc dziesiętnych; liczba miejsc dziesiętnych i URL RPC podane przez wywołującego są odrzucane.Szczegóły
Kontrakt ERC-20 (0x i 40 znaków szesnastkowych) lub klasyczny mint SPL. Węzły weryfikują tożsamość sieci i dokładną liczbę miejsc dziesiętnych; liczba miejsc dziesiętnych i URL RPC podane przez wywołującego są odrzucane.
namestringwymaganeNazwa do wyświetlania (1–80 znaków) i symbol (1–16 liter/cyfr/kropek/podkreśleń/łączników, pierwszy znak alfanumeryczny). Ten punkt końcowy nie może zmieniać nazw istniejących tożsamości.Szczegóły
Nazwa do wyświetlania (1–80 znaków) i symbol (1–16 liter/cyfr/kropek/podkreśleń/łączników, pierwszy znak alfanumeryczny). Ten punkt końcowy nie może zmieniać nazw istniejących tożsamości.
symbolstringwymaganeNazwa do wyświetlania (1–80 znaków) i symbol (1–16 liter/cyfr/kropek/podkreśleń/łączników, pierwszy znak alfanumeryczny). Ten punkt końcowy nie może zmieniać nazw istniejących tożsamości.Szczegóły
Nazwa do wyświetlania (1–80 znaków) i symbol (1–16 liter/cyfr/kropek/podkreśleń/łączników, pierwszy znak alfanumeryczny). Ten punkt końcowy nie może zmieniać nazw istniejących tożsamości.
price_modefixed | dexopcjonalneDomyślnie fixed dla zgodności wstecznej. DEX używa konkretnej puli wykrytej dla dokładnego blockchaina i kontraktu.
price_usddecimal stringtryb fixedStała wartość USD JEDNEGO tokena, dodatnia, najwyżej 30 miejsc dziesiętnych, maksymalnie 1000000000000000000000000. Bez wykładnika ani liczb zmiennoprzecinkowych. Pomiń w trybie dex.
dex_pair_addressstringtryb dexAdres puli z payment-token-dex-pools. Wymagany w trybie dex; pomiń w trybie fixed. Serwer ponownie sprawdza tożsamość puli, cenę, płynność i aktywność przy każdym zapisie.Szczegóły
Adres puli z payment-token-dex-pools. Wymagany w trybie dex; pomiń w trybie fixed. Serwer ponownie sprawdza tożsamość puli, cenę, płynność i aktywność przy każdym zapisie.
Odpowiedź 200 application/json
Przykładowa odpowiedź
{"data":{"asset_id":"44444444-4444-4444-8444-444444444444"}}Pola odpowiedzi
Uwagi dotyczące użycia
- Po rejestracji wybierz asset_id w punkcie końcowym payment-assets sklepu; sama rejestracja nigdy nie włącza metody sklepu.
- Tokeny niestandardowe i katalogowe współdzielą limit 20 tokenów projektu. Ten sam kontrakt w różnych blockchainach to różne aktywa płatnicze.
- Istniejące kontrakty katalogowe zwracają 409: użyj rejestracji katalogowej, aby zachować automatyczne kursy rynkowe. Niestandardowy symbol nigdy nie zapożycza ceny tokena o tej samej nazwie.
- Stałe ceny są szacunkami operatora. Automatyczne ceny DEX to obserwacje spot z wybranej puli przez DEX Screener, nie wyrocznia odporna na manipulacje. Narzut kursowy sklepu i zaokrąglenie w górę nadal obowiązują, wraz ze świeżymi kursami fiducjarnymi. Już wystawione wyceny nie zmieniają się.
- W trybie DEX najpierw znajdź pulę, a następnie wyślij price_mode: dex i dex_pair_address, pomijając price_usd. Wspólne zadanie w tle odświeża wybrane pule co minutę. Nieudane kontrole lub ceny starsze niż pięć minut usuwają token z nowych wycen; nie ma cichego przejścia na stałą cenę ani symbol zastępczy.
- Akceptowane są tylko standardowe tokeny ERC-20 i klasyczne SPL. Token-2022/rozszerzenia i blockchainy wyłącznie natywne są odrzucane. Weryfikacja techniczna nie jest audytem bezpieczeństwa emitenta/kontraktu; tokeny z opłatą za transfer, rebasingiem lub czarnymi listami mogą zachowywać się niezgodnie.
- Ustaw limit czasu klienta na co najmniej 60 sekund. Weryfikacja jest ograniczona i może próbować zapasowych węzłów. Nieprawidłowe dane wejściowe zwracają 400; nieudane kontrole blockchaina/kontraktu 422; konflikty tożsamości lub limity 409.
Błędy
GETLista metod płatności sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assetsTylko odczyt
Wyświetla aktywa on-chain w data i oddzielną gotowość Lightning w lightning. Metody on-chain wymagają gotowych portfeli blockchaina. Lightning używa zweryfikowanego zewnętrznego połączenia odbiorczego wybranego w sklepie, niezależnie od portfela Bitcoin on-chain.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{ "asset": { "id": "ASSET_UUID", "chain_slug": "ethereum", "symbol": "USDC", "asset_kind": "token", "token_standard": "erc20", "scanner_ready": true }, "project_policy": { "enabled": true, "required_confirmations": 12 }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": 3, "effective_required_confirmations": 3, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet": { "id": "WALLET_UUID", "status": "active" }, "wallet_readiness": "ready" }
],
"lightning": { "payment_rail": "lightning", "symbol": "BTC", "asset_decimals": 11, "enabled": true, "ready": true }
}Pola odpowiedzi
data[]object[]
assetobjectzawsze
Natywne aktywo lub zweryfikowany token widoczny w projekcie.
asset_kindnative | tokenzawszeCzy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.
payment_railstringzawszeKanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.
coingecko_idstring | nullzawszeTożsamość wykrywania/wyceny. Null dla niestandardowych kontraktów; nigdy nie wnioskuj ceny rynkowej z ich symbolu. Same metadane CoinGecko nigdy nie umożliwiają wyboru tokena.
custom_tokenbooleanzawszeNiestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.
token_standarderc20 | spl-token | nullzawszeZweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.
metadata_verified_attimestamp | nullzawszeCzas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.
payment_supportedbooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
scanner_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
balance_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
default_finality_modeconfirmations | finalizedzawszeDomyślny model ostateczności dziedziczony przez nową politykę projektu.
project_policyobject | nullzawsze
Nadrzędna polityka projektu.
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
selectedbooleanzawszeCzy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.Szczegóły
Czy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.
confirmation_policyobject | nullzawsze
Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.
finality_modeconfirmations | finalizedzawszeCzy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.
project_required_confirmationsintegerzawszeBieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.
override_required_confirmationsinteger | nullzawszeLiczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.
effective_required_confirmationsintegerzawszeLiczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.
minimum_required_confirmationsintegerzawszeDolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.
walletobject | nullzawsze
Portfel blockchaina współdzielony przez aktywa natywne i tokeny.
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
wallet_readinessreadiness enumzawszeTylko status portfela/polityki; do wymagań skanera używaj receive_readiness.
receive_readinessobject | null5.5.0+
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.Szczegóły
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
Uwagi dotyczące użycia
- selected to konfiguracja on-chain; wallet_readiness określa jej bieżące spełnienie warunków.
- Element odpowiedzi lightning zawiera payment_rail: lightning, symbol: BTC, asset_decimals: 11, enabled i ready. Nigdy nie zawiera danych dostępu węzła. Konfiguruj tę metodę w panelu sklepu; aktualizacja tablicy assets nie zmienia Lightning.
- confirmation_policy dotyczy tylko metod on-chain. Lightning rozlicza się bez potwierdzeń blokowych i wymaga pełnej kwoty BOLT11, bez tolerancji płatności częściowych.
- Metody natywne i tokenowe w jednym blockchainie używają tego samego adresu docelowego faktury dla portfela tego blockchaina.
- Osadzone podsumowania portfeli dotyczą wyłącznie gotowości i pozostawiają salda puste; użyj dedykowanej trasy portfeli projektu, aby uzyskać bieżące wartości.
Błędy
PUTZastąp metody płatności sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assetsOdczyt + zapis
Atomowo zastępuje pełny uporządkowany podzbiór aktywów sklepu i zwraca odświeżoną listę. Pominięte aktywa zostają odznaczone.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Content-Type | wymagane | application/json |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request PUT \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{ "asset": { "id": "44444444-4444-4444-8444-444444444444", "symbol": "USDC" }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": null, "effective_required_confirmations": 12, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet_readiness": "ready" }
]
}Pola odpowiedzi
data[]object[]
assetobjectzawsze
Natywne aktywo lub zweryfikowany token widoczny w projekcie.
asset_kindnative | tokenzawszeCzy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.
payment_railstringzawszeKanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.
coingecko_idstring | nullzawszeTożsamość wykrywania/wyceny. Null dla niestandardowych kontraktów; nigdy nie wnioskuj ceny rynkowej z ich symbolu. Same metadane CoinGecko nigdy nie umożliwiają wyboru tokena.
custom_tokenbooleanzawszeNiestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.
token_standarderc20 | spl-token | nullzawszeZweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.
metadata_verified_attimestamp | nullzawszeCzas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.
payment_supportedbooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
scanner_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
balance_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
default_finality_modeconfirmations | finalizedzawszeDomyślny model ostateczności dziedziczony przez nową politykę projektu.
project_policyobject | nullzawsze
Nadrzędna polityka projektu.
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
selectedbooleanzawszeCzy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.Szczegóły
Czy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.
confirmation_policyobject | nullzawsze
Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.
finality_modeconfirmations | finalizedzawszeCzy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.
project_required_confirmationsintegerzawszeBieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.
override_required_confirmationsinteger | nullzawszeLiczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.
effective_required_confirmationsintegerzawszeLiczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.
minimum_required_confirmationsintegerzawszeDolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.
walletobject | nullzawsze
Portfel blockchaina współdzielony przez aktywa natywne i tokeny.
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
wallet_readinessreadiness enumzawszeTylko status portfela/polityki; do wymagań skanera używaj receive_readiness.
receive_readinessobject | null5.5.0+
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.Szczegóły
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
Uwagi dotyczące użycia
- Tablica akceptuje najwyżej 64 unikalne aktywa i pozycje wyświetlania.
- Wybory są zapisaną pożądaną konfiguracją i mogą zostać przygotowane przed wykonaniem kopii zapasowej portfela lub podczas wstrzymania blockchaina. Tworzenie faktur nadal oferuje tylko metody, których polityka projektu, nadrzędna polityka natywna, portfel i kontrole wykonawcze są gotowe.
- Wyślij pustą tablicę assets, aby nie skonfigurować żadnych metod płatności.
Błędy
PUTUstaw politykę potwierdzeń sklepu/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policyOdczyt + zapis
Ustawia lub usuwa jedno nadpisanie potwierdzeń sklepu i zwraca odświeżoną listę metod płatności. Aktywo musi być już wybrane w sklepie. Konfiguracja pozostaje dostępna, gdy projekt, sklep, blockchain lub portfel są wstrzymane.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Content-Type | wymagane | application/json |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request PUT \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"strategy": "custom",
"required_confirmations": 0
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"strategy": "custom",
"required_confirmations": 0
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"strategy": "custom",
"required_confirmations": 0
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"strategy": "custom",
"required_confirmations": 0
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{
"asset": { "id": "YOUR_ASSET_ID", "chain_slug": "bitcoin", "symbol": "BTC" },
"selected": true,
"display_order": 0,
"confirmation_policy": {
"finality_mode": "confirmations",
"project_required_confirmations": 2,
"override_required_confirmations": 0,
"effective_required_confirmations": 0,
"editable": true,
"minimum_required_confirmations": 0,
"maximum_required_confirmations": 10000
},
"wallet_readiness": "ready"
}
]
}Pola odpowiedzi
data[]object[]
assetobjectzawsze
Natywne aktywo lub zweryfikowany token widoczny w projekcie.
asset_kindnative | tokenzawszeCzy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.
payment_railstringzawszeKanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.
coingecko_idstring | nullzawszeTożsamość wykrywania/wyceny. Null dla niestandardowych kontraktów; nigdy nie wnioskuj ceny rynkowej z ich symbolu. Same metadane CoinGecko nigdy nie umożliwiają wyboru tokena.
custom_tokenbooleanzawszeNiestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.
token_standarderc20 | spl-token | nullzawszeZweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.
metadata_verified_attimestamp | nullzawszeCzas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.
payment_supportedbooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
scanner_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
balance_readybooleanzawszeWarunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.Szczegóły
Warunki rejestru sprawdzane przy kompilacji. scanner_ready oznacza zainstalowane środowisko skanera płatności; potwierdzenie płatności wymaga skonfigurowanej liczby sprawnych dostawców o dokładnej roli (domyślnie 2, opcjonalnie 1); tymczasowa dostępność skanera nie blokuje tworzenia faktur od 6.0.6. balance_ready ma wartość true tylko dla zaimplementowanych adapterów salda.
default_finality_modeconfirmations | finalizedzawszeDomyślny model ostateczności dziedziczony przez nową politykę projektu.
project_policyobject | nullzawsze
Nadrzędna polityka projektu.
enabledbooleanwymaganeWłącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.
finality_modeconfirmations | finalizedwymaganePolityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.
required_confirmationsintegerwymaganeKanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.Szczegóły
Kanały Bitcoin i EVM akceptują zero; inne kanały potwierdzeń wymagają co najmniej jednego, kanały tylko finalized wymagają dokładnie jednego, a kanały EVM są ograniczone do 0–48, aby każdy przelew pozostał w oknie odtwarzania transakcji.
selectedbooleanzawszeCzy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.Szczegóły
Czy metoda jest częścią zapisanej pożądanej konfiguracji sklepu. Jest oferowana, gdy polityka projektu, portfel, zainstalowany adapter i wycena są prawidłowe. Tymczasowe awarie skanera nie usuwają jej z nowych faktur.
confirmation_policyobject | nullzawsze
Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.
finality_modeconfirmations | finalizedzawszeCzy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.
project_required_confirmationsintegerzawszeBieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.
override_required_confirmationsinteger | nullzawszeLiczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.
effective_required_confirmationsintegerzawszeLiczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.
minimum_required_confirmationsintegerzawszeDolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.
walletobject | nullzawsze
Portfel blockchaina współdzielony przez aktywa natywne i tokeny.
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
wallet_readinessreadiness enumzawszeTylko status portfela/polityki; do wymagań skanera używaj receive_readiness.
receive_readinessobject | null5.5.0+
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.Szczegóły
Wspólna konfiguracja odbioru i akceptacja sklepu. Używa buforowanych obserwacji; nie jest rezerwacją ani gwarancją. Tworzenie ponownie sprawdza wymagania i rzeczywisty kurs faktury.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
Uwagi dotyczące użycia
- Użyj {"strategy":"inherit"}, aby usunąć nadpisanie sklepu i stosować bieżącą wartość domyślną projektu do przyszłych faktur.
- Sieci finalized zwracają editable false i używają ostateczności sieci; nie akceptują niestandardowego nadpisania liczby bloków.
- Wartość 0 oznacza akceptację przy wykryciu bez potwierdzenia sieci i ochrony przed reorganizacją. Jest akceptowana tylko tam, gdzie minimum_required_confirmations wynosi 0.
- Zmiany polityki dotyczą tylko nowych faktur. Istniejące faktury zachowują zapis polityki potwierdzeń projektu/sklepu z chwili utworzenia.
- Aktualizacje dotyczą jednego aktywa naraz; wykonuj kolejno równoczesne zmiany tego samego aktywa sklepu i używaj odświeżonej odpowiedzi jako bieżącego stanu.
Błędy
GETLista portfeli i sald projektu/v1/projects/{project_id}/walletsTylko odczyt
Zwraca publiczne metadane portfela oraz każde zarejestrowane aktywo z obsługą salda w dokładnym blockchainie i sieci portfela. Obejmuje wszystkie 30 natywnych kanałów blockchainowych; śledzone są też zweryfikowane aktywa ERC-20 i SPL. Aktywa pojawiają się natychmiast, nawet przed pierwszym skanowaniem lub gdy nie są przyjmowane jako płatność. project_enabled informuje o akceptacji płatności; tracking_active niezależnie informuje o możliwości odświeżania tylko do odczytu. Monero wymaga zewnętrznego wallet-RPC tylko do podglądu przypisanego do projektu. Funkcja Skanuj salda w panelu nadaje priorytet ograniczonym odczytom z postępem/błędami dla każdego aktywa; tylko pełne cykle aktualizują świeże sumy. Rozliczenie faktury nadal zależy od monitorowania na poziomie transakcji i polityki potwierdzeń, nie od tych buforowanych sald.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{
"id": "55555555-5555-4555-8555-555555555555",
"project_id": "11111111-1111-4111-8111-111111111111",
"native_asset_id": "10000000-0000-4000-8000-000000000003",
"chain_slug": "ethereum",
"network": "mainnet",
"asset_symbol": "ETH",
"asset_name": "Ethereum",
"status": "active",
"label": "Primary Ethereum wallet",
"public_key": "0x…",
"primary_address": "0x…",
"derivation_scheme": "bip44",
"address_format": "eip55",
"backup_confirmed_at": "2026-08-31T17:00:00Z",
"last_secret_revealed_at": null,
"secret_reveal_count": 0,
"next_receive_index": 43,
"last_scanned_height": 23123456,
"last_scanned_at": "2026-08-31T18:05:00Z",
"last_error": null,
"balances": [
{ "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000003", "project_enabled": true, "tracking_active": true, "asset_kind": "native", "contract_address": null, "symbol": "ETH", "name": "Ethereum", "decimals": 18, "coingecko_id": "ethereum", "balance": "0.125", "balance_atomic": "125000000000000000", "price_usd": "4500", "value_usd": "562.50", "status": "fresh", "checked_at": "2026-08-31T18:05:00Z", "last_error": null },
{ "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000099", "project_enabled": false, "tracking_active": true, "asset_kind": "token", "contract_address": "0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48", "symbol": "USDC", "name": "USDC", "decimals": 6, "coingecko_id": "usd-coin", "balance": null, "balance_atomic": null, "price_usd": "1", "value_usd": null, "status": "pending", "checked_at": null, "last_error": null }
],
"total_value_usd": "562.50",
"balance_status": "fresh",
"balance_checked_at": "2026-08-31T18:05:00Z",
"recent_payments": [
{ "invoice_public_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50", "chain_slug": "ethereum", "symbol": "USDC", "transaction_id": "0x…", "event_index": 0, "amount": "25", "status": "final", "confirmations": 12, "observed_at": "2026-08-31T18:04:00Z" }
],
"created_at": "2026-08-31T16:00:00Z",
"updated_at": "2026-08-31T18:05:00Z"
}
]
}Pola odpowiedzi
data[]object[]
project_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
native_asset_idUUIDzawszeIdentyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.
public_keystring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
primary_addressstring | nullzawszePubliczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.
backup_confirmed_attimestamp | nullzawszeWartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.
activation_requiredbooleanzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
activation_verified_attimestamp|nullzawszeWspółdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.Szczegóły
Współdzielone konta XRP i Stellar pozostają niedostępne, dopóki operator nie zasili wyświetlonego adresu, a skonfigurowani dostawcy skanera nie zweryfikują dokładnie tego konta. Trwały dowód nie wygasa; bieżący stan skanera jest sprawdzany oddzielnie do weryfikacji płatności, nie tworzenia faktur.
receive_readinessobject | null5.5.0+
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.Szczegóły
Dołączane do list portfeli: konfiguracja odbioru projektu i wymagania skanera blockchaina. Oddzielne od sald, gas tokenów i gotowości wysyłania. Inne odpowiedzi portfela mogą pozostawić null.
readybooleanzawszeKontrole konfiguracji odbioru przeszły pomyślnie. Nie opisuje gotowości wydawania środków, gas, odświeżania salda ani gwarantowanej przyszłej wyceny.
invoice_creatableboolean6.0.6+Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.Szczegóły
Konfiguracja zezwala na metodę faktury mimo tymczasowych ostrzeżeń skanera. Wycena waluty jest sprawdzana przy tworzeniu. To nie weryfikacja płatności: ready może być false, gdy invoice_creatable jest true. Brak portfeli, wyłączona polityka i nieobsługiwane adaptery nadal bezpiecznie powodują błąd.
checked_attimestampzawszeCzas oceny. Listowanie nie wykonuje żądania sieciowego ani nie przydziela adresu.
issues[]object[]zawsze
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.Szczegóły
Puste, gdy gotowe; w przeciwnym razie ostrzeżenie odbioru lub blokada konfiguracji. Sprawdź invoice_creatable, aby odróżnić tymczasowe ostrzeżenia skanera od błędów konfiguracji faktury.
chain_slugstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_idUUIDgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
asset_tickerstringgdy znaneIdentyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.
reason_codestringzawszescanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.Szczegóły
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled lub asset_not_accepted.
messagestringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
actionstringgdy dostępneWyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.Szczegóły
Wyjaśnienie dla sprzedawcy i identyfikator działania: chain_connections, wallets, rates, payment_methods, project_settings lub store_settings. Bez danych dostępu ani prywatnych adresów dostawców.
required_endpoint_rolestring | nullon-chainPreferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.Szczegóły
Preferowana rola API skanera (starsze pole). Używaj accepted_endpoint_roles, aby uzyskać pełną listę zgodności. Podstawowa sprawność węzła nie dowodzi obsługi historii płatności.
accepted_endpoint_roles[]string[] | nullon-chainZgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.Szczegóły
Zgodne dialekty API, nie dowód historii ani wydajności punktu końcowego. Surowe node-rpc obsługuje BTC/BCH/LTC/DOGE/DASH i przejrzyste ZEC (kompletne zdekodowane bloki, 1–48 potwierdzeń), utrwalone natywne TRX, natywne ALGO przez algod, XTZ przez Octez, sfinalizowane DOT Asset Hub przez metadane SCALE oraz natywne XLM przez Stellar RPC z identyfikatorem memo faktury. Przycięta lub niepełna historia nie kwalifikuje się. Te surowe adaptery nie dodają kanałów tokenów. Indeksowane API pozostają alternatywami; zobacz tabelę kanałów poniżej. Mieszane źródła surowe/indeksowane niezależnie weryfikują ograniczone okna; domyślnie nadal wymaganych jest dwóch niezależnych dostawców, nie aliasy jednego operatora. Podstawowa wysokość węzła, informacje o blockchainie ORDnet i przekaźnik EVM dla kanału innego niż EVM nie są dowodami odbioru. Monero nadal wymaga wallet-RPC tylko do podglądu przypisanego do projektu.
healthy_endpointsintegeron-chainSprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.
usable_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
required_independent_providersintegeron-chainUżyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.Szczegóły
Użyteczne miejsca weryfikacji, maksymalnie dwa. required_independent_providers to ustawienie blockchaina: domyślnie 2 lub 1 po wyraźnym wyborze administratora. W trybie dwóch dostawców wymagane są różne klucze dostawców ORAZ hosty. Źródła wyłączone, nieaktualne (ponad dziesięć minut) lub objęte przerwą nie zajmują miejsca. Lightning używa własnych zasad połączeń.
last_checked_attimestamp | nullon-chainOstatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.
monero_wallet_rpcMoneroWalletRpcBinding | nullzawszeOczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.Szczegóły
Oczyszczony stan powiązania zewnętrznego wallet-RPC Monero tylko do podglądu. Zawiera punkt końcowy, tryb uwierzytelniania, główny adres konta 0, techniczne flagi/wysokości dowodów i znaczniki czasu poświadczeń operatora; dane dostępu, klucze i pliki portfela nigdy nie są serializowane.
balances[]object[]zawsze
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.Szczegóły
Buforowane salda każdego z 30 natywnych kanałów blockchainowych oraz zweryfikowanych aktywów ERC-20 i SPL. Monero wymaga skonfigurowanego zewnętrznego wallet-RPC tylko do podglądu.
active_store_countintegerzawszeLiczba włączonych sklepów, które obecnie wybierają to aktywo. To odwzorowanie akceptacji; śledzenie salda tylko do odczytu pozostaje niezależne.
active_store_ids[]UUID[]zawszeWłączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.
tracking_activebooleanzawszeCzy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.Szczegóły
Czy ten portfel z obsługą odczytu i zarejestrowane aktywo tego samego blockchaina kwalifikują się do odświeżania salda w tle. Przełączniki projektu i akceptacji metod płatności nie wstrzymują śledzenia tylko do odczytu.
balancedecimal string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
balance_atomicinteger string|nullzawszeDokładne saldo wyświetlane i atomowe obejmujące główny adres portfela i wydane adresy faktur. Null, gdy pełna wartość jest niedostępna.
price_usddecimal string | nullzawszeOrientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.
statuspending | refreshing | fresh | stale | errorzawszeBuforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.Szczegóły
Buforowany stan skanowania. refreshing może zachowywać ukończone saldo: do ustalenia wieku użyj checked_at. Pending oznacza brak ukończonego zapisu stanu. Żaden z tych stanów nie dowodzi oczekującego przelewu ani rozliczenia faktury.
balance_statuspending | refreshing | fresh | stale | error | unknownzawszeZbiorcza aktualność pamięci podręcznej; unknown to ostrożny stan zastępczy i żaden z tych stanów nie dowodzi rozliczenia faktury.
balance_checked_attimestamp | nullzawszeNajstarsza istotna udana kontrola salda uwzględniona w agregacie.
recent_payments[]object[]zawsze
Do trzech najnowszych prawidłowych obserwacji detected, confirming lub final przypisanych dokładnie do tego portfela.
statusdetected | confirming | finalzawszeBieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.
Uwagi dotyczące użycia
- Ta trasa bearer nigdy nie zwraca frazy odzyskiwania, klucza prywatnego, zaszyfrowanego sekretu ani metody wydawania środków.
- Nowo zarejestrowane aktywo tego samego blockchaina jest zwracane z saldami null i statusem pending przed pierwszym ukończonym skanowaniem; nigdy nie jest raportowane jako fikcyjne zero.
- Wyłączenie projektu, portfela do akceptacji płatności, natywnego kanału lub pojedynczego aktywa nie zatrzymuje śledzenia sald tylko do odczytu: aktywne i wyłączone portfele z głównym adresem nadal odświeżają każde zarejestrowane obsługiwane aktywo tego samego blockchaina. Portfele pending i error nie są skanowane.
- project_enabled informuje tylko o polityce akceptacji aktywa w projekcie i może mieć wartość false, gdy tracking_active pozostaje true.
- balance i balance_atomic są dokładnymi ciągami; price_usd, value_usd i total_value_usd są orientacyjne i mogą mieć wartość null. Świeży status salda nie gwarantuje świeżej ceny rynkowej.
- Wycena wartości preferuje ceny CoinGecko do dwóch godzin. Monety natywne i zweryfikowane kanoniczne USDC/USDT mogą awaryjnie używać włączonych notowań USD Kraken/Binance do pięciu minut, najpierw głównego dostawcy. Bez zakładania powiązania z dolarem ani wyceny niestandardowych tokenów wyłącznie po symbolu; stałe ceny/DEX projektu pozostają oddzielne. Wyceny faktur nie zmieniają się.
- Pending nie ma pełnego zapisu stanu. Refreshing zachowuje ostatnią ukończoną kwotę i checked_at; nie oznacza oczekującego przelewu blockchainowego. Kwoty stale/error też mogą zachować starsze wartości. Nigdy nie traktuj niedostępnej pamięci podręcznej jako zera ani brakującej płatności. Rutynowe odświeżenia EVM/Solana używają ponownie niedawno sprawdzonych pustych adresów przez do 30 minut między audytami, a adresy zasilone, nowe i zmienione sprawdzają ponownie. Jawna funkcja Skanuj salda w panelu żąda pełnego skanowania.
- recent_payments jest ograniczone do trzech obserwacji na portfel i wyklucza unieważnioną historię.
Błędy
POSTUtwórz fakturę/v1/projects/{project_id}/stores/{store_id}/invoicesOdczyt + zapis
Tworzy fakturę atomowo z adresami docelowymi portfeli, świeżymi dokładnymi wycenami, historią audytu i wpisami skrzynki nadawczej powiadomień. Odtworzenie identycznych bajtów surowej treści z tymi samymi danymi dostępu i Idempotency-Key zwraca pierwotną fakturę.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Idempotency-Key | wymagane | Unikalne 1–128 widocznych znaków ASCII bez białych znaków. |
| Content-Type | zalecane | application/json. Obecny handler surowej treści parsuje JSON bez wymuszania typu mediów. |
| Accept | zalecane | application/json |
Parametry ścieżki
project_idUUIDwymaganeSkopiuj identyfikator API projektu z Projekt → Ustawienia → Identyfikatory API. Musi być przypisany do danych dostępu; czytelny identyfikator projektu nie jest akceptowany.
store_idUUIDwymaganeSkopiuj identyfikator API sklepu z Projekt → Sklepy → wybierz sklep → Podstawowe → Identyfikatory API. Wymagany nawet dla domyślnego sklepu; sklep musi być włączony i należeć do project_id.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: order-1042-attempt-1' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "49.90",
"currency": "USD"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"amount": "49.90",
"currency": "USD"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"amount": "49.90",
"currency": "USD"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "49.90",
"currency": "USD"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response)): "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: order-1042-attempt-1' \
--header 'Content-Type: application/json' \
--data-raw '{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"language": "en",
"metadata": {
"cart_id": "cart-681",
"firstname": "Ada",
"lastname": "Lovelace",
"street": "12 Example Street",
"street2": "Suite 2",
"zip": "10115",
"city": "Berlin",
"country": "Germany",
"countryiso2": "DE",
"company": "Example GmbH",
"vatid": "DE123456789"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"language": "en",
"metadata": {
"cart_id": "cart-681",
"firstname": "Ada",
"lastname": "Lovelace",
"street": "12 Example Street",
"street2": "Suite 2",
"zip": "10115",
"city": "Berlin",
"country": "Germany",
"countryiso2": "DE",
"company": "Example GmbH",
"vatid": "DE123456789"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"language": "en",
"metadata": {
"cart_id": "cart-681",
"firstname": "Ada",
"lastname": "Lovelace",
"street": "12 Example Street",
"street2": "Suite 2",
"zip": "10115",
"city": "Berlin",
"country": "Germany",
"countryiso2": "DE",
"company": "Example GmbH",
"vatid": "DE123456789"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"language": "en",
"metadata": {
"cart_id": "cart-681",
"firstname": "Ada",
"lastname": "Lovelace",
"street": "12 Example Street",
"street2": "Suite 2",
"zip": "10115",
"city": "Berlin",
"country": "Germany",
"countryiso2": "DE",
"company": "Example GmbH",
"vatid": "DE123456789"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Treść żądania
amountstringwymaganeZwykły ciąg dziesiętny bez znaku; bez znaku ani wykładnika, do 48 cyfr części całkowitej i 30 miejsc dziesiętnych. Domyślnie musi być dodatni. Sklep może zezwolić na faktury zerowe w Sklepy → Faktura; zerowe sumy rozliczają się bez otrzymania środków, przydzielania adresów ani opłat za przetwarzanie.Szczegóły
Zwykły ciąg dziesiętny bez znaku; bez znaku ani wykładnika, do 48 cyfr części całkowitej i 30 miejsc dziesiętnych. Domyślnie musi być dodatni. Sklep może zezwolić na faktury zerowe w Sklepy → Faktura; zerowe sumy rozliczają się bez otrzymania środków, przydzielania adresów ani opłat za przetwarzanie.
currencystring | nullopcjonalneObsługiwana trzyliterowa waluta fiducjarna, normalizowana do wielkich liter. Pominięcie lub null dziedziczy walutę faktur sklepu. Tworzenie wymaga też niezależnie dostępnego kursu przeliczenia rozliczeń.Szczegóły
Obsługiwana trzyliterowa waluta fiducjarna, normalizowana do wielkich liter. Pominięcie lub null dziedziczy walutę faktur sklepu. Tworzenie wymaga też niezależnie dostępnego kursu przeliczenia rozliczeń.
payment_methods[]object[] | nullopcjonalne
Wybierz dla tej faktury metody włączone w sklepie. Merchant 5.4.0+: pomijaj nieznane/nieaktywne/nieakceptowane opcje; jeśli żadna nie pasuje, użyj ustawień domyślnych sklepu. Pominięcie/null też używa ustawień domyślnych; [] jest nieprawidłowe. Nigdy nie włącza metody ani nie zmienia ustawień sklepu. Zobacz schemat wyboru poniżej.Szczegóły
Wybierz dla tej faktury metody włączone w sklepie. Merchant 5.4.0+: pomijaj nieznane/nieaktywne/nieakceptowane opcje; jeśli żadna nie pasuje, użyj ustawień domyślnych sklepu. Pominięcie/null też używa ustawień domyślnych; [] jest nieprawidłowe. Nigdy nie włącza metody ani nie zmienia ustawień sklepu. Zobacz schemat wyboru poniżej.
chain_slugstringwymaganeSkopiuj chain_slug w Projekt → Sklepy → Metody płatności lub odczytaj go z GET /v1/projects/{project_id}/stores/{store_id}/payment-assets, np. ethereum, base lub bitcoin. Para blockchain/kanał może wystąpić tylko raz.Szczegóły
Skopiuj chain_slug w Projekt → Sklepy → Metody płatności lub odczytaj go z GET /v1/projects/{project_id}/stores/{store_id}/payment-assets, np. ethereum, base lub bitcoin. Para blockchain/kanał może wystąpić tylko raz.
asset_ids[]UUID[] | nullopcjonalneUUID asset.id aktywów on-chain, nie adresy kontraktów ani identyfikatory metod płatności faktury. Użyj tego LUB asset_tickers. Pomiń oba selektory, aby wybrać wszystkie aktywne akceptowane aktywa tego blockchaina. [] i zduplikowane/zerowe identyfikatory są nieprawidłowe. W 5.4.0+ pomijaj identyfikatory nieaktywne/nieakceptowane w tym blockchainie i sklepie; całkowicie niedopasowany wybór używa ustawień domyślnych sklepu.Szczegóły
UUID asset.id aktywów on-chain, nie adresy kontraktów ani identyfikatory metod płatności faktury. Użyj tego LUB asset_tickers. Pomiń oba selektory, aby wybrać wszystkie aktywne akceptowane aktywa tego blockchaina. [] i zduplikowane/zerowe identyfikatory są nieprawidłowe. W 5.4.0+ pomijaj identyfikatory nieaktywne/nieakceptowane w tym blockchainie i sklepie; całkowicie niedopasowany wybór używa ustawień domyślnych sklepu.
asset_tickers[]string[] | nullopcjonalneMerchant 5.3.0+. Symbole takie jak BTC, USDC lub PEPE, ograniczone do chain_slug i tego sklepu. 1–64 unikalne symbole; przycinanie/bez rozróżniania wielkości liter, 1–40 znaków ASCII: liter/cyfr/kropek/podkreśleń/łączników. Użyj tego LUB asset_ids. W 5.4.0+ pomijaj nieznane/nieaktywne/nieakceptowane symbole. Niejednoznaczne akceptowane symbole nadal powodują błąd: użyj asset_ids. Aktywne wybrane metody wymagają prawidłowych portfeli i wyceny; tymczasowe awarie skanera on-chain nie blokują tworzenia od 6.0.6. Lightning opcjonalnie akceptuje tylko BTC.Szczegóły
Merchant 5.3.0+. Symbole takie jak BTC, USDC lub PEPE, ograniczone do chain_slug i tego sklepu. 1–64 unikalne symbole; przycinanie/bez rozróżniania wielkości liter, 1–40 znaków ASCII: liter/cyfr/kropek/podkreśleń/łączników. Użyj tego LUB asset_ids. W 5.4.0+ pomijaj nieznane/nieaktywne/nieakceptowane symbole. Niejednoznaczne akceptowane symbole nadal powodują błąd: użyj asset_ids. Aktywne wybrane metody wymagają prawidłowych portfeli i wyceny; tymczasowe awarie skanera on-chain nie blokują tworzenia od 6.0.6. Lightning opcjonalnie akceptuje tylko BTC.
payment_railonchain | lightningopcjonalneDomyślnie onchain. Aby wybrać Bitcoin Lightning, użyj {chain_slug: bitcoin, payment_rail: lightning} bez asset_ids; asset_tickers może opcjonalnie wynosić [BTC]. Bitcoin on-chain nie obejmuje Lightning. Połączenie Lightning sklepu musi już być włączone i gotowe.Szczegóły
Domyślnie onchain. Aby wybrać Bitcoin Lightning, użyj {chain_slug: bitcoin, payment_rail: lightning} bez asset_ids; asset_tickers może opcjonalnie wynosić [BTC]. Bitcoin on-chain nie obejmuje Lightning. Połączenie Lightning sklepu musi już być włączone i gotowe.
order_idstring | nullopcjonalneIdentyfikator zamówienia sprzedawcy, 1–128 znaków po przycięciu; znaki sterujące są odrzucane.
emailstring | nullopcjonalneE-mail klienta tylko dla sprzedawcy, normalizowany do praktycznego adresu ASCII o długości najwyżej 254 znaków. Pominięcie lub null nie zapisuje e-maila.
descriptionstring | nullopcjonalneOpis widoczny dla klienta, 1–500 znaków; dozwolone są podziały wierszy i tabulatory.
expires_in_secondsinteger | nullopcjonalneCzas ważności wyceny faktury od 300 do 86 400 sekund; pominięcie lub null dziedziczy politykę sklepu.
exchange_rate_spread_percentdecimal string | nullopcjonalneNarzut wyceny od 0 do 100, z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu; "0" wyłącza go dla tej faktury. Stosowany przed zaokrągleniem w górę, potem blokowany. Nie zmienia kwoty faktury w walucie fiducjarnej ani podstawy opłaty za przetwarzanie.Szczegóły
Narzut wyceny od 0 do 100, z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu; "0" wyłącza go dla tej faktury. Stosowany przed zaokrągleniem w górę, potem blokowany. Nie zmienia kwoty faktury w walucie fiducjarnej ani podstawy opłaty za przetwarzanie.
underpayment_tolerance_percentdecimal string | nullopcjonalneAkceptowana niedopłata od 0 do 99.99 z najwyżej dwoma miejscami po przecinku. Pominięcie lub null dziedziczy wartość domyślną sklepu.
ipn_urlstring | nullopcjonalnePubliczne wywołanie zwrotne HTTPS, najwyżej 2048 bajtów, bez danych dostępu ani fragmentu. Zastępuje wartość domyślną sklepu; null/pominięcie ją dziedziczy.
redirect_urlstring | nullopcjonalneAdres HTTPS sukcesu używany po rozliczeniu, najwyżej 2048 bajtów, bez osadzonych danych dostępu. Pominięcie lub null dziedziczy wartość domyślną sklepu i nie może jej wyczyścić.
cancel_urlstring | nullopcjonalneAdres powrotny HTTPS używany po zakończeniu płatności bez sukcesu. Pominięcie lub null dziedziczy wartość domyślną sklepu i nie może jej wyczyścić.
redirect_automaticallyboolean | nullopcjonalnePominięcie lub null dziedziczy politykę sklepu. true wymaga obowiązującego redirect_url.
languagestring | nullopcjonalneJęzyk klienta: en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja. pt oznacza portugalski brazylijski, a zh - chiński uproszczony. Obsługiwane znaczniki regionalne, takie jak de-DE, są normalizowane do wymienionego języka. Pominięcie lub null dziedziczy język sklepu. Język panelu jest oddzielny.Szczegóły
Język klienta: en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja. pt oznacza portugalski brazylijski, a zh - chiński uproszczony. Obsługiwane znaczniki regionalne, takie jak de-DE, są normalizowane do wymienionego języka. Pominięcie lub null dziedziczy język sklepu. Język panelu jest oddzielny.
checkout_appearanceobject | nullopcjonalne
Częściowe ustawienia prezentacji tej faktury. Pominięcie/null używa bieżącego wyglądu sklepu. Obiekt, w tym {}, zamraża wynikowy wygląd i obrazy przy tworzeniu. Zobacz schemat nadpisania poniżej; bez ustawień finansowych, HTML, CSS, JavaScript ani zdalnych adresów obrazów.Szczegóły
Częściowe ustawienia prezentacji tej faktury. Pominięcie/null używa bieżącego wyglądu sklepu. Obiekt, w tym {}, zamraża wynikowy wygląd i obrazy przy tworzeniu. Zobacz schemat nadpisania poniżej; bez ustawień finansowych, HTML, CSS, JavaScript ani zdalnych adresów obrazów.
inherit_default_storebooleanopcjonalnetrue wybiera wygląd domyślnego sklepu projektu jako bazę; w przeciwnym razie używa efektywnego wyglądu sklepu docelowego. Następnie nadpisania są stosowane i zapisywane niezależnie; wynikowa flaga faktury to false.Szczegóły
true wybiera wygląd domyślnego sklepu projektu jako bazę; w przeciwnym razie używa efektywnego wyglądu sklepu docelowego. Następnie nadpisania są stosowane i zapisywane niezależnie; wynikowa flaga faktury to false.
introstringopcjonalneZwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.Szczegóły
Zwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.
outrostringopcjonalneZwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.Szczegóły
Zwykły tekst, do 2000 znaków każdy. Wstęp pojawia się u góry, zakończenie u dołu w każdym stanie. Nowe wiersze są zachowywane; bezpieczne adresy tekstowe stają się linkami. Pusty ciąg czyści. Starsze customer_message jest akceptowane jako alias intro; nie wysyłaj obu.
intro_font_sizeintegeropcjonalnePiksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.
outro_font_sizeintegeropcjonalnePiksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.
accent_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
background_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
card_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
button_colorstringopcjonalne#RRGGBB. Tło, karta i przycisk mogą być puste dla automatycznych kolorów. Kontrast tekstu jest automatyczny.
imagesobjectopcjonalne
Klucze logo_light, logo_dark, favicon. Pominięty klucz zachowuje obraz bazowy; null go usuwa. Obiekt {store_id: UUID, kind?: logo_light|logo_dark|favicon} wykorzystuje efektywny przesłany obraz tego sklepu w TYM SAMYM projekcie. kind domyślnie odpowiada kluczowi docelowemu. Najpierw prześlij w Sklep → Strona płatności; skopiuj identyfikator API sklepu z Podstawowe → Identyfikatory API. Brak obrazów lub identyfikatory z innego projektu zwracają 400. Zewnętrzne URL ani dane obrazów nie są akceptowane.Szczegóły
Klucze logo_light, logo_dark, favicon. Pominięty klucz zachowuje obraz bazowy; null go usuwa. Obiekt {store_id: UUID, kind?: logo_light|logo_dark|favicon} wykorzystuje efektywny przesłany obraz tego sklepu w TYM SAMYM projekcie. kind domyślnie odpowiada kluczowi docelowemu. Najpierw prześlij w Sklep → Strona płatności; skopiuj identyfikator API sklepu z Podstawowe → Identyfikatory API. Brak obrazów lub identyfikatory z innego projektu zwracają 400. Zewnętrzne URL ani dane obrazów nie są akceptowane.
logo_lightobject | nullopcjonalne
logo_darkobject | nullopcjonalne
show_order_idbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
show_descriptionbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
details_expandedbooleanopcjonalnePokaż szczegóły identyfikatora zamówienia i opis zwykłym tekstem pod tytułem. details_expanded otwiera szczegóły identyfikatora zamówienia od razu. Tylko wyświetlanie, nie usuwanie danych.
show_project_namebooleanopcjonalneMerchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.Szczegóły
Merchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.
show_store_namebooleanopcjonalneMerchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.Szczegóły
Merchant 5.6.0+: pokaż lub ukryj każdą nazwę w nagłówku strony płatności klienta. Obie domyślnie mają wartość true. Dostępne też w Sklep → Strona płatności; dziedziczone i zapisywane w stanie faktury jak inne ustawienia wyglądu. Tylko wyświetlanie, nie usuwanie danych.
featured_chains[]string[]opcjonalneUporządkowane slugi blockchainów, najwyżej 60 unikalnych wartości (małe litery, cyfry, łączniki; do 64 znaków). [] czyści. Zmieniana jest kolejność tylko dostępnych metod faktury.Szczegóły
Uporządkowane slugi blockchainów, najwyżej 60 unikalnych wartości (małe litery, cyfry, łączniki; do 64 znaków). [] czyści. Zmieniana jest kolejność tylko dostępnych metod faktury.
featured_asset_ids[]UUID[]opcjonalneDo 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.Szczegóły
Do 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.
default_asset_idUUID|nullopcjonalneDo 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.Szczegóły
Do 100 unikalnych uporządkowanych identyfikatorów aktywów; [] czyści. Domyślne aktywo może mieć wartość null. Identyfikatory pochodzą z payment-assets, nie są identyfikatorami intencji płatności. Nigdy nie włączają metod; otrzymane płatności i prawidłowe preferencje klienta mają pierwszeństwo.
messagesobjectopcjonalne
Obiekty językowe z kluczami en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja, zawierające zwykłe ciągi waiting, confirming, paid, underpaid, expired (po 500 znaków). Zmieniają się tylko podane języki/stany; {} czyści wszystkie komunikaty, {en:{}} czyści angielski, a pusty ciąg stanu czyści ten stan. Angielski jest językiem awaryjnym. Nie zastępuje rzeczywistego statusu.Szczegóły
Obiekty językowe z kluczami en, de, es, pt-BR, it, ru, zh-CN, fr, ko lub ja, zawierające zwykłe ciągi waiting, confirming, paid, underpaid, expired (po 500 znaków). Zmieniają się tylko podane języki/stany; {} czyści wszystkie komunikaty, {en:{}} czyści angielski, a pusty ciąg stanu czyści ten stan. Angielski jest językiem awaryjnym. Nie zastępuje rzeczywistego statusu.
enobjectopcjonalne
deobjectopcjonalne
esobjectopcjonalne
pt-BRobjectopcjonalne
itobjectopcjonalne
ruobjectopcjonalne
zh-CNobjectopcjonalne
frobjectopcjonalne
koobjectopcjonalne
support_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
terms_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
privacy_urlstringopcjonalneAdresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.
return_button_textstringopcjonalneEtykieta do 60 znaków. Do zachowania faktury używaj najwyższego poziomu redirect_url/cancel_url/redirect_automatically/language.
show_return_buttonbooleanopcjonalnePokaż ręczny przycisk Powrót do sprzedawcy/anulowania na stronie płatności, także w stanach końcowych. Pomiń, aby odziedziczyć wygląd sklepu (domyślnie true); false go ukrywa. Nie anuluje faktury, nie ukrywa adresów URL w JSON ani nie wyłącza automatycznych przekierowań po sukcesie. W razie potrzeby oddzielnie ustaw redirect_automatically najwyższego poziomu na false. Wymaga oprogramowania sprzedawcy 8.1.4 lub nowszego.Szczegóły
Pokaż ręczny przycisk Powrót do sprzedawcy/anulowania na stronie płatności, także w stanach końcowych. Pomiń, aby odziedziczyć wygląd sklepu (domyślnie true); false go ukrywa. Nie anuluje faktury, nie ukrywa adresów URL w JSON ani nie wyłącza automatycznych przekierowań po sukcesie. W razie potrzeby oddzielnie ustaw redirect_automatically najwyższego poziomu na false. Wymaga oprogramowania sprzedawcy 8.1.4 lub nowszego.
metadataobject | nullopcjonalne
Obiekt JSON tylko dla sprzedawcy; pominięcie lub null staje się {}, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia. firstname, lastname, street, street2, zip, city, country, countryiso2, company i vatid są walidowane, normalizowane i odwzorowywane w polach podsumowania klienta.Szczegóły
Obiekt JSON tylko dla sprzedawcy; pominięcie lub null staje się {}, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia. firstname, lastname, street, street2, zip, city, country, countryiso2, company i vatid są walidowane, normalizowane i odwzorowywane w polach podsumowania klienta.
Odpowiedź 201 new invoice; 200 exact idempotent replay
Przykładowa odpowiedź
{
"data": {
"id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
"invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
"project_id": "11111111-1111-4111-8111-111111111111",
"store_id": "22222222-2222-4222-8222-222222222222",
"source": "api",
"order_id": "order-1042",
"email": "ada@example.com",
"customer_name": "Ada Lovelace · Example GmbH",
"customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
"description": "Annual plan",
"amount": "49.9",
"currency": "USD",
"exchange_rate_spread_percent": "0.5",
"underpayment_tolerance_percent": "1",
"status": "new",
"amount_status": "none",
"timing_status": "on_time",
"resolution": "automatic",
"sequence": 1,
"winning_payment_intent_id": null,
"expires_at": "2026-08-31T18:15:00Z",
"monitoring_expires_at": "2026-09-07T18:15:00Z",
"settled_at": null,
"cancelled_at": null,
"archived_at": null,
"created_at": "2026-08-31T18:00:00Z",
"updated_at": "2026-08-31T18:00:00Z",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"checkout_language": "en",
"metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
"payment_intents": [
{
"id": "33333333-3333-4333-8333-333333333333",
"asset_id": "10000000-0000-4000-8000-000000000001",
"asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"chain_slug": "bitcoin",
"network": "mainnet",
"caip_network_id": "bip122:000000000019d6689c085ae165831e93",
"caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"symbol": "BTC",
"asset_decimals": 8,
"status": "pending",
"finality_mode": "confirmations",
"required_confirmations": 1,
"quote_rate": "0.000009218",
"quote_details": null,
"expected_amount": "0.00046",
"expected_amount_atomic": "46000",
"minimum_payment_amount": "0.0004554",
"minimum_payment_amount_atomic": "45540",
"received_amount": "0",
"received_amount_atomic": "0",
"confirmed_amount": "0",
"confirmed_amount_atomic": "0",
"destination_address": "bc1q…example",
"destination_tag": null,
"derivation_index": 42,
"quote_expires_at": "2026-08-31T18:15:00Z",
"monitoring_expires_at": "2026-09-07T18:15:00Z",
"next_check_at": "2026-08-31T18:00:00Z",
"last_checked_at": null,
"last_chain_height": null,
"last_anchor_hash": null,
"last_monitor_error": null,
"first_payment_at": null,
"fully_paid_at": null,
"finalized_at": null
}
]
},
"links": {
"checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
}
}Pola odpowiedzi
dataobject
idUUIDzawszeWewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.
invoice_idUUIDzawszePubliczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.
emailstring | nullzawszeE-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.
customer_namestring | nullzawszeNazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.
customer_addressstring | nullzawszeJednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.
exchange_rate_spread_percentdecimal stringzawszeZablokowany narzut wyceny: nadpisanie przy tworzeniu lub wartość domyślna sklepu przy pominięciu. Stosowany przed zaokrągleniem w górę; nigdy nie zmienia się na tej fakturze.
underpayment_tolerance_percentdecimal stringzawszeNiezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.
amount_statusamount statuszawszenone, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.
winning_payment_intent_idUUID | nullzawszeMetoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.
monitoring_expires_atRFC 3339 timestampzawszeNajpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.
ipn_urlstring | nullzawszeObowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.
cancel_urlstring | nullzawszeObowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.
redirect_automaticallybooleanzawszeCzy strona płatności powinna automatycznie przekierować po sukcesie.
metadataobjectzawsze
Metadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.Szczegóły
Metadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.
payment_intents[]object[]zawsze
Wycenione metody płatności i stan monitorowania.
payment_railonchain | lightningzawszeTransport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.Szczegóły
Transport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.
bolt11string | nullzawszeŻądanie płatności Lightning, w innym przypadku null. Opłać to żądanie portfelem Lightning; nigdy nie wysyłaj środków on-chain na jego hash płatności.
asset_decimalsintegerzawszePrecyzja jednostek atomowych. Lightning BTC używa 11 (millisatoshi), a nie 8 jak Bitcoin on-chain. Wyceny są w pełnych satoshi; wpływy zachowują precyzję millisatoshi.
quote_ratedecimal stringzawszeJednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.
quote_detailsobject | nullzawszePochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.Szczegóły
Pochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.
expected_amountdecimal stringzawszeDokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.Szczegóły
Dokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.
minimum_payment_amountdecimal stringzawszeNajmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.
minimum_payment_amount_atomicinteger stringzawszeDokładny akceptowany próg w najmniejszej jednostce aktywa.
destination_addressstringzawszeAdres odbiorczy on-chain lub 64-znakowy hash płatności dla Lightning. Do płacenia Lightning używaj bolt11; jego hash nie jest adresem Bitcoin.
destination_tagstring | nullzawszeWymagany publiczny identyfikator płatności, jeśli kanał go używa: tag docelowy XRP, identyfikator memo Stellar lub komentarz faktury TON. Null dla kanałów z unikalnymi adresami.
derivation_indexintegerzawszeZarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.
monitoring_expires_atRFC 3339 timestampzawszeKoniec monitorowania spóźnionych płatności dla tej metody.
Uwagi dotyczące użycia
- payment_methods filtruje metody włączone w sklepie wyłącznie dla tej faktury. Pominięcie/null zachowuje wszystkie metody sklepu; [] jest nieprawidłowe. Małą wskazówkę chain_slug i wyświetlane symbole aktywów znajdziesz w Projekt → Sklepy → Metody płatności. Lista API payment-assets dostarcza chain_slug, asset.symbol i asset.id. Użyj {chain_slug: ethereum, asset_tickers: [USDC, USDT]} dla akceptowanych tokenów Ethereum; BTC i PEPE działają tak samo w wybranych blockchainach. Symbole nie rozróżniają wielkości liter, są ograniczone do blockchaina i rozpoznawane tylko wewnątrz sklepu. Dwa akceptowane kontrakty z tym samym symbolem zwracają 400 zamiast wybierać jeden, nawet jeśli jeden nie jest gotowy; w takim przypadku użyj asset_ids. Aktywa natywne, tokeny katalogowe i niestandardowe podlegają tym samym zasadom. Każdy blockchain/kanał może wystąpić raz; maksymalnie 64 końcowe metody. Merchant 5.4.0+: nieznane, wyłączone, z niewłaściwego blockchaina lub nieakceptowane opcje są pomijane. Jeśli cały wybór nie ma aktywnych akceptowanych dopasowań, obowiązują ustawienia domyślne sklepu; w przeciwnym razie używane są tylko pasujące opcje. Wpis obejmujący tylko blockchain uwzględnia każde aktywne akceptowane aktywo on-chain. Aktywne wybrane metody wymagają prawidłowych portfeli, zainstalowanych adapterów skanera i wiarygodnych kursów. Od 6.0.6 niedostępne skanery, przerwy i oczekujące/nieaktualne kontrole stanu nie blokują tworzenia faktur ani nie usuwają skonfigurowanych metod on-chain. Wykrywanie jest ponawiane automatycznie; rozliczenie nadal wymaga kworum dostawców i potwierdzeń. Monitoruj receive_readiness i dbaj o dostępność dostawców: faktura może pozostawać niezweryfikowana do powrotu skanerów. Przydzielanie podadresów Monero i generowanie BOLT11 Lightning nadal wymaga ich zewnętrznej usługi portfela/węzła. Błędy zwracają error.message oraz error.details.payment_methods z chain_slug, asset_ticker, reason_code, a w diagnostyce skanera także required_endpoint_role, healthy_endpoints i required_independent_providers. TRON akceptuje indeksowaną historię lub obsługiwane surowe API utrwalonych natywnych bloków; sama podstawowa sprawność nie dowodzi zgodności skanera. Błędy wyceny identyfikują aktywo/walutę. Nic nie włącza nieakceptowanego aktywa ani nie zmienia polityki sklepu. W wersjach oprogramowania sprzedawcy przed 5.4.0 nieznane/nieaktywne jawne wybory powodują zamiast tego błąd. Metody istniejących faktur nigdy nie rozszerzają się po zmianie ustawień sklepu. Lightning trzeba wybrać oddzielnie. Odtworzenia zachowują pierwotne metody, a zmiana wyboru z tym samym Idempotency-Key zwraca 409.
- checkout_appearance obsługuje wszystkie wymienione wyżej ustawienia prezentacji. Pominięte pola dziedziczą wartości, tablice zastępują, a zagnieżdżone pola komunikatów są scalane; pusty obiekt komunikatów czyści dany zakres. Wynikowy wygląd i obrazy są zapisywane dla tej faktury bez edycji sklepu. Odczytaj appearance z publicznego JSON strony płatności, aby sprawdzić wynik. Całe żądanie ma limit 32 KiB, a wynikowe ustawienia 20 KiB.
- Zmiana checkout_appearance z tym samym Idempotency-Key zwraca 409; ponawiaj z identycznymi surowymi bajtami. Wygląd nie zmienia kwot, kursów, akceptowanych aktywów, wymagań potwierdzeń, rzeczywistego statusu ani uprawnień osadzania. Bez HTML, CSS, skryptów ani pobierania zdalnych obrazów.
- exchange_rate_spread_percent nadpisuje wartość domyślną sklepu dla tej faktury: pomiń lub wyślij null, aby dziedziczyć, albo wyślij "0", aby wyłączyć. Wyceny istniejących faktur nigdy się nie zmieniają.
- Narzut kursowy jest stosowany przed zaokrągleniem w górę. Opłaty nadal bazują na pierwotnej kwocie faktury w walucie fiducjarnej, bez narzutu.
- Zawsze wysyłaj zwrócone expected_amount lub expected_amount_atomic. Zaokrąglanie odbywa się w górę, ograniczone precyzją aktywa, 0,1% kwoty i jedną najmniejszą jednostką waluty fiducjarnej.
- Ponowienia muszą zachować te same dane dostępu, Idempotency-Key i dokładne bajty treści. Zmiana narzutu z tym samym kluczem zwraca 409 idempotency_conflict.
- Dokładne odtworzenie jest sprawdzane przed nową wyceną, DNS wywołania zwrotnego lub przygotowaniem adresu. Zakres danych dostępu i autoryzacja projektu/sklepu nadal są sprawdzane przy każdym żądaniu.
- Obowiązujący ipn_url wymaga sekretu podpisującego IPN sklepu. Nieznane pola treści są odrzucane.
Błędy
GETLista faktur/v1/projects/{project_id}/invoicesTylko odczyt
Zwraca zwięzłą stronę podsumowań faktur w danym zakresie, od najnowszych, w tym e-mail tylko dla sprzedawcy i pola klienta wyprowadzone z rozpoznanych metadanych. Wyszukiwanie oraz filtry statusu i sklepu są oceniane po stronie serwera; odpowiedź zawiera total i has_more dla przewidywalnego stronicowania.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Parametry zapytania
searchstringOpcjonalny prefiks identyfikatora faktury, zamówienia lub e-maila bez rozróżniania wielkości liter; dokładny UUID faktury; lub fragment opisu i rozpoznanych pól klienta. Wszystkie klucze metadanych i wartości tekstowe, liczbowe i logiczne (w tym zagnieżdżone obiekty/tablice) obsługują też indeksowane wyszukiwanie prefiksów słów: każde słowo wyszukiwania musi pasować, interpunkcja jest separatorem. Po przycięciu najwyżej 100 znaków, bez znaków sterujących. Dopasowania metadanych nie dodają surowych metadanych do odpowiedzi listy; odczytaj je w szczegółach faktury.Szczegóły
Opcjonalny prefiks identyfikatora faktury, zamówienia lub e-maila bez rozróżniania wielkości liter; dokładny UUID faktury; lub fragment opisu i rozpoznanych pól klienta. Wszystkie klucze metadanych i wartości tekstowe, liczbowe i logiczne (w tym zagnieżdżone obiekty/tablice) obsługują też indeksowane wyszukiwanie prefiksów słów: każde słowo wyszukiwania musi pasować, interpunkcja jest separatorem. Po przycięciu najwyżej 100 znaków, bez znaków sterujących. Dopasowania metadanych nie dodają surowych metadanych do odpowiedzi listy; odczytaj je w szczegółach faktury.
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": [
{
"id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
"invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
"project_id": "11111111-1111-4111-8111-111111111111",
"store_id": "22222222-2222-4222-8222-222222222222",
"source": "api",
"order_id": "order-1042",
"email": "ada@example.com",
"customer_name": "Ada Lovelace · Example GmbH",
"customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
"description": "Annual plan",
"amount": "49.9",
"currency": "USD",
"exchange_rate_spread_percent": "0.5",
"underpayment_tolerance_percent": "1",
"status": "processing",
"amount_status": "paid",
"timing_status": "on_time",
"resolution": "automatic",
"sequence": 3,
"winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
"expires_at": "2026-08-31T18:15:00Z",
"monitoring_expires_at": "2026-09-07T18:15:00Z",
"settled_at": null,
"cancelled_at": null,
"archived_at": null,
"created_at": "2026-08-31T18:00:00Z",
"updated_at": "2026-08-31T18:04:10Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 143,
"has_more": true
}
}Pola odpowiedzi
data[]object[]
idUUIDzawszeWewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.
invoice_idUUIDzawszePubliczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.
emailstring | nullzawszeE-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.
customer_namestring | nullzawszeNazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.
customer_addressstring | nullzawszeJednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.
exchange_rate_spread_percentdecimal stringzawszeZablokowany narzut wyceny: nadpisanie przy tworzeniu lub wartość domyślna sklepu przy pominięciu. Stosowany przed zaokrągleniem w górę; nigdy nie zmienia się na tej fakturze.
underpayment_tolerance_percentdecimal stringzawszeNiezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.
amount_statusamount statuszawszenone, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.
winning_payment_intent_idUUID | nullzawszeMetoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.
monitoring_expires_atRFC 3339 timestampzawszeNajpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.
paginationobject
totalintegerzawszeŁączna liczba wierszy pasujących do filtrów projektu, sklepu, statusu i wyszukiwania w zapisanym stanie strony.
Uwagi dotyczące użycia
- Sortowanie malejąco według created_at, potem malejąco według wewnętrznego id.
- Elementy listy to obiekty InvoiceSummary; email, customer_name i customer_address są tylko dla sprzedawcy. Wywołaj szczegóły, aby uzyskać surowe metadane i intencje płatności.
- Dla następnej strony ustaw offset na pagination.offset + pagination.limit tylko wtedy, gdy has_more jest true.
- Licznik i strona są odczytywane z jednego obrazu bazy danych w izolacji repeatable-read; równoczesne zapisy pojawią się przy późniejszym żądaniu.
Błędy
GETPobierz fakturę/v1/projects/{project_id}/invoices/{invoice_id}Tylko odczyt
Zwraca pełne szczegóły faktury sprzedawcy i bieżący aktywny URL strony płatności. Używaj tej trasy do odpytywania i uzgadniania.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
"invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
"project_id": "11111111-1111-4111-8111-111111111111",
"store_id": "22222222-2222-4222-8222-222222222222",
"source": "api",
"order_id": "order-1042",
"email": "ada@example.com",
"customer_name": "Ada Lovelace · Example GmbH",
"customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
"description": "Annual plan",
"amount": "49.9",
"currency": "USD",
"exchange_rate_spread_percent": "0.5",
"underpayment_tolerance_percent": "1",
"status": "settled",
"amount_status": "paid",
"timing_status": "on_time",
"resolution": "automatic",
"sequence": 4,
"winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
"expires_at": "2026-08-31T18:15:00Z",
"monitoring_expires_at": "2026-09-07T18:15:00Z",
"settled_at": "2026-08-31T18:05:00Z",
"cancelled_at": null,
"archived_at": null,
"created_at": "2026-08-31T18:00:00Z",
"updated_at": "2026-08-31T18:05:00Z",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"checkout_language": "en",
"metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
"payment_intents": [
{
"id": "33333333-3333-4333-8333-333333333333",
"asset_id": "10000000-0000-4000-8000-000000000001",
"asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"chain_slug": "bitcoin",
"network": "mainnet",
"caip_network_id": "bip122:000000000019d6689c085ae165831e93",
"caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"symbol": "BTC",
"asset_decimals": 8,
"status": "paid",
"finality_mode": "confirmations",
"required_confirmations": 1,
"quote_rate": "0.000009218",
"quote_details": null,
"expected_amount": "0.00046",
"expected_amount_atomic": "46000",
"minimum_payment_amount": "0.0004554",
"minimum_payment_amount_atomic": "45540",
"received_amount": "0.0004554",
"received_amount_atomic": "45540",
"confirmed_amount": "0.0004554",
"confirmed_amount_atomic": "45540",
"destination_address": "bc1q…example",
"destination_tag": null,
"derivation_index": 42,
"quote_expires_at": "2026-08-31T18:15:00Z",
"monitoring_expires_at": "2026-09-07T18:15:00Z",
"next_check_at": null,
"last_checked_at": "2026-08-31T18:05:00Z",
"last_chain_height": 912345,
"last_anchor_hash": "000000000000000000example",
"last_monitor_error": null,
"first_payment_at": "2026-08-31T18:03:00Z",
"fully_paid_at": "2026-08-31T18:03:00Z",
"finalized_at": "2026-08-31T18:05:00Z"
}
]
},
"links": {
"checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
}
}Pola odpowiedzi
dataobject
idUUIDzawszeWewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.
invoice_idUUIDzawszePubliczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.
emailstring | nullzawszeE-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.
customer_namestring | nullzawszeNazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.
customer_addressstring | nullzawszeJednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.
exchange_rate_spread_percentdecimal stringzawszeZablokowany narzut wyceny: nadpisanie przy tworzeniu lub wartość domyślna sklepu przy pominięciu. Stosowany przed zaokrągleniem w górę; nigdy nie zmienia się na tej fakturze.
underpayment_tolerance_percentdecimal stringzawszeNiezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.
amount_statusamount statuszawszenone, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.
winning_payment_intent_idUUID | nullzawszeMetoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.
monitoring_expires_atRFC 3339 timestampzawszeNajpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.
ipn_urlstring | nullzawszeObowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.
cancel_urlstring | nullzawszeObowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.
redirect_automaticallybooleanzawszeCzy strona płatności powinna automatycznie przekierować po sukcesie.
metadataobjectzawsze
Metadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.Szczegóły
Metadane sprzedawcy. Nigdy nie są zwracane przez publiczną stronę płatności. Narzędzia płatnicze panelu dodają informacje o pochodzeniu payment_tool (id, kind, title, pricing, requested_amount, request_id); nie dowodzą one płatności. Uwierzytelniaj wywołania zwrotne i realizuj invoice.settled raz na invoice_id.
payment_intents[]object[]zawsze
Wycenione metody płatności i stan monitorowania.
payment_railonchain | lightningzawszeTransport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.Szczegóły
Transport faktury. Bitcoin on-chain i Lightning mogą współdzielić asset_id; używaj identyfikatora intencji wraz z tym polem, nie samego symbolu. To co innego niż payment_rail skanera w katalogu aktywów.
bolt11string | nullzawszeŻądanie płatności Lightning, w innym przypadku null. Opłać to żądanie portfelem Lightning; nigdy nie wysyłaj środków on-chain na jego hash płatności.
asset_decimalsintegerzawszePrecyzja jednostek atomowych. Lightning BTC używa 11 (millisatoshi), a nie 8 jak Bitcoin on-chain. Wyceny są w pełnych satoshi; wpływy zachowują precyzję millisatoshi.
quote_ratedecimal stringzawszeJednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.
quote_detailsobject | nullzawszePochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.Szczegóły
Pochodzenie zablokowanej wyceny: reference_rate przed narzutem kursowym, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at i asset_fetched_at. Null na starszych fakturach; wartości historyczne nie są wymyślane.
expected_amountdecimal stringzawszeDokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.Szczegóły
Dokładna zablokowana kwota aktywa do zapłaty po narzucie kursowym i zaokrągleniu w górę. Od 4.1.1 rozpoznane zweryfikowane stablecoiny fiducjarne (takie jak USDC, USDT, DAI, USDS, EURC) zaokrągla się w górę do najwyżej dwóch miejsc dziesiętnych; 1.321 staje się 1.33, nigdy 1.32. To oczekiwana kwota nawet przy zerowej tolerancji. Inne aktywa zachowują adaptacyjną precyzję. Istniejące faktury nigdy nie są wyceniane ponownie.
minimum_payment_amountdecimal stringzawszeNajmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.
minimum_payment_amount_atomicinteger stringzawszeDokładny akceptowany próg w najmniejszej jednostce aktywa.
destination_addressstringzawszeAdres odbiorczy on-chain lub 64-znakowy hash płatności dla Lightning. Do płacenia Lightning używaj bolt11; jego hash nie jest adresem Bitcoin.
destination_tagstring | nullzawszeWymagany publiczny identyfikator płatności, jeśli kanał go używa: tag docelowy XRP, identyfikator memo Stellar lub komentarz faktury TON. Null dla kanałów z unikalnymi adresami.
derivation_indexintegerzawszeZarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.
monitoring_expires_atRFC 3339 timestampzawszeKoniec monitorowania spóźnionych płatności dla tej metody.
Uwagi dotyczące użycia
- Wyszukiwanie w zakresie celowo zwraca invoice_not_found, gdy publiczny identyfikator nie należy do autoryzowanego projektu.
- links.checkout używa Sklep → Podstawowe → Domeny sklepu: aktywnej nazwy hosta pay tego sklepu, potem wyboru jego sklepu domyślnego, a następnie systemowej domeny głównej. Hosty wycofane/robocze lub niewłaściwej usługi są pomijane. Dotyczy to też odpowiedzi tworzenia i MCP; linki są ustalane w chwili odpowiedzi, także przy idempotentnych odtworzeniach. Podpisane linki wywołań zwrotnych są zamrożone przy utworzeniu zdarzenia, nie przepisywane przy ponowieniach. Te preferencje tylko generują linki; nie przekierowują ruchu ani nie zmieniają ograniczeń IP.
Błędy
GETLista płatności faktury/v1/projects/{project_id}/invoices/{invoice_id}/paymentsTylko odczyt
Pełna bieżąca historia przelewów, w tym unieważnione obserwacje. Używaj, gdy wywołanie zwrotne oznacza payments_truncated. To bieżący stan, nie odtworzenie starszego zdarzenia.
Uwierzytelnianie i nagłówki
| Nagłówek | Obecność | Zasada |
|---|---|---|
| Authorization | wymagane | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | zalecane | application/json |
Parametry ścieżki
Parametry zapytania
Żądanie
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"invoice_id": "11111111-2222-4333-8444-555555555555",
"data": [{
"payment_id": "44444444-4444-4444-8444-444444444444",
"payment_method_id": "33333333-3333-4333-8333-333333333333",
"transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"payment_hash": null,
"event_index": 12,
"payment_rail": "onchain",
"chain_slug": "ethereum",
"network": "mainnet",
"asset_id": "55555555-5555-4555-8555-555555555555",
"asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"symbol": "USDC",
"asset_decimals": 6,
"amount": "58.17342",
"amount_atomic": "58173420",
"status": "final",
"counts_towards_received": true,
"confirmations": 2,
"block_height": 25975377,
"observed_at": "2026-09-14T12:03:00Z",
"chain_time": "2026-09-14T12:02:48Z",
"finalized_at": "2026-09-14T12:04:00Z",
"explorer_name": "Etherscan",
"explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}],
"pagination": {"limit": 25, "offset": 0, "total": 1, "has_more": false}
}Pola odpowiedzi
invoice_idstringdata[]object[]
payment_idstringpayment_method_idstringtransaction_idstringpayment_hashJSON | nullevent_indexintegerpayment_railstringchain_slugstringnetworkstringasset_idstringasset_keystringcaip_asset_idstringsymbolstringasset_decimalsintegeramountstringamount_atomicstringstatusstringcounts_towards_receivedbooleanconfirmationsintegerblock_heightintegerobserved_atstringchain_timestringfinalized_atstringexplorer_namestringexplorer_urlstringUwagi dotyczące użycia
- Obserwacja to log tokena, wyjście UTXO lub przelew innego kanału, niekoniecznie unikalny hash transakcji. Usuwaj duplikaty według payment_id; transaction_id wraz z event_index identyfikuje przelew blockchainowy.
- status to detected, confirming, final, reorged, replaced lub invalid. Tylko obserwacje counts_towards_received wliczają się do otrzymanych kwot. Nigdy nie sumuj kwot różnych aktywów.
- Zapisy Lightning używają payment_hash z null w transaction_id, confirmations i linkach eksploratora; precyzja BTC wynosi 11 (millisatoshi). Nie ujawniają preimage, BOLT11 ani sekretów portfela.
- Sortowane malejąco według observed_at, potem payment_id. Licznik i strona używają jednego obrazu w izolacji repeatable-read; późniejsze strony mogą zmieniać się wraz z napływem płatności. Przy stronicowaniu aktywnej faktury usuwaj duplikaty według payment_id.
- Obowiązują istniejący zakres projektu tylko do odczytu, ograniczenia IP i limity zapytań danych dostępu. Nigdy nie otwieraj linku z wywołania zwrotnego ze swoim tokenem, chyba że jego origin odpowiada skonfigurowanemu hostowi API.
Błędy
GETSzkielet strony płatności/Publiczne
Ścieżka główna zarządzanego hosta płatności udostępniająca aplikację płatniczą bez wyboru faktury. Integracje klientów zwykle powinny używać zamiast tego links.checkout.
Uwierzytelnianie i nagłówki
Publiczne
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/" \
--output 'checkout.html'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout.html").write_bytes(response.read())Odpowiedź 200 text/html
Przykładowa odpowiedź
<!doctype html>
<!-- Hosted Wholly Crypto checkout shell -->Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Zarządzana warstwa brzegowa płatności zezwala na GET/HEAD i odrzuca inne metody.
Błędy
GETHostowana strona płatności/invoice/{invoice_id}Publiczne
Strona płatności HTML dla klienta. Pobiera bezpieczny JSON płatności z tego samego hosta. Osadzanie jest zabronione, chyba że sklep je włączy i jawnie dopuści nadrzędny origin HTTPS.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID" \
--output 'checkout.html'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout.html").write_bytes(response.read())Odpowiedź 200 text/html
Przykładowa odpowiedź
<!doctype html>
<!-- Hosted Wholly Crypto checkout application -->Uwagi dotyczące użycia
- Token bearer nie jest akceptowany ani potrzebny.
- Sam szkielet HTML zwraca 200 nawet przy braku faktury; jego żądanie JSON płatności otrzymuje wtedy invoice_not_found.
- Odpowiedź ma no-store, noindex i CSP frame-ancestors właściwe dla faktury.
- Wyłączony projekt/sklep lub nieznana faktura nie ujawniają danych płatności.
Błędy
GETBezpieczne dane faktury dla strony płatności/checkout-api/invoices/{invoice_id}Publiczne
Zwraca tylko pola potrzebne do wyświetlenia strony płatności. Celowo pomija wewnętrzne identyfikatory, e-mail klienta i wyprowadzone pola adresu, URL IPN, metadane sprzedawcy, identyfikatory portfeli, ścieżki derywacji i diagnostykę monitora.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
"order_id": "order-1042",
"description": "Annual plan",
"amount": "49.9",
"currency": "USD",
"exchange_rate_spread_percent": "0.5",
"underpayment_tolerance_percent": "1",
"status": "processing",
"amount_status": "partial",
"timing_status": "on_time",
"sequence": 3,
"active_payment_method_id": "33333333-3333-4333-8333-333333333333",
"payment_method_locked": true,
"server_time": "2026-08-31T18:10:00Z",
"expires_at": "2026-08-31T18:15:00Z",
"expires_in_seconds": 300,
"payment_open": true,
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"checkout_language": "en",
"project": {
"name": "Example project",
"checkout_title": "Complete your payment",
"checkout_description": "Send the exact amount shown.",
"theme": "system",
"accent_color": "#42e39b",
"logo_url": "/checkout-api/invoices/…/logo/…/image.png"
},
"store": { "name": "Online shop" },
"payment_methods": [
{
"id": "33333333-3333-4333-8333-333333333333",
"asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"chain_slug": "bitcoin",
"chain_name": "Bitcoin",
"network": "mainnet",
"caip_network_id": "bip122:000000000019d6689c085ae165831e93",
"caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
"asset_name": "Bitcoin",
"symbol": "BTC",
"asset_icon_url": "/assets/coingecko/bitcoin.png",
"asset_kind": "native",
"contract_address": null,
"token_standard": null,
"asset_decimals": 8,
"status": "partial",
"payable": true,
"finality_mode": "confirmations",
"required_confirmations": 1,
"expected_amount": "0.00046",
"expected_amount_atomic": "46000",
"minimum_payment_amount": "0.0004554",
"minimum_payment_amount_atomic": "45540",
"received_amount": "0.0002",
"received_amount_atomic": "20000",
"remaining_amount": "0.0002554",
"remaining_amount_atomic": "25540",
"confirmed_amount": "0",
"confirmed_amount_atomic": "0",
"destination_address": "bc1q…example",
"destination_tag": null,
"quote_expires_at": "2026-08-31T18:15:00Z",
"payment_uri": "bitcoin:bc1q…example?amount=0.00026",
"qr_url": "/checkout-api/invoices/…/payment-methods/…/qr.svg?sequence=3&amount_atomic=26000",
"address_explorer_name": "mempool.space",
"address_explorer_url": "https://mempool.space/address/…",
"transaction_count": 0,
"transactions_truncated": false,
"transactions": []
}
]
}
}Pola odpowiedzi
dataobject
exchange_rate_spread_percentdecimal stringzawszeObowiązujący narzut wyceny zablokowany przy tworzeniu, w tym nadpisanie dla danej faktury.
amount_statusamount statuszawszenone, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.
active_payment_method_idUUID | nullzawszeWymieniona metoda płatności, która otrzymała środki. Strona płatności pozostaje przy tej metodzie, aby niedopłata nie była uzupełniana niezgodnym aktywem.
payment_method_lockedbooleanzawszeTrue po wybraniu active_payment_method_id przez prawidłową płatność.
server_timeRFC 3339 timestampzawszeCzas serwera zapisany dla tej odpowiedzi; używaj go z expires_at, aby uniknąć rozbieżności zegara urządzenia klienta.
expires_in_secondsintegerzawszePełne sekundy pozostałe w server_time, zaokrąglone w górę i ograniczone od dołu do zera.
payment_openbooleanzawszeTrue tylko wtedy, gdy faktura new lub processing jest przed terminem i ma co najmniej jedną dostępną do opłacenia metodę z pozostałą kwotą.
projectobjectzawsze
name, checkout_title, checkout_description, theme, accent_color i logo_url.
appearanceobjectzawsze
Efektywna prezentacja: zamrożone nadpisanie dla faktury, jeśli podane, w przeciwnym razie bieżący wygląd sklepu. Nigdy nie zmienia pól finansowych ani ostrzeżeń bezpieczeństwa.
inherit_default_storebooleanzawszeTrue, gdy wygląd pochodzi z domyślnego sklepu projektu. False dla niezależnych sklepów i zamrożonych nadpisań faktury.
invoice_overridebooleanzawszeTrue, gdy checkout_appearance podano przy tworzeniu faktury. Pominięcie/null zachowuje false.
titlestringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
introstringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
outrostringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
accent_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
background_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
card_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
button_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
logo_sizestringzawszesmall, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.
logo_alignmentstringzawszesmall, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.
imagesobjectzawszeOpcjonalne adresy logo_light, logo_dark i favicon: znormalizowane obrazy PNG z tego samego origin, ograniczone zakresem.
show_order_idbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
show_descriptionbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
details_expandedbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
show_project_namebooleanzawszeMerchant 5.6.0+: widoczność nazw w nagłówku. Obie domyślnie mają wartość true. Tożsamość projektu/sklepu pozostaje dostępna w JSON.
show_store_namebooleanzawszeMerchant 5.6.0+: widoczność nazw w nagłówku. Obie domyślnie mają wartość true. Tożsamość projektu/sklepu pozostaje dostępna w JSON.
featured_chains[]arrayzawszeUporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.
featured_asset_ids[]arrayzawszeUporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.
default_asset_idUUID | nullzawszeSugerowana metoda początkowa. Prawidłowa zapamiętana preferencja klienta lub metoda już otrzymująca środki ma pierwszeństwo.
messagesobjectzawsze
Zwykły tekst dla en, de, es, pt-BR, it, ru, zh-CN, fr, ko i ja, z kluczami waiting, confirming, paid, underpaid i expired. Angielski jest językiem zastępczym przy brakujących komunikatach sprzedawcy. Uzupełniające; nigdy nie zastępują rzeczywistego statusu. Treść napisana przez sprzedawcę nie jest automatycznie tłumaczona.Szczegóły
Zwykły tekst dla en, de, es, pt-BR, it, ru, zh-CN, fr, ko i ja, z kluczami waiting, confirming, paid, underpaid i expired. Angielski jest językiem zastępczym przy brakujących komunikatach sprzedawcy. Uzupełniające; nigdy nie zastępują rzeczywistego statusu. Treść napisana przez sprzedawcę nie jest automatycznie tłumaczona.
support_emailstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
support_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
terms_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
privacy_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
return_button_textstringzawszeTylko opcjonalna etykieta. Cele sukcesu/anulowania i polityka przekierowań nadal należą do faktury.
show_return_buttonbooleanzawszeWidoczność ręcznego przycisku powrotu/anulowania; domyślnie true. Dotyczy stanów aktywnych i końcowych, nie automatycznych przekierowań po sukcesie. Dostępne od oprogramowania sprzedawcy 8.1.4.
payment_methods[]object[]zawsze
Metody płatności bezpieczne dla strony płatności.
payment_railonchain | lightningzawszeLightning pozostaje metodą Bitcoin, oddzielną od BTC on-chain. Identyfikuj wybór przez identyfikator intencji i kanał, nie samo asset_id.
bolt11string | nullzawszePodpisane żądanie Lightning; null dla metod on-chain. Nigdy nie płać po zmianie payable na false.
payment_hashstring | nullzawszeHash płatności Lightning do uzgadniania, nie adres odbiorczy. Null dla metod on-chain.
asset_idUUIDzawszeUUID aktywa używany przez preferencje wyglądu; odrębny od identyfikatora intencji płatności tej faktury.
caip_network_idstringzawszeKanoniczna tożsamość sieci używana do jednoznacznego określenia wybranego blockchaina.
caip_asset_idstring | nullzawszeKanoniczna dokładna tożsamość aktywa, obejmująca zweryfikowany kontrakt lub mint tokena, jeśli dotyczy.
asset_icon_urlstring | nullzawszeLokalnie buforowana ikona aktywa z tego samego origin lub null, gdy brak zweryfikowanego mapowania CoinGecko.
contract_addressstring | nullzawszeKanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla waluty natywnej.
token_standarderc20 | spl-token | nullzawszeZweryfikowany typ wykonawczy tokena lub null dla waluty natywnej.
asset_decimalsintegerzawszePrecyzja jednostek atomowych: 11 dla millisatoshi Lightning BTC, 8 dla satoshi BTC on-chain.
payablebooleanzawszeTrue tylko wtedy, gdy dokładnie ta metoda może obecnie przyjąć płatność; false dla nieaktywnych metod po otrzymaniu środków przez inne aktywo.
expected_amountdecimalzawszePełna zablokowana wycena w jednostkach wyświetlanych i rzeczywistych on-chain. Rozpoznane stablecoiny fiducjarne używają najwyżej dwóch miejsc dziesiętnych wyceny, zawsze zaokrąglanych w górę po narzucie; inne aktywa używają adaptacyjnej precyzji. Rzeczywiste miejsca dziesiętne tokena, otrzymane środki i pozostałe kwoty płatności częściowych pozostają dokładne. Używaj zwróconych kwot bez zmian.Szczegóły
Pełna zablokowana wycena w jednostkach wyświetlanych i rzeczywistych on-chain. Rozpoznane stablecoiny fiducjarne używają najwyżej dwóch miejsc dziesiętnych wyceny, zawsze zaokrąglanych w górę po narzucie; inne aktywa używają adaptacyjnej precyzji. Rzeczywiste miejsca dziesiętne tokena, otrzymane środki i pozostałe kwoty płatności częściowych pozostają dokładne. Używaj zwróconych kwot bez zmian.
expected_amount_atomicinteger stringzawszePełna zablokowana wycena w jednostkach wyświetlanych i rzeczywistych on-chain. Rozpoznane stablecoiny fiducjarne używają najwyżej dwóch miejsc dziesiętnych wyceny, zawsze zaokrąglanych w górę po narzucie; inne aktywa używają adaptacyjnej precyzji. Rzeczywiste miejsca dziesiętne tokena, otrzymane środki i pozostałe kwoty płatności częściowych pozostają dokładne. Używaj zwróconych kwot bez zmian.Szczegóły
Pełna zablokowana wycena w jednostkach wyświetlanych i rzeczywistych on-chain. Rozpoznane stablecoiny fiducjarne używają najwyżej dwóch miejsc dziesiętnych wyceny, zawsze zaokrąglanych w górę po narzucie; inne aktywa używają adaptacyjnej precyzji. Rzeczywiste miejsca dziesiętne tokena, otrzymane środki i pozostałe kwoty płatności częściowych pozostają dokładne. Używaj zwróconych kwot bez zmian.
minimum_payment_amountdecimalzawszeAkceptowany próg rozliczenia po zastosowaniu tolerancji niedopłaty.
minimum_payment_amount_atomicinteger stringzawszeAkceptowany próg rozliczenia po zastosowaniu tolerancji niedopłaty.
remaining_amountdecimal stringzawszeDokładna wyświetlana kwota nadal potrzebna do osiągnięcia akceptowanego progu, ograniczona od dołu do zera.
remaining_amount_atomicinteger stringzawszeBrakująca kwota do akceptowanego progu w jednostkach atomowych. To nie żądana kwota płatności: tolerancja wpływa tylko na akceptację.
destination_addressstringzawszeAdres docelowy on-chain i opcjonalny identyfikator. Dla Lightning jest to hash płatności bez tagu; zamiast tego opłać bolt11/payment_uri.
destination_tagstring|nullzawszeAdres docelowy on-chain i opcjonalny identyfikator. Dla Lightning jest to hash płatności bez tagu; zamiast tego opłać bolt11/payment_uri.
payment_uristring | nullzawszeŻądanie właściwe dla blockchaina: ERC-681, Solana Pay, natywny URI lub lightning:<bolt11>. Żądania z kwotą używają pełnej oczekiwanej kwoty minus otrzymane środki, nigdy progu tolerancji. Null, gdy payable jest false, także po zaakceptowaniu tolerowanej niedopłaty. QR Lightning koduje pełne żądanie Lightning, nie hash płatności.Szczegóły
Żądanie właściwe dla blockchaina: ERC-681, Solana Pay, natywny URI lub lightning:<bolt11>. Żądania z kwotą używają pełnej oczekiwanej kwoty minus otrzymane środki, nigdy progu tolerancji. Null, gdy payable jest false, także po zaakceptowaniu tolerowanej niedopłaty. QR Lightning koduje pełne żądanie Lightning, nie hash płatności.
qr_urlpath | nullzawszeŚcieżka SVG QR z tego samego origin, wersjonowana sekwencją i dokładną pozostałą kwotą, lub null, gdy payable jest false. SVG ma no-store.
address_explorer_namestring|nullzawszeZweryfikowany zapasowy eksplorator sieci głównej, tam gdzie obsługiwany.
address_explorer_urlstring|nullzawszeZweryfikowany zapasowy eksplorator sieci głównej, tam gdzie obsługiwany.
transaction_countintegerzawszeŁączna liczba odrębnych publicznych prawidłowych transakcji zaobserwowanych dla tej metody.
transactions_truncatedbooleanzawszeTrue, gdy transaction_count przekracza długość zwróconej listy najnowszych transakcji.
transactions[]object[]zawsze
Do 10 najnowszych publicznych prawidłowych transakcji. Dokładne otrzymane sumy pozostają niezależne od tego limitu wyświetlania.
Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Cache-Control ma wartość no-store, a indeksowanie wyszukiwarkami jest wyłączone.
- Traktuj invoice_id jako dane umożliwiające klientowi dostęp; unikaj niepotrzebnego publikowania.
- asset_icon_url to lokalny zasób z tego samego origin; strona płatności klienta nigdy nie musi kontaktować się z CoinGecko, aby go wyświetlić.
- Gdy destination_tag nie jest null, wyświetlaj i kopiuj go obok adresu: to wymagany tag docelowy XRP, identyfikator memo Stellar lub komentarz faktury TON i musi zostać wysłany dokładnie.
- Dla zweryfikowanych tokenów asset_kind to token, contract_address identyfikuje dokładny kontrakt ERC-20 lub mint SPL, token_standard identyfikuje kanał, a payment_uri zawiera tę tożsamość tokena.
Błędy
GETPodgląd strony płatności sklepu/invoice/preview/{project_id}Publiczne
Wyświetla zapisany wygląd sklepu z przykładową kwotą i rzeczywistymi metadanymi akceptowanych aktywów. Przełączaj przykłady waiting, confirming, paid, underpaid i expired bez tworzenia płatności.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Parametry zapytania
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming" \
--output 'checkout-preview.html'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-preview.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-preview.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-preview.html").write_bytes(response.read())Odpowiedź 200 text/html
Przykładowa odpowiedź
<!doctype html>
<!-- Hosted branding preview; no invoice is created -->Uwagi dotyczące użycia
- Podgląd służy wyłącznie prezentacji marki i nigdy nie wolno wysyłać go klientowi jako żądania płatności.
- Bez adresu odbiorczego, płatnego QR, operacji portfela, przekierowania ani odpytywania płatności. Przykłady nie zmieniają rzeczywistego statusu faktury.
- Odpowiedź ma no-store, noindex i nie może być osadzana.
Błędy
GETDane podglądu płatności/checkout-api/previews/{project_id}Publiczne
Zwraca efektywny wygląd sklepu i bezpieczne metadane akceptowanych aktywów. payment_methods pozostaje puste; preview_methods nie zawiera adresów płatniczych, wycen ani prywatnych danych portfela.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Parametry zapytania
store_idUUID,opcjonalneMusi należeć do tego projektu; niedopasowane identyfikatory zwracają 404. Nieznane pola zapytania są odrzucane.
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID", {
method: "GET",
headers: {
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))Odpowiedź 200 application/json
Przykładowa odpowiedź
{
"data": {
"preview": true,
"invoice_id": "YOUR_PROJECT_ID",
"amount": "100.00",
"currency": "USD",
"project": {
"name": "Example project",
"checkout_title": "Complete your payment",
"checkout_description": "Choose a network and send the exact amount shown.",
"theme": "system",
"accent_color": "#42e39b",
"logo_url": "/checkout-api/previews/…/logo/…/image.png"
},
"appearance": {"inherit_default_store": true, "theme": "system", "accent_color": "#42E39B", "images": {}},
"preview_methods": [],
"payment_methods": []
}
}Pola odpowiedzi
dataobject
previewbooleaninvoice_idstringamountstringcurrencystringprojectobject
appearanceobject
inherit_default_storebooleanzawszeTrue, gdy wygląd pochodzi z domyślnego sklepu projektu. False dla niezależnych sklepów i zamrożonych nadpisań faktury.
invoice_overridebooleanzawszeTrue, gdy checkout_appearance podano przy tworzeniu faktury. Pominięcie/null zachowuje false.
titlestringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
introstringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
outrostringzawszeZwykły nagłówek sprzedawcy, komunikat górny i dolny. intro zastępuje customer_message; stara zapisana treść zostaje zachowana. Nigdy nie interpretuj jako znaczników.
accent_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
background_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
card_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
button_colorstringzawszeŚcisły format kolorów #RRGGBB. Kolory opcjonalne są puste dla wartości automatycznych; kontrast pierwszego planu jest obliczany.
logo_sizestringzawszesmall, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.
logo_alignmentstringzawszesmall, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.
imagesobjectzawszeOpcjonalne adresy logo_light, logo_dark i favicon: znormalizowane obrazy PNG z tego samego origin, ograniczone zakresem.
show_order_idbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
show_descriptionbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
details_expandedbooleanzawszeWidoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.
show_project_namebooleanzawszeMerchant 5.6.0+: widoczność nazw w nagłówku. Obie domyślnie mają wartość true. Tożsamość projektu/sklepu pozostaje dostępna w JSON.
show_store_namebooleanzawszeMerchant 5.6.0+: widoczność nazw w nagłówku. Obie domyślnie mają wartość true. Tożsamość projektu/sklepu pozostaje dostępna w JSON.
featured_chains[]arrayzawszeUporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.
featured_asset_ids[]arrayzawszeUporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.
default_asset_idUUID | nullzawszeSugerowana metoda początkowa. Prawidłowa zapamiętana preferencja klienta lub metoda już otrzymująca środki ma pierwszeństwo.
messagesobjectzawsze
Zwykły tekst dla en, de, es, pt-BR, it, ru, zh-CN, fr, ko i ja, z kluczami waiting, confirming, paid, underpaid i expired. Angielski jest językiem zastępczym przy brakujących komunikatach sprzedawcy. Uzupełniające; nigdy nie zastępują rzeczywistego statusu. Treść napisana przez sprzedawcę nie jest automatycznie tłumaczona.Szczegóły
Zwykły tekst dla en, de, es, pt-BR, it, ru, zh-CN, fr, ko i ja, z kluczami waiting, confirming, paid, underpaid i expired. Angielski jest językiem zastępczym przy brakujących komunikatach sprzedawcy. Uzupełniające; nigdy nie zastępują rzeczywistego statusu. Treść napisana przez sprzedawcę nie jest automatycznie tłumaczona.
support_emailstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
support_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
terms_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
privacy_urlstringzawszeOpcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.
return_button_textstringzawszeTylko opcjonalna etykieta. Cele sukcesu/anulowania i polityka przekierowań nadal należą do faktury.
show_return_buttonbooleanzawszeWidoczność ręcznego przycisku powrotu/anulowania; domyślnie true. Dotyczy stanów aktywnych i końcowych, nie automatycznych przekierowań po sukcesie. Dostępne od oprogramowania sprzedawcy 8.1.4.
preview_methods[]arraypayment_methods[]arrayUwagi dotyczące użycia
- Token bearer nie jest akceptowany ani potrzebny.
- Nie są zwracane dane faktury, adresu docelowego, portfela, transakcji, IPN, webhooka ani metadane sprzedawcy.
- Użyj uwierzytelnionego panelu, aby uzyskać poprawny link podglądu w domenie pay.
Błędy
GETObraz strony płatności sklepu/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngPubliczne
Zwraca znormalizowane logo sklepu lub favicon należące do tej faktury. Używaj adresów appearance.images z danych strony płatności.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
--output 'store-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("store-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("store-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("store-logo.png").write_bytes(response.read())Odpowiedź 200 image/png
Przykładowa odpowiedź
(binary PNG response)Uwagi dotyczące użycia
- Używaj appearance.images z JSON strony płatności. Zamrożone obrazy faktury nadal działają po zastąpieniu lub usunięciu przesłanego obrazu w sklepie źródłowym. Jawnie usunięte, przypisane do innej faktury, niewłaściwego rodzaju i nieznane rewizje zwracają 404; zapisany stan nigdy nie przechodzi awaryjnie na bieżący obraz sklepu.
- Bez nadpisania faktury używany jest bieżący efektywny obraz sklepu, a zastąpione/usunięte rewizje zwracają 404. Tylko PNG, nosniff i prywatne buforowanie.
- Przesyłanie obrazów sklepu przyjmuje ograniczone rozmiarem PNG, JPEG lub WebP w uwierzytelnionym panelu; nigdy SVG, HTML ani zdalne URL obrazów.
Błędy
GETObraz podglądu sklepu/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngPubliczne
Zwraca znormalizowany obraz podglądu tylko dla pasującego projektu, sklepu, rodzaju i bieżącej rewizji.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
--output 'store-preview-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("store-preview-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("store-preview-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("store-preview-logo.png").write_bytes(response.read())Odpowiedź 200 image/png
Przykładowa odpowiedź
(binary PNG response)Uwagi dotyczące użycia
- Używaj appearance.images z danych podglądu. Nieznane lub niedopasowane identyfikatory zwracają 404. Żadne informacje o portfelu ani płatności nie są ujawniane.
Błędy
GETWersjonowane logo podglądu/checkout-api/previews/{project_id}/logo/{revision}/image.pngPubliczne
Zwraca znormalizowane logo projektu tylko wtedy, gdy projekt i bezpieczna dla pamięci podręcznej rewizja logo są zgodne. Używaj project.logo_url z danych podglądu zamiast konstruować ten URL.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png" \
--output 'checkout-preview-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-preview-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-preview-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-preview-logo.png").write_bytes(response.read())Odpowiedź 200 image/png
Przykładowa odpowiedź
(binary PNG response)Uwagi dotyczące użycia
- Nieznane projekty i nieaktualne rewizje logo zwracają invoice_not_found bez ujawniania, którego elementu brakowało.
- Pomyślnie zwrócony wersjonowany obraz jest niezmienny i może być buforowany.
Błędy
GETObraz QR płatności/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgPubliczne
Generuje SVG QR 512×512 dla dokładnej treści płatności właściwej dla blockchaina i metody płatności faktury.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg" \
--output 'payment-qr.svg'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("payment-qr.svg", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("payment-qr.svg", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("payment-qr.svg").write_bytes(response.read())Odpowiedź 200 image/svg+xml
Przykładowa odpowiedź
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">…</svg>Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Używaj qr_url wersjonowanego sekwencją i pozostałą kwotą, zwróconego w JSON strony płatności; SVG jest prywatne i no-store.
- Po płatności częściowej żąda dokładnej pozostałej kwoty i pozostaje zablokowane na to aktywo.
- Zwraca 409 po wygaśnięciu, zakończeniu lub gdy aktywna jest inna metoda; zwraca payment_qr_unavailable (422), jeśli żądanie jest zbyt duże do zakodowania.
Błędy
GETWersjonowane logo strony płatności/checkout-api/invoices/{invoice_id}/logo/{revision}/image.pngPubliczne
Zwraca znormalizowane logo płatności projektu tylko wtedy, gdy faktura i bieżąca rewizja logo są zgodne. Preferuj project.logo_url zwrócone w JSON strony płatności zamiast konstruować tę trasę.
Uwierzytelnianie i nagłówki
Publiczne
Parametry ścieżki
Żądanie
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png" \
--output 'checkout-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-logo.png").write_bytes(response.read())Odpowiedź 200 image/png
Przykładowa odpowiedź
(binary PNG response)Uwagi dotyczące użycia
- Token bearer nie jest potrzebny.
- Publiczny czas buforowania to rok z immutable, ponieważ rewizja identyfikuje stan według treści.
- Nieznane/niedopasowane rewizje zwracają invoice_not_found.
Błędy
Dokumentacja Wholly Crypto 8.3.2. Dla zainstalowanej wersji otwórz Ustawienia → Dostęp API → Dokumentacja w panelu. Zobacz wydania.