DOKUMENTACJA DLA PROGRAMISTÓW

Dokumentacja API

Zintegruj faktury, stronę płatności i powiadomienia o płatnościach.

Szybki start

Utwórz pierwszą fakturę.

  1. Przygotuj sklep

    Włącz jego metody płatności, skonfiguruj dostawców i wykonaj kopie zapasowe portfeli projektu.

  2. Utwórz dane dostępu API

    W panelu w Ustawienia → Dostęp API wybierz odczyt/zapis i przypisz projekt.

  3. Wyślij żądanie

    Użyj swojego hosta API i skopiuj identyfikatory projektu i sklepu. Wysyłaj kwoty dziesiętne jako ciągi znaków.

  4. Otwórz stronę płatności

    Przekieruj na links.checkout z 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"
}'

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ępczyGdzie go znaleźćZastosowanie
YOUR_PROJECT_IDProjekt → Ustawienia → Identyfikatory API → Identyfikator API projektu → Kopiuj. Widoczny też na karcie Podstawowe sklepu.Żądania na poziomie projektu i sklepu.
YOUR_STORE_IDProjekt → 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 hostCel
merchant.example.comPanel sprzedawcy i Ustawienia
pay.example.comStrona 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
UstawienieJak to działa
Poziom dostępuDane 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.
ProjektyPrzypisz projekty dostępne dla danych dostępu. Identyfikatory sklepów i faktur muszą należeć do przypisanego projektu.
Ograniczenia IPOpcjonalnie zezwól na dokładne publiczne adresy wyjściowe IPv4 lub IPv6 w Ustawienia → Dostęp API.
Przechowywanie danych dostępuPrzechowuj 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.

  1. Odczytaj aktywa płatnicze projektu i ich gotowość.
  2. Włącz natywny blockchain oraz skonfiguruj jego portfel i dostawców.
  3. Przeglądaj kandydatów na tokeny i zweryfikuj kontrakt lub mint przed włączeniem tokena.
  4. 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ściObsługaDowodyWymagania
Natywne kanały płatnościobsługiwaneSkanowanie transakcjiBTC, 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-20obsługiwaneSkanowanie transakcjiEthereum, Base, BNB Chain, HyperEVM, Avalanche, Polygon, Arbitrum i Optimism wymagają weryfikacji on-chain; indeksowane logi Transfer pozwalają przypisać płatność.
Kanały tokenów SPLobsługiwaneSkanowanie transakcjiKandydaci 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 UTXOobsługiwaneSkanowanie transakcjiBCH/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 kontoweobsługiwaneSkanowanie transakcjiTRON 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ęgachobsługiwaneSkanowanie transakcjiAptos 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 TONobsługiwaneSkanowanie transakcjiCardano 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ść rozliczeniaobsługiwaneNiezależna weryfikacjaDomyś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ł MoneroobsługiwaneRPC portfela tylko do podglądu przypisanego do projektuJeden 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ń.

StatusZnaczenie
newOczekiwanie na płatność
processingZaobserwowano płatność; oczekiwanie na akceptowaną kwotę lub ostateczność
settledZaakceptowano zgodnie z polityką rozliczenia faktury lub ręcznie
expiredTermin upłynął; monitorowanie spóźnionych płatności może trwać dalej
invalidPłatność nie może zostać zaakceptowana automatycznie
cancelledAnulowano; 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/historiiStatus w treściZnaczenie
invoice.creatednewFaktura została utworzona i oczekuje na płatność. Używane też, gdy kontrolowane ponowne otwarcie przywraca fakturę do new.
payment.receivedResulting invoice statusZarejestrowano płatność lub wzrosła otrzymana kwota. Zwykle processing lub settled; samo to zdarzenie nie jest dowodem rozliczenia.
invoice.processingprocessingWykryto płatność, ale akceptowana kwota lub wymagana ostateczność nie zostały jeszcze osiągnięte. Obejmuje płatności częściowe.
invoice.settledsettledSpełniono politykę rozliczenia lub zaakceptowano ręcznie. Przed realizacją sprawdź resolution i zamówienie.
invoice.expiredexpiredTermin płatności upłynął. Spóźniona płatność może nadal zmienić status, dopóki trwa monitorowanie.
invoice.invalidinvalidNie można zaakceptować automatycznie, utracono dowody płatności lub sprzedawca ją odrzucił. Sprawdź fakturę.
invoice.cancelledcancelledFaktura 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)

Sekwencjaevent_typestatus
1invoice.creatednew
2payment.receivedprocessing
2invoice.processingprocessing
3invoice.settledsettled

Płatność jest już ostateczna przy wykryciu (przykład Solana)

Sekwencjaevent_typestatus
1invoice.creatednew
2payment.receivedsettled
2invoice.settledsettled

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ścieSposób obsługi
Odbiornik oparty na zdarzeniachPrzechowuj 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ń SDKDostarczone 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
PoleWartościZnaczenie
statusnew, processing, settled, expired, invalid, cancelledStan faktury przy utworzeniu zdarzenia; niekoniecznie jej bieżący stan przy dostarczeniu.
amount_statusnone, partial, paid, overpaidOtrzymana kwota, z uwzględnieniem akceptowanej tolerancji. paid nie oznacza ostateczności potwierdzeń.
timing_statuson_time, lateCzy płatność zmieściła się w terminie faktury.
resolutionautomatic, manually_settled, manually_invalidatedCzy wynik określiły zwykłe reguły, czy ręczna akceptacja/odrzucenie.
requires_reviewfalse, trueWskazówka dotycząca wyjątku, a nie kolejny status faktury ani automatyczne zezwolenie na realizację/zwrot.
SytuacjaObsługa
Niedopłata / tolerancjaZgodnie 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łataoverpaid 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 akceptacjainvoice.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żnienieNowsza 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 kwotaRozliczenie 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
PoleTypZnaczenie
invoice_idUUIDPubliczny UUID faktury, używany przez uwierzytelnioną trasę szczegółów faktury
statusstringZapisany stan faktury: new, processing, settled, expired, invalid, cancelled
amount_statusstringnone, partial, paid lub overpaid; paid obejmuje akceptowaną tolerancję niedopłaty, a nie ostateczność potwierdzeń
timing_statusstringon_time lub late
resolutionstringautomatic, manually_settled lub manually_invalidated
sequenceintegerRosnąca rewizja faktury; różne zdarzenia mogą współdzielić jedną rewizję. Porównuj bez utraty precyzji liczb całkowitych
amountdecimal stringPierwotna suma faktury, nie otrzymana kwota krypto; zachowaj precyzję dziesiętną
currencystringWaluta pola amount, np. EUR dla faktury w EUR opłaconej USDC
order_idstring | nullIdentyfikator zamówienia sprzedawcy
payload_versioninteger2 dla nowo generowanych zdarzeń w 4.1.0+; brak w zachowanych starszych zdarzeniach
event_idUUIDPodpisana tożsamość zdarzenia, niezmienna przy ponowieniach i ręcznym ponownym dostarczeniu
event_typestringJedno z siedmiu zdarzeń subskrypcji
occurred_attimestampCzas utworzenia tego niezmiennego zdarzenia, nie czas dostarczenia
project_idUUIDZakres projektu sprzedawcy; dopasuj do skonfigurowanego odbiornika
store_idUUIDZakres sklepu sprzedawcy; dopasuj do skonfigurowanego odbiornika
descriptionstring | nullPierwotny opis faktury
emailstring | nullOpcjonalny e-mail klienta w chwili utworzenia zdarzenia
customerobjectRozpoznawane opcjonalne pola metadanych klienta; bez odgadywanych lub wzbogacanych danych osobowych
metadataobjectPierwotne metadane sprzedawcy w postaci z chwili utworzenia zdarzenia
created_attimestampCzas utworzenia faktury
updated_attimestampCzas aktualizacji stanu faktury
expires_attimestampTermin płatności faktury
monitoring_expires_attimestampTermin zakończenia monitorowania spóźnionych płatności
settled_attimestamp | nullCzas rozliczenia
paid_chainstring | null4.1.2+: slug blockchaina potwierdzonej metody rozliczenia, np. ethereum; null bez zapisanego kwalifikującego rozliczenia
paid_assetstring | null4.1.2+: symbol natywnej monety lub tokena, np. BTC, ETH lub USDC; etykieta do wyświetlania, nie unikalna tożsamość aktywa
paid_asset_amountdecimal string | null5.0.1+: pełna zablokowana żądana kwota w jednostkach paid_asset, przed odjęciem tolerancji; zapisana przy rozliczeniu
paid_asset_amount_receiveddecimal string | null5.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_idUUID | null4.1.2+: identyfikator intencji rozliczającej; odpowiada payment_info.methods[].payment_method_id i jej dokładnej sieci/kontraktowi
settlement_exchange_rateobject | null4.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_attimestamp | nullCzas anulowania
exchange_rate_spread_percentdecimal stringZablokowany narzut kursowy, nie bieżąca wartość domyślna sklepu
underpayment_tolerance_percentdecimal stringZablokowana tolerancja faktury; każda metoda podaje też swoją efektywną tolerancję
reason_codestring | nullPrzyczyna zmiany stanu w formacie maszynowym
requires_reviewbooleanWskazówka dotycząca wyjątku płatności; nie zezwolenie na automatyczną realizację lub zwrot
linksobjectAdresy 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_infoobjectRzeczywiś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

PoleTypZnaczenie
rate / units / currency / symbolstringsJednostki 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_oftimestampsCzas 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_atstrings / timestampsŹródła cen waluty fiducjarnej i aktywa oraz czasy ich pobrania, zapisane przy rozliczeniu.
stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringTe same znaczniki jakości co w market_rate_at_event. Stałe ceny projektu są oznaczone; walutą odniesienia jest USD.
Missing snapshot or pricenullBez 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

PoleTypZnaczenie
active_payment_method_idUUID | nullZwycięska lub wybrana zaobserwowana metoda. Null przed wykryciem lub po unieważnieniu; domyślna metoda nie jest odgadywana.
method_count / methods_truncatedinteger / 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_railUUID / stringTożsamość intencji faktury i transport onchain lub lightning.
chain_slug / network / caip_network_idstringTożsamość sieci. Zawsze łącz tożsamość tokena z jego siecią.
asset_id / asset_key / caip_asset_idUUID / string / nullable stringZweryfikowana tożsamość w rejestrze; same symbole nie są unikalne.
asset_name / symbol / asset_kindstringWyświetlana nazwa aktywa, symbol i rodzaj: natywne lub token.
contract_address / token_standardstring | nullKontrakt lub mint tokena i standard; null dla aktywów natywnych.
asset_decimalsintegerPrecyzja atomowa; Lightning BTC używa 11.
destination_address / destination_tagstring | nullPubliczny adres odbiorczy i wymagane memo/tag. Adres ma wartość null dla Lightning; nigdy nie jest kluczem prywatnym.
statusstringStan 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.paymentsHTTPS URL | nullUwierzytelniona, stronicowana historia tej metody na skonfigurowanym origin API.

Dokładne kwoty: methods[].amounts

PoleTypZnaczenie
expected_amountdecimal stringPełna zablokowana wycena po narzucie kursowym i zaokrągleniu w górę.
received_amount / confirmed_amountdecimal stringsPrawidłowo wykryte środki / środki spełniające politykę potwierdzeń lub ostateczności tej metody.
unconfirmed_amountdecimal stringmax(received - confirmed, 0). Nie jest to dodatkowa kwota do wysłania.
minimum_payment_amountdecimal stringAkceptowany próg po uwzględnieniu tolerancji. Może być niższy od pełnej wyceny.
remaining_amountdecimal stringmax(minimum accepted - received, 0). Dodatkowe środki potrzebne do osiągnięcia akceptowanego progu, nie postęp potwierdzeń.
remaining_to_full_amountdecimal stringmax(full quote - received, 0), z pominięciem tolerancji.
overpaid_amountdecimal stringmax(received - full quote, 0). Nie upoważnia do automatycznego zwrotu.
Every amount's *_atomic companioninteger stringDokł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

PoleTypZnaczenie
finality_mode / required_confirmationsstring / integerZablokowana liczba potwierdzeń lub polityka finalized. Zero potwierdzeń jest jawnie dozwolone przez politykę sprzedawcy, nie oznacza powszechnej ostateczności sieci.
observed_confirmationsinteger | nullMinimum wśród prawidłowych obserwacji, nie tylko najnowszego przelewu. Null dla Lightning lub przy braku prawidłowych obserwacji.
underpayment_tolerance_percentdecimal stringEfektywna tolerancja metody. Lightning używa zera, nawet jeśli faktura ma niezerową tolerancję on-chain.

Kursy: methods[].quote i market_rate_at_event

PoleTypZnaczenie
quote.effective_rate / units / currency / symbolstringsZablokowany kurs asset_per_invoice_currency z narzutem kursowym; waluta i symbol jawnie określają kierunek.
quote.exchange_rate_spread_percent / quote_expires_atdecimal string / timestampZablokowany narzut kursowy i termin wyceny. Nigdy nie zastępują ich bieżące ustawienia sklepu.
quote.reference_rate / unrounded_payment_amount / rounding_adjustmentdecimal string | nullWartość 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_atstring or timestamp | nullPierwotne źródła/czasy wyceny waluty i aktywa. Bez kluczy API ani danych dostępu dostawców.
quote.provenance_available / roundingboolean / stringFalse dla starych faktur bez zapisanego stanu źródeł; zaokrąglanie następuje w górę.
market_rate_at_eventobject | nullOrientacyjny 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 / symbolstringsKurs rynkowy przed narzutem, z tym samym jawnym kierunkiem co quote.
market_rate_at_event.observed_at / as_of / pricing_fetched_at / asset_fetched_attimestampsCzas zapisu zdarzenia / starszy z dwóch czasów źródeł / czas każdego źródła.
market_rate_at_event.pricing_provider / asset_providerstringsBuforowane źródła waluty i aktywa, w tym skonfigurowane ceny niestandardowych tokenów.
market_rate_at_event.stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringCzy 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

PoleTypZnaczenie
payment_id / payment_method_idUUIDTożsamość obserwacji / tożsamość nadrzędnej intencji. Używaj payment_id do usuwania duplikatów historii.
transaction_id / payment_hash / event_indexstring | null / integerHash 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_decimalsstrings / UUID / integerTe same identyfikatory aktywa i sieci co w metodzie nadrzędnej.
amount / amount_atomicdecimal / integer stringsDokładna wartość tego przelewu, nigdy przeliczenie na walutę fiducjarną.
status / counts_towards_receivedstring / booleandetected, confirming i final są wliczane; reorged, replaced i invalid nie są. Zachowuj unieważnioną historię do uzgadniania płatności.
confirmations / block_heightinteger | nullDane bloku obserwacji; potwierdzenia mają wartość null dla Lightning.
observed_at / chain_time / finalized_attimestamp | nullPierwsze 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_urlstring | nullZweryfikowane 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.

Stronicowana historia płatności →

Odbieraj bezpiecznie

  1. 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.
  2. 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ę.
  3. 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ń.
  4. 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 dostarczaniaSzczegóły
NagłówkiWholly-Signature, Wholly-Event-Id i Wholly-Delivery-Id; Content-Type to application/json.
PodpisHMAC-SHA256 dla <unix timestamp>.<exact raw body>; format nagłówka t=<timestamp>,v1=<64 lowercase hex>.
SukcesDowolna odpowiedź HTTP 2xx. Przekierowania nie są śledzone; odpowiedzi inne niż 2xx oznaczają niepowodzenie.
Limity czasu5 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 celuTylko 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ówZapisuj 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 sekretuRotacja nie ma okresu nakładania ani nagłówka wersji i natychmiast zmienia podpisy zakolejkowanych, ponawianych i ręcznych dostarczeń.
Wstrzymane dostarczeniaNiewystarczają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.

  1. 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.
  2. 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.
  3. 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ą.
  4. 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"
    }
  }
}

Przewodnik konfiguracji MCP →

NarzędzieDostępCel
list_projectsOdczytajWłączone projekty przypisane do połączenia; stronicowanie limit/offset.
list_storesOdczytajSklepy, identyfikatory i stan włączenia w project_id; stronicowanie limit/offset.
list_payment_methodsOdczytajSkonfigurowane metody blockchainowe, tokenowe i Lightning dla project_id + store_id.
get_wallet_balancesOdczytajAdresy odbiorcze i buforowane salda z polami aktualności/dostępności; nigdy sekrety portfeli.
list_invoicesOdczytajFaktury projektu, filtrowane według sklepu, statusu lub wyszukiwania; stronicowanie limit/offset.
get_invoiceOdczytajPełne szczegóły faktury i link płatniczy przy użyciu project_id + invoice_id.
get_delivery_historyOdczytajStatusy IPN/webhooków sklepu, próby i wyniki HTTP. Opcjonalne filtry invoice_id/kind; bez sekretów ani treści wywołań zwrotnych.
convert_amountOdczytajBuforowane przeliczenie referencyjne przy użyciu from, to i kwoty jako ciągu dziesiętnego; nie wycena faktury.
create_invoiceJawny zapisproject_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żkaKontrakt
POST/mcpUwierzytelnione JSON-RPC: initialize, ping, tools/list, tools/call. Żądania powiadomień zwracają 202; partie żądań są odrzucane.
GET / DELETE/mcpUwierzytelnione 405: skończone odpowiedzi JSON, bez samodzielnego strumienia SSE i bez sesji MCP po stronie serwera.
GET/.well-known/oauth-protected-resource/mcpKanoniczny adres URL zasobu i wykrywanie serwera autoryzacji; dostępne też pod /.well-known/oauth-protected-resource.
GET/.well-known/oauth-authorization-serverPunkty końcowe OAuth, authorization_code/refresh_token, S256 PKCE i obsługiwane zakresy.
POST/mcp/oauth/registerRejestracja 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/authorizeclient_id, redirect_uri, response_type=code, resource, code_challenge, code_challenge_method=S256, opcjonalne scope/state; przekierowuje do zatwierdzenia w panelu.
POST/mcp/oauth/tokenZakodowane jako formularz authorization_code + code + code_verifier + redirect_uri lub refresh_token + refresh_token. Zawsze dołączaj client_id i resource.
POST/mcp/oauth/revokeclient_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
    }
  }
}'

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.

  1. 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.
  2. Przechowuj klucz wc_operator_ na serwerze. Używaj nazwy hosta API, a nie nazwy hosta panelu Operator ani klucza sprzedawcy.
  3. 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ę.
  4. 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.
ZakresDostęp
merchants.read / merchants.writeListowanie/odczyt i tworzenie/aktualizacja hostowanych sprzedawców.
users.read / users.write / users.securityOdczyt/tworzenie/aktualizacja użytkowników; zmiana haseł i unieważnianie sesji oddzielnie. Nigdy nie tworzy administratora operatora.
invitations.read / invitations.writeListowanie/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.writeOdczyt sald/księgi; przyznawanie lub korygowanie lokalnych środków; ustawianie przyszłych opłat. Niezerowe saldo początkowe wymaga credits.write.
topups.read / topups.writeOdczyt 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.readKonfiguracja 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.writeZarzą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.readOdczyt 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
TematZasada
Dane dostępuOpcjonalny 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.
IzolacjaKlucze 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 logowanieKonta 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.
ZaproszeniaLinki 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 ponawianieKaż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 wynikioperator_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łatyCią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.
Wstrzymywanieenabled=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 funkcjeBez 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

ZdarzenieDane
merchant.created / merchant.updatedmerchant_id, enabled, payments_paused, fee_bps.
user.created / user.updatedmerchant_id, user_id, enabled. Zdarzenie aktualizacji obejmuje zmiany e-maila, stanu włączenia i roli administratora.
invitation.accepted / password_reset.completedmerchant_id, user_id, invitation_id.
topup.settled / credit.balance_changedmerchant_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
  }
}

Utwórz sprzedawcę → · Przyjmij zaproszenie →

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.

  1. Włącz Marketplace w projekcie, wybierz uczestniczące sklepy i pozostaw wypłaty wstrzymane podczas konfiguracji.
  2. Zarejestruj sprzedających i niezależnie zweryfikuj ich adresy wypłat. Utworzony adres docelowy oczekuje na zatwierdzenie; zatwierdzenie wymaga destinations.approve.
  3. 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.
  4. 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.
  5. 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.
TematZasada
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ącychFaktura 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łatyIstnieją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 środkiZwykł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ątkiNiedopł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.
ZwrotyPrzygotuj 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.
PonowieniaKaż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.
RewizjeModyfikowalne 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łatyDomyś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 odzyskiwanieNiskie 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 stronicowanieUż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ępuKlucze 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.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
{
  "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 .

LimitSzczegół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 MerchantMaksymalnie 32 KiB w routerze aplikacji. Warstwa brzegowa może odrzucić zbyt duże żądanie przed utworzeniem odpowiedzi błędu JSON.
Lista fakturlimit 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 sklepuNajwyż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ówLimit 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 projektuNajwyżej 20 trwale zapisanych aktywów tokenowych na projekt. Już zarejestrowane aktywa można wykorzystać ponownie bez zajmowania kolejnego miejsca.
IdempotencjaWymagana 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.
MetadaneWyłącznie obiekt JSON, maksymalnie 4096 zakodowanych bajtów i pięć poziomów zagnieżdżenia.
Wywołania zwrotnePubliczny 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ściOdpowiedzi 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 APIZarzą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ż JSONNieprawidł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

HTTPKod błęduZnaczenie
400invalid_reconciliation_actionNieprawidłowy status wyjątku, przyczyna, wyszukiwanie lub filtr strony historii.
500reconciliation_unavailableNie udało się załadować kolejki wyjątków lub dowodów. Ponów odczyt ze zwiększanym odstępem.
402billing_requiredKaż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.
400invalid_jsonNieprawidłowy JSON, nieznane pole lub treść niezgodna z udokumentowanym żądaniem.
400idempotency_key_requiredW żądaniu tworzenia faktury pominięto Idempotency-Key.
400invalid_idempotency_keyKlucz jest pusty, przekracza 128 bajtów, nie jest ASCII, zawiera białe znaki lub bajt sterujący.
400invalid_payment_requestWeryfikowane 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().
400invalid_invoice_statusStatus listy nie mieści się w sześciu udokumentowanych stanach faktury.
400invalid_callback_urlObowiązujący cel IPN nie przeszedł weryfikacji HTTPS, publicznego adresu, DNS lub SSRF.
400invalid_wallet_requestNieprawidłowe dane wejściowe przygotowania portfela/adresu.
400invalid_token_assetNieprawidłowy blockchain tokena, zapytanie o kandydatów, tożsamość CoinGecko, metadane katalogu lub kontrakt/mint.
401authentication_requiredToken bearer jest nieobecny, nieprawidłowy, wyłączony, wymieniony przez rotację lub nieznany.
403source_ip_deniedOgraniczenie IP danych dostępu nie obejmuje dokładnego publicznego adresu źródłowego żądania.
403source_ip_not_allowedOgraniczenie ź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.
503source_access_unavailableWeryfikacja dostępu do nazwy hosta jest tymczasowo niedostępna. Spróbuj później; przy błędzie ograniczenia blokują dostęp.
403 / 409 / 500merchant_api_access_deniedAutoryzacja 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.
403project_access_deniedTransakcyjna ponowna kontrola przy tworzeniu wykryła, że dane dostępu nie mają już dostępu do projektu.
404invoice_not_foundW autoryzowanym projekcie nie ma faktury o tym publicznym identyfikatorze lub strona płatności nie może jej ujawnić.
404payment_resource_not_foundProjekt, sklep, aktywo lub portfel potrzebny podczas przygotowywania faktury już nie istnieje.
404token_candidate_not_foundProjekt jest niedostępny lub token nie występuje już w bieżącym dopasowanym katalogu wykrywania.
409idempotency_conflictKlucz w zakresie sklepu już istnieje, a dane dostępu lub dokładne surowe bajty żądania różnią się.
409store_unavailableProjekt/sklep jest wyłączony lub niedostępny.
409no_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.
409payment_method_unavailableWybrana metoda stała się niedostępna podczas atomowej ponownej kontroli przy tworzeniu.
409store_payment_method_not_selectedZażądano nadpisania potwierdzeń sklepu dla aktywa, które nie jest obecnie wybrane w tym sklepie.
409wallet_unavailablePortfel płatniczy stał się niedostępny podczas atomowej ponownej kontroli przy tworzeniu.
409ipn_secret_requiredIstnieje obowiązujący URL IPN, ale sklep nie ma sekretu podpisującego IPN.
409payment_resource_not_readyWymagane 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.
409account_activation_unverifiedNie 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ę.
400invalid_monero_wallet_rpcNieprawidłowy punkt końcowy HTTPS, dokładny główny adres sieci głównej, etykieta lub kompletne dane uwierzytelniania Digest/Basic/nagłówkiem.
404monero_wallet_rpc_not_foundPowiązanie wallet-RPC Monero w zakresie projektu nie istnieje.
409monero_wallet_rpc_not_readyAktywo Monero, kworum dwóch demonów, niezmienne powiązanie lub jawne poświadczenie kopii zapasowej/trybu tylko do podglądu nie jest gotowe.
409monero_wallet_rpc_unavailableTworzenie faktur wymaga aktywnego, zweryfikowanego i poświadczonego powiązania wallet-RPC Monero projektu z prawidłowymi danymi dostępu po stronie serwera.
503lightning_unavailableJedyną 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.
422monero_wallet_rpc_verification_failedKontrola dokładnego portfela, przypięcia HTTPS, synchronizacji, kworum demonów sieci głównej lub dowodu odmowy metod przez bramę nie powiodła się.
503monero_wallet_rpc_failedZewnętrzny wallet-RPC tylko do obserwacji nie mógł bezpiecznie utworzyć i ponownie odczytać podadresu faktury; nie jest wymyślany żaden adres zastępczy.
409token_chain_not_readyNatywne aktywo blockchaina jest wyłączone, mapowanie wykrywania zmieniło się podczas weryfikacji lub projekt ma już aktualne maksimum 20 zarejestrowanych aktywów tokenowych.
503dex_price_unavailableDostawca 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.
422invalid_dex_priceNieprawidł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.
422token_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.
422invalid_store_confirmation_policyNadpisanie 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ń.
409invoice_not_payableFaktura strony płatności jest w stanie końcowym lub jej termin płatności upłynął.
409invoice_payment_method_lockedPrawidłowa płatność wybrała już inne aktywo; kontynuuj z active_payment_method_id.
409payment_method_not_payableWybrana metoda jest zakończona lub nie przyjmuje już kolejnej płatności.
422payment_qr_unavailableŻądanie płatności jest zbyt duże, aby zakodować je jako obraz QR SVG.
503payment_rates_unavailableBrak świeżej wiarygodnej wyceny dla jakiejkolwiek gotowej metody płatności.
500authentication_unavailableUwierzytelnianie bearer nie mogło bezpiecznie odczytać lub zweryfikować zapisanych danych dostępu.
429rate_limit_exceededTe 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.
500database_error / internal_errorPrzejś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}/payments

Metody 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-policy

Portfele

GETLista portfeli i sald projektu/v1/projects/{project_id}/wallets

Uzgadnianie 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}/resend

API 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/accept

Strona 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.png

Usługa

GETWykrywanie usług API/GETStan usługi/healthz
GETMoż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łówekObecnośćZasada
AuthorizationwymaganeBearer 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"

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

api_versionstring
operator_versionstring
scopes[]array
all_merchantsboolean
merchant_ids[]array
onboarding[]array
write_methods[]array
idempotency_requiredboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer 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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "version": "7.4.0",
  "nodes": []
}

Pola odpowiedzi

versionstring
nodes[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–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"
}'

Treść żądania

namestringwymagane

Nazwa sprzedawcy i globalnie unikalny e-mail pierwszego administratora.

emailstringwymagane

Nazwa sprzedawcy i globalnie unikalny e-mail pierwszego administratora.

onboardingdirect | invitationwymagane

direct wymaga password i nie wysyła e-maila z zaproszeniem. invitation pomija password.

passwordstring · direct only

12–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_changebooleanopcjonalne

Wymaga nowego hasła przy pierwszym logowaniu. Każde bezpośrednio utworzone konto musi potwierdzić powiernictwo hostowanego portfela.

currencyfiat codeopcjonalne

Waluta konta przedpłaconego; domyślnie waluta regionalna, której później nie można zmienić.

fee_bpsintegeropcjonalne

0–10000; 100 oznacza 1%. Przy pominięciu używa wartości domyślnej operatora. Wymaga fees.write.

starting_creditdecimal stringopcjonalne

Dokładne jednorazowe lokalne przyznanie środków. Niezerowa wartość wymaga credits.write. Nie uzupełnia salda instalacji operatora.

external_idstringopcjonalne

Unikalny identyfikator integracji, 1–120 znaków.

default_timezoneIANA timezoneopcjonalne

Domyślnie regionalna strefa czasowa instalacji.

send_invitation_emailbooleanopcjonalne

Tylko 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

merchant_idstring
user_idstring
merchantobject
idstring
namestring
currencystring
balancestring
onboardingstring
email_deliveryobject
statusstring
custody_acceptance_requiredboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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"

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

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

namefieldsopcjonalne
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ć.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ć.

enabledfieldsopcjonalne
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ć.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_pausedfieldsopcjonalne
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ć.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_bpsfieldsopcjonalne
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ć.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_idfieldsopcjonalne
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ć.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

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

emailstringswymagane

E-mail jest unikalny w instalacji.

display_namestringswymagane

E-mail jest unikalny w instalacji.

onboardingsame as merchant creation

Tworzenie zaproszenia wymaga dodatkowo invitations.write.

passwordsame as merchant creation

Tworzenie zaproszenia wymaga dodatkowo invitations.write.

require_password_changesame as merchant creation

Tworzenie zaproszenia wymaga dodatkowo invitations.write.

send_invitation_emailsame as merchant creation

Tworzenie zaproszenia wymaga dodatkowo invitations.write.

access_leveladmin | projectsopcjonalne

admin 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.

default_timezoneIANA timezoneopcjonalne

Przy pominięciu regionalna wartość domyślna.

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
idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
user_idstring
email_deliveryobject
statusstring
merchant_idstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

user_idUUIDwymagane

Kanoniczny 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/users/YOUR_USER_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

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

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

user_idUUIDwymagane

Kanoniczny 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/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"
}'

Treść żądania

emailfieldsopcjonalne

Aktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.

display_namefieldsopcjonalne

Aktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.

enabledfieldsopcjonalne

Aktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.

access_levelfieldsopcjonalne

Aktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.

project_idsfieldsopcjonalne

Aktualizuje podane pola; ochrona ostatniego administratora pozostaje. Hasła mają oddzielną operację users.security.

default_timezonefieldsopcjonalne

Aktualizuje 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

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

user_idUUIDwymagane

Kanoniczny 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/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
}'

Treść żądania

passwordstringwymagane

Zmienia hasło i unieważnia sesje, zachowując TOTP. Wymaga users.security.

require_password_changebooleanopcjonalne

Użytkownik musi ustawić własne hasło przy następnym udanym logowaniu.

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

Pola odpowiedzi

user_idstring
sessions_revokedboolean
totp_preservedboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

user_idUUIDwymagane

Kanoniczny 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/YOUR_USER_ID/revoke-sessions" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

Pola odpowiedzi

user_idstring
sessions_revokedboolean
totp_preservedboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

user_idUUID, boolean

Wystaw/zastąp jednorazowy link dla istniejącego konta. Aktywowani użytkownicy otrzymują link resetu ważny godzinę i wymagają users.security.

send_emailUUID, boolean

Wystaw/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_id

Uż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

user_idstring
emailstring
kindstring
expires_atstring
urlstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

invitation_idUUIDwymagane

Kanoniczny 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"

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

idstring
user_idstring
merchant_idstring
kindstring
statusstring
created_atstring
expires_atstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

invitation_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

send_emailbooleanopcjonalne

Zastę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

user_idstring
emailstring
kindstring
expires_atstring
urlstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

invitation_idUUIDwymagane

Kanoniczny 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 '{}'

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "revoked": true,
  "invitation_id": "44444444-4444-4444-8444-444444444444"
}

Pola odpowiedzi

revokedboolean
invitation_idstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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"

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

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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.

qopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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"
}'

Treść żądania

amountsigned decimal stringwymagane

Dodatnie przyznanie lub ujemna korekta, do sześciu miejsc dziesiętnych w walucie salda sprzedawcy. Nie jest to przelew on-chain.

notestringwymagane

Uzasadnienie zachowane w księdze dopuszczającej tylko dopisywanie.

request_idUUIDwymagane

Zapisz trwale wraz z kwotą i uzasadnieniem, dodatkowo obok HTTP Idempotency-Key.

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "balance": "25"
}

Pola odpowiedzi

balancestring
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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"
}'

Treść żądania

amountdecimal stringwymagane

Co najmniej jedna jednostka waluty salda sprzedawcy. Wymaga gotowego sklepu odbiorczego Operator.

request_idUUIDwymagane

Zachowaj między ponowieniami. Zwraca istniejącą fakturę, jeśli już ją utworzono. Środki są dodawane dopiero po zaobserwowanym rozliczeniu.

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

idstring
invoice_idstring
checkout_urlstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

topup_idUUIDwymagane

Kanoniczny 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/topups/YOUR_TOPUP_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

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

idstring
merchant_idstring
invoice_idstring
amountstring
currencystring
statusstring
invoice_statusstring
checkout_urlstring
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

Kody błędów i zasady ponowień

GETRaporty/v1/operator/reportsTylko odczyt

Odczytaj przegląd finansowy Operator. Wymaga dostępu do wszystkich hostowanych sprzedawców.

Uwierzytelnianie i nagłówki
NagłówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry zapytania

periodopcjonalne

Filtry 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.

startopcjonalne

Filtry 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.

endopcjonalne

Filtry 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.

currencyopcjonalne

Filtry 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_idopcjonalne

Filtry 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"

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

summaryobject
feesstring
costsstring
marginstring
creditsstring
pendinginteger
missing_ratesinteger
merchants[]array
filtersobject
periodstring
currencystring
timezonestring
basisstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry zapytania

merchant_idopcjonalne

Filtruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry zapytania

merchant_idopcjonalne

Filtruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.

event_typeopcjonalne

Filtruj dozwolonego sprzedawcę, dokładny typ zdarzenia (events) lub tekst działania (audit). Przechowywanie zdarzeń: 30 dni.

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–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
}'

Treść żądania

urlpublic HTTPS URLwymagane

Bez danych dostępu, prywatnych IP ani przekierowań. DNS/IP są ponownie sprawdzane przy dostarczaniu.

events[]string[]wymagane

Wybierz zdarzenia cyklu życia z przewodnika Operator, nie wywołania zwrotne faktur.

merchant_ids[]UUID[]opcjonalne

Pusta wartość oznacza wszystkich sprzedawców dozwolonych dla tych danych dostępu. Bieżące ograniczenia zakresu są ponownie sprawdzane.

enabledbooleanopcjonalne

Wstrzymane 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

idstring
signing_secretstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

webhook_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

urlpublic HTTPS URLwymagane

Bez danych dostępu, prywatnych IP ani przekierowań. DNS/IP są ponownie sprawdzane przy dostarczaniu.

events[]string[]wymagane

Wybierz zdarzenia cyklu życia z przewodnika Operator, nie wywołania zwrotne faktur.

merchant_ids[]UUID[]opcjonalne

Pusta wartość oznacza wszystkich sprzedawców dozwolonych dla tych danych dostępu. Bieżące ograniczenia zakresu są ponownie sprawdzane.

enabledbooleanopcjonalne

Wstrzymane 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

idstring
signing_secretJSON | null
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

webhook_idUUIDwymagane

Kanoniczny 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 '{}'

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "id": "11111111-1111-4111-8111-111111111111",
  "signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}

Pola odpowiedzi

idstring
signing_secretstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

webhook_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

namestringswymagane

Nazwa i unikalny stabilny identyfikator projektu. Tworzy lokalne portfele przy użyciu istniejącej inicjalizacji projektu, nigdy nie przenosi środków.

slugstringswymagane

Nazwa i unikalny stabilny identyfikator projektu. Tworzy lokalne portfele przy użyciu istniejącej inicjalizacji projektu, nigdy nie przenosi środków.

enabledopcjonalne

enabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.

reporting_timezoneopcjonalne

enabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.

checkout_titleopcjonalne

enabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.

checkout_descriptionopcjonalne

enabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.

checkout_themeopcjonalne

enabled domyślnie ma wartość true; zaleca się utworzenie w stanie wstrzymanym i wcześniejsze skonfigurowanie sklepu.

checkout_accent_coloropcjonalne

enabled 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

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny 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" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

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

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny 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" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'

Treść żądania

nameopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

enabledopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

reporting_currencyopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

reporting_timezoneopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

checkout_titleopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

checkout_descriptionopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

checkout_themeopcjonalne

Częściowa aktualizacja. Identyfikatora i przypisania do sprzedawcy nie można zmienić.

checkout_accent_coloropcjonalne

Częś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

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny 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" \
  --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
}'

Treść żądania

namestringswymagane

Nazwa sklepu i stabilny identyfikator.

slugstringswymagane

Nazwa sklepu i stabilny identyfikator.

default_currencyopcjonalne

Dla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.

invoice_expiry_minutesopcjonalne

Dla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.

exchange_rate_spread_percentopcjonalne

Dla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.

underpayment_tolerance_percentopcjonalne

Dla procentów używaj ciągów dziesiętnych. Nowe sklepy dziedziczą wygląd domyślnego sklepu projektu.

enabledopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

is_defaultopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

allow_zero_amount_invoicesopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

allow_underpaymentsopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

allow_overpaymentsopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

allowed_chain_slugsopcjonalne

Konfiguruj akceptowane aktywa przez payment-assets; faktury na zerową kwotę są domyślnie wyłączone.

ipn_enabledopcjonalne

Adresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.

default_ipn_urlopcjonalne

Adresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.

default_redirect_urlopcjonalne

Adresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.

default_cancel_urlopcjonalne

Adresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.

redirect_automaticallyopcjonalne

Adresy IPN i powrotne podlegają istniejącej walidacji URL. Bez dowolnego HTML/JavaScript.

checkout_languageopcjonalne

Używaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.

embed_enabledopcjonalne

Używaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.

allowed_embed_originsopcjonalne

Używaj obsługiwanego języka i aktywnych domen ról; jawnie skonfiguruj originy osadzania.

domainsopcjonalne

Uż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

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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"

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

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

store fieldsopcjonalne

Te same modyfikowalne ustawienia co przy tworzeniu sklepu, poza slug. Zmieniają się tylko podane pola.

enabledboolean

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

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "revision": 1,
  "settings": {
    "inherit_default_store": true
  },
  "effective": {
    "title": "Pay securely"
  }
}

Pola odpowiedzi

revisioninteger
settingsobject
inherit_default_storeboolean
effectiveobject
titlestring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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"
  }
}'

Treść żądania

revisionintegerwymagane

Najpierw 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.

inherit_default_storeboolean
titlestring
themestring

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "settings": {
    "inherit_default_store": false,
    "title": "Pay securely",
    "theme": "light"
  },
  "revision": 2
}

Pola odpowiedzi

settingsobject
inherit_default_storeboolean
titlestring
themestring
revisioninteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": []
}

Pola odpowiedzi

data[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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
    }
  ]
}'

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.

asset_idstring
display_orderinteger

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": []
}

Pola odpowiedzi

data[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

namestrings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

urlstrings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

event_types[]strings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

enabledbooleansopcjonalne

Tworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.

automatic_redeliverybooleansopcjonalne

Tworzenie 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

signing_secretstring
endpointobject
idstring
namestring
enabledboolean
secret_visible_onceboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

store_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

webhook_idUUIDwymagane

Kanoniczny 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
}'

Treść żądania

namestrings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

urlstrings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

event_types[]strings / arraywymagane

Publiczny odbiornik HTTPS i nazwy zdarzeń faktur z dokumentacji IPN i webhooków.

enabledbooleansopcjonalne

Tworzenie zwraca sekret podpisujący jeden raz. To wywołania zwrotne płatności sklepu, nie zdarzenia cyklu życia Operator.

automatic_redeliverybooleansopcjonalne

Tworzenie 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

idstring
namestring
enabledboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

limitopcjonalne

Stronicowanie i filtry faktur, takie same jak na liście faktur projektu.

offsetopcjonalne

Stronicowanie i filtry faktur, takie same jak na liście faktur projektu.

statusopcjonalne

Stronicowanie i filtry faktur, takie same jak na liście faktur projektu.

store_idopcjonalne

Stronicowanie i filtry faktur, takie same jak na liście faktur projektu.

Żą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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

Pola odpowiedzi

data[]array
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

invoice_idUUIDwymagane

Kanoniczny 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"

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

invoice_idstring
project_idstring
amountstring
currencystring
statusstring
metadataobject
payment_intents[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

project_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

wallet_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

limitopcjonalne
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.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.

beforeopcjonalne
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.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_balanceopcjonalne
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.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_balancesopcjonalne
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.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"

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

walletobject
idstring
chain_slugstring
items[]array
totalinteger
total_pagesinteger
next_cursorJSON | null
reporting_currencystring
has_balanceboolean
hide_small_balancesboolean
small_balance_thresholdobject
amountstring
currencystring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

Parametry zapytania

pageopcjonalne
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.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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Pola odpowiedzi

data[]array
pageinteger
page_sizeinteger
totalinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny 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"
  ]
}'

Treść żądania

namestringwymagane

Etykieta nowego zwykłego klucza sprzedawcy, nie klucza Operator.

access_levelread_only | read_writeopcjonalne

Odczyt/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.

enabledopcjonalne

Istniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.

ip_restriction_enabledopcjonalne

Istniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.

allowed_ips[]opcjonalne

Istniejące mechanizmy kontroli klucza sprzedawcy. Sekret zwracany tylko raz; wymaga merchant_credentials.write.

requests_per_minuteopcjonalne

Istnieją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

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

credential_idUUIDwymagane

Kanoniczny 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/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"
  ]
}'

Treść żądania

namefieldswymagane

Wyś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_levelfieldswymagane

Wyś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.

enabledfieldswymagane

Wyś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_enabledfieldswymagane

Wyś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[]fieldswymagane

Wyś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[]array

Odpowiedź 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

idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

credential_idUUIDwymagane

Kanoniczny 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/YOUR_CREDENTIAL_ID/rotate" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

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

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisane trwale dla tej operacji

Parametry ścieżki

merchant_idUUIDwymagane

Kanoniczny UUID zasobu zapisany małymi literami; musi należeć do zakresu sprzedawców danych dostępu.

credential_idUUIDwymagane

Kanoniczny 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/YOUR_CREDENTIAL_ID/revoke" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "revoked": true
}

Pola odpowiedzi

revokedboolean
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

Kody błędów i zasady ponowień

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"
}'

Treść żądania

tokenstringwymagane

Sekret z fragmentu adresu URL zaproszenia. Nigdy go nie zapisuj w dziennikach.

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "kind": "invitation",
  "email": "admin@example.test",
  "merchant_name": "Example shop"
}

Pola odpowiedzi

kindstring
emailstring
merchant_namestring
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

Kody błędów i zasady ponowień

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
}'

Treść żądania

tokenstringwymagane

Sekret z fragmentu adresu URL zaproszenia. Nigdy go nie zapisuj w dziennikach.

passwordstringwymagane

Nowe hasło, 12–128 znaków (najwyżej 512 bajtów UTF-8).

custody_acknowledgedboolean

Musi mieć wartość true przy przyjmowaniu nowego zaproszenia do hostowanego portfela.

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "password_set": true
}

Pola odpowiedzi

password_setboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

GETUstawienia projektu/v1/marketplace/settingsTylko odczyt

Zwraca enabled, payouts_paused, commission_percent, revision i uczestniczące sklepy.

Uwierzytelnianie i nagłówki
NagłówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepolicies.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
    }
  ]
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

0

enabled

true

payouts_paused

true

commission_percent

"4"

stores[]object[]

[{"store_id":"YOUR_STORE_ID","enabled":true,"commission_percent":null}]

store_idstring
enabledboolean
commission_percentJSON | null

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopevendors.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

name

"Example vendor"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

GETPobierz sprzedającego/v1/marketplace/vendors/{vendor_id}Tylko odczyt

Zwróć jednego sprzedającego, rewizję i nadpisanie prowizji.

Uwierzytelnianie i nagłówki
NagłówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopevendors.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

name

"Example vendor"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopevendors.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopedestinations.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

chain_slug

"bitcoin"

network

"mainnet"

address

"VERIFIED_VENDOR_BTC_ADDRESS"

label

"Vendor BTC"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopedestinations.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopedestinations.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopeinvoices.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"
    }
  ]
}'

Treść żądania

amountstringwymagane
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.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 | nullopcjonalne
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ń.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_slugstringwymagane
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.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[] | nullopcjonalne
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.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[] | nullopcjonalne
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.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 | lightningopcjonalne
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.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 | nullopcjonalne

Identyfikator zamówienia sprzedawcy, 1–128 znaków po przycięciu; znaki sterujące są odrzucane.

emailstring | nullopcjonalne

E-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 | nullopcjonalne

Opis widoczny dla klienta, 1–500 znaków; dozwolone są podziały wierszy i tabulatory.

expires_in_secondsinteger | nullopcjonalne

Czas ważności wyceny faktury od 300 do 86 400 sekund; pominięcie lub null dziedziczy politykę sklepu.

exchange_rate_spread_percentdecimal string | nullopcjonalne
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.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 | nullopcjonalne

Akceptowana 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 | nullopcjonalne

Publiczne 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 | nullopcjonalne

Adres 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 | nullopcjonalne

Adres 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 | nullopcjonalne

Pominięcie lub null dziedziczy politykę sklepu. true wymaga obowiązującego redirect_url.

languagestring | nullopcjonalne
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.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_storebooleanopcjonalne
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.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.

titlestringopcjonalne

Nagłówek strony płatności, do 120 znaków. Pusty używa standardowego nagłówka.

introstringopcjonalne
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.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.

outrostringopcjonalne
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.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_sizeintegeropcjonalne

Piksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.

outro_font_sizeintegeropcjonalne

Piksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.

themesystem | light | dim | darkopcjonalne

Dopasuj do urządzenia klienta lub użyj stałego motywu.

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.

logo_sizestringopcjonalne

small, medium lub large; left lub center.

logo_alignmentstringopcjonalne

small, medium lub large; left lub center.

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
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
logo_darkobject | nullopcjonalne
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
faviconobject | nullopcjonalne
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
show_order_idbooleanopcjonalne

Pokaż 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_descriptionbooleanopcjonalne

Pokaż 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_expandedbooleanopcjonalne

Pokaż 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_namebooleanopcjonalne
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.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_namebooleanopcjonalne
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.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[]opcjonalne
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.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[]opcjonalne
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.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|nullopcjonalne
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.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
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
deobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
esobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
pt-BRobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
itobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
ruobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
zh-CNobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
frobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
koobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
jaobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
support_emailstringopcjonalne

E-mail ASCII, do 254 znaków. Pusty czyści.

support_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

terms_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

privacy_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

return_button_textstringopcjonalne

Etykieta do 60 znaków. Do zachowania faktury używaj najwyższego poziomu redirect_url/cancel_url/redirect_automatically/language.

show_return_buttonbooleanopcjonalne
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.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.

firstnamestringopcjonalne
lastnamestringopcjonalne
streetstringopcjonalne
street2stringopcjonalne
zipstringopcjonalne
citystringopcjonalne
countrystringopcjonalne
countryiso2stringopcjonalne
companystringopcjonalne
vatidstringopcjonalne
project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

store_id

"YOUR_STORE_ID"

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"}]

vendor_idstring
gross_amountstring

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

dataobject
invoice_idstring
statusstring
marketplaceobject
statestring
allocations[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopeinvoices.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopereconciliation.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

reason

"Verify customer request"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopereconciliation.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

reason

"Verified payment evidence"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopereconciliation.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

destination_id

"YOUR_DESTINATION_ID"

reason

"Vendor verified replacement address"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopereconciliation.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepayouts.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepayouts.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"
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

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

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

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

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepayouts.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepayouts.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepayouts.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": []
}

Pola odpowiedzi

data[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopepolicies.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

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

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

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

dataobject
endpoints[]array
event_types[]array
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopewebhooks.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"
  ]
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed","marketplace.payout.failed"]

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopewebhooks.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"
  ]
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed"]

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

POSTWyłącz webhook platformy handlowej/v1/marketplace/webhooks/{webhook_id}/disableOdczyt + zapis

Zatrzymaj nowe dostarczenia; zachowana historia zdarzeń pozostaje.

Uwierzytelnianie i nagłówki
NagłówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopewebhooks.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

revision

1

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

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

dataobject
event_idstring
event_typestring
payload_versioninteger
project_idstring
occurred_atstring
dataobject
payout_idstring
asset_idstring
amount_atomicstring
transactions[]object[]
transaction_idstring
explorer_urlstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Pola odpowiedzi

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
ParametrTyp / lokalizacjaZasada
permissioncredential scopemarketplace.read

Parametry zapytania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

per_pageopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

qopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

statusopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

store_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

vendor_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

asset_idopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

fromopcjonalne

Używaj tylko filtrów udokumentowanych dla tego zasobu. Listy stronicowane domyślnie zawierają 25 wierszy i dopuszczają do 100.

toopcjonalne

Uż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"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keywymagane16–128 liter, cyfr, -, _ lub .; zapisz trwale z dokładnie tym żądaniem
ParametrTyp / lokalizacjaZasada
permissioncredential scopewebhooks.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
}'

Treść żądania

project_idUUIDwymagane

Autoryzowany projekt. Wymagany w każdym żądaniu, również w adresach URL elementów.

confirm

true

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "data": {}
}

Pola odpowiedzi

dataobject
Uwagi 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do tych danych dostępu.

Parametry zapytania

statusstring

open (domyślnie), resolved lub all.

reasonstring

underpaid, overpaid, late, reorged, ambiguous, delivery_failed, disabled_method lub expired_method.

store_idUUID

Opcjonalny filtr sklepu.

pageinteger

1–40001. Stałe 25 spraw na stronę.

Żą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"

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.

idUUIDzawsze

Wewnętrzny identyfikator rekordu / UUID faktury widoczny dla klienta. invoice_id odpowiada treściom wywołań zwrotnych.

invoice_idUUIDzawsze

Wewnętrzny identyfikator rekordu / UUID faktury widoczny dla klienta. invoice_id odpowiada treściom wywołań zwrotnych.

store_idUUIDzawsze

Sklep właścicielski.

store_namestringzawsze

Sklep właścicielski.

order_idstring | nullzawsze

Prywatny identyfikator zamówienia sprzedawcy i e-mail klienta.

emailstring | nullzawsze

Prywatny identyfikator zamówienia sprzedawcy i e-mail klienta.

amountdecimal stringzawsze

Pierwotna kwota i waluta fiducjarna faktury.

currencystringzawsze

Pierwotna kwota i waluta fiducjarna faktury.

invoice_statusinvoice statuszawsze

Bieżący status cyklu życia płatności.

statusopen|resolvedzawsze

Stan sprawy i typy wyjątków wymienione w filtrze reason.

reasons[]string[]zawsze

Stan sprawy i typy wyjątków wymienione w filtrze reason.

revisionintegerzawsze

Bieżąca rewizja przeglądu i czas aktualizacji.

updated_attimestampzawsze

Bieżąca rewizja przeglądu i czas aktualizacji.

paginationobjectzawsze

page (1–40001), per_page (25), łączna liczba pasujących wierszy, has_more.

pageinteger
per_pageinteger
totalinteger
has_moreboolean
countsobjectzawsze

Sumy open i resolved dla całego projektu, niezależne od bieżących filtrów.

openinteger
resolvedinteger
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN

Parametry ścieżki

project_idUUIDwymagane

Przypisany projekt.

invoice_idUUIDwymagane

Publiczny UUID faktury, nie wewnętrzne id.

Parametry zapytania

pageinteger

Strona historii decyzji, od 1; 25 decyzji na stronę.

Żą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"

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.

idUUIDzawsze

Wewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.

invoice_idUUIDzawsze

Publiczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.

project_idUUIDzawsze

Projekt właścicielski.

store_idUUIDzawsze

Sklep właścicielski.

sourcemanual | apizawsze

Sposób utworzenia faktury.

order_idstring | nullzawsze

Identyfikator zamówienia sprzedawcy.

emailstring | nullzawsze

E-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.

customer_namestring | nullzawsze

Nazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.

customer_addressstring | nullzawsze

Jednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.

descriptionstring | nullzawsze

Opis widoczny dla klienta.

amountdecimal stringzawsze

Kanoniczna kwota faktury.

currencystringzawsze

Znormalizowany kod waluty/aktywa faktury.

exchange_rate_spread_percentdecimal stringzawsze

Zablokowany 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 stringzawsze

Niezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.

statusinvoice statuszawsze

new, processing, settled, expired, invalid lub cancelled.

amount_statusamount statuszawsze

none, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.

timing_statustiming statuszawsze

on_time lub late.

resolutionresolutionzawsze

automatic, manually_settled lub manually_invalidated.

sequenceintegerzawsze

Monotoniczna sekwencja stanu faktury, zaczynająca się od 1.

winning_payment_intent_idUUID | nullzawsze

Metoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.

expires_atRFC 3339 timestampzawsze

Termin wyceny/płatności.

monitoring_expires_atRFC 3339 timestampzawsze

Najpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.

settled_attimestamp | nullzawsze

Czas rozliczenia, jeśli rozliczona.

cancelled_attimestamp | nullzawsze

Czas anulowania, jeśli anulowana.

archived_attimestamp | nullzawsze

Czas archiwizacji, jeśli zarchiwizowana.

created_atRFC 3339 timestampzawsze

Czas utworzenia.

updated_atRFC 3339 timestampzawsze

Czas ostatniej aktualizacji stanu.

ipn_urlstring | nullzawsze

Obowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.

redirect_urlstring | nullzawsze

Obowiązujący URL sukcesu używany po rozliczeniu.

cancel_urlstring | nullzawsze

Obowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.

redirect_automaticallybooleanzawsze

Czy strona płatności powinna automatycznie przekierować po sukcesie.

checkout_languagestringzawsze

Obowiązujący znacznik języka strony płatności.

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.

idUUIDzawsze

Identyfikator intencji płatności; używany też jako intent_id kodu QR płatności.

payment_railonchain | lightningzawsze
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.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_idUUIDzawsze

Identyfikator skonfigurowanego aktywa płatniczego.

asset_keystringzawsze

Kanoniczny klucz aktywa w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto.

networkstringzawsze

Skonfigurowana sieć, obecnie mainnet dla obsługiwanych aktywów płatniczych.

caip_network_idstringzawsze

Kanoniczny identyfikator sieci CAIP-2.

caip_asset_idstring | nullzawsze

Kanoniczny identyfikator CAIP-19, jeśli zarejestrowany.

symbolstringzawsze

Symbol aktywa.

asset_decimalsintegerzawsze

Precyzja 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.

statusintent statuszawsze

pending, partial, paid, overpaid, expired lub invalid.

finality_modeconfirmations | finalizedzawsze

Polityka ostateczności.

required_confirmationsintegerzawsze

Wymagana liczba potwierdzeń, jeśli dotyczy.

quote_ratedecimal stringzawsze

Jednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.

quote_detailsobject | nullzawsze
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.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 stringzawsze
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.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.

expected_amount_atomicinteger stringzawsze

Dokładna kwota w najmniejszej jednostce aktywa.

minimum_payment_amountdecimal stringzawsze

Najmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.

minimum_payment_amount_atomicinteger stringzawsze

Dokładny akceptowany próg w najmniejszej jednostce aktywa.

received_amountdecimal stringzawsze

Zaobserwowana kwota.

received_amount_atomicinteger stringzawsze

Zaobserwowana kwota atomowa.

confirmed_amountdecimal stringzawsze

Potwierdzona/ostateczna kwota.

confirmed_amount_atomicinteger stringzawsze

Potwierdzona/ostateczna kwota atomowa.

destination_addressstringzawsze

Adres 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 | nullzawsze

Wymagany 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_indexintegerzawsze

Zarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.

quote_expires_atRFC 3339 timestampzawsze

Termin ważności wyceny.

monitoring_expires_atRFC 3339 timestampzawsze

Koniec monitorowania spóźnionych płatności dla tej metody.

next_check_attimestamp | nullzawsze

Następne zaplanowane sprawdzenie blockchaina.

last_checked_attimestamp | nullzawsze

Ostatnie sprawdzenie blockchaina.

last_chain_heightinteger | nullzawsze

Ostatnia wiarygodna wysokość zaobserwowana przez monitor.

last_anchor_hashstring | nullzawsze

Ostatnia kotwica/hash bloku monitora.

last_monitor_errorstring | nullzawsze

Bezpieczna diagnostyka monitorowania dla operatorów.

first_payment_attimestamp | nullzawsze

Czas pierwszej zaobserwowanej płatności.

fully_paid_attimestamp | nullzawsze

Czas pierwszego osiągnięcia akceptowanej kwoty minimalnej.

finalized_attimestamp | nullzawsze

Czas spełnienia polityki ostateczności płatności.

caseobject | nullzawsze

Bieżąca sprawa ze statusem, przyczynami, rewizją i znacznikami czasu; null, gdy nie ma wyjątku. Wewnętrzne dowody są wykluczone.

statusstring
reasons[]array
revisioninteger
methods[]object[]zawsze
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.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[]zawsze

Najnowsze 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.

pageinteger
per_pageinteger
totalinteger
refunds[]object[]zawsze
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.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[]zawsze
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.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[]zawsze

Najnowsze 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

Kody błędów i zasady ponowień

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/"

Odpowiedź 200 application/json

Przykładowa odpowiedź
{
  "service": "Wholly Crypto API",
  "status": "ready",
  "version": "v1"
}

Pola odpowiedzi

servicestring
statusstring
versionstring
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

Kody błędów i zasady ponowień

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"

Odpowiedź 200 healthy; 503 database unavailable

Przykładowa odpowiedź
{
  "status": "ok",
  "database": "ok",
  "version": "0.1.0"
}

Pola odpowiedzi

statusstring
databasestring
versionstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do 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/projects/YOUR_PROJECT_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

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.

idUUIDzawsze

Trwały identyfikator aktywa płatniczego używany przez trasy polityk projektu i sklepu.

asset_keystringzawsze

Kanoniczna tożsamość aktywa natywnego lub kontraktowego w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

networkstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

caip_network_idstringzawsze

Kanoniczne tożsamości sieci i aktywa.

caip_asset_idstring|nullzawsze

Kanoniczne tożsamości sieci i aktywa.

asset_kindnative | tokenzawsze

Czy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.

payment_railstringzawsze

Kanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.

symbolstringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

namestringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

decimalsintegerzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.

coingecko_idstring | nullzawsze

Toż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_tokenbooleanzawsze

Niestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.

icon_pathpath | nullzawsze

Lokalnie buforowana ikona tokena, jeśli dostępna.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.

metadata_verified_attimestamp | nullzawsze

Czas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.

payment_supportedbooleanzawsze
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.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_readybooleanzawsze
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.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_readybooleanzawsze
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.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 | finalizedzawsze

Domyślny model ostateczności dziedziczony przez nową politykę projektu.

default_required_confirmationsintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

default_monitoring_minutesintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

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.

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

walletobject | nullzawsze

Niepowierniczy portfel projektu w tym blockchainie. Tokeny współdzielą natywny portfel swojego blockchaina.

idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

wallet_readinessreadiness enumzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Content-Typewymaganeapplication/json
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do danych dostępu.

asset_idUUIDwymagane

Identyfikator aktywa zwrócony przez listę aktywów projektu lub rejestrację tokena.

Żą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
}'

Treść żądania

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

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.

idUUIDzawsze

Trwały identyfikator aktywa płatniczego używany przez trasy polityk projektu i sklepu.

asset_keystringzawsze

Kanoniczna tożsamość aktywa natywnego lub kontraktowego w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

networkstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

caip_network_idstringzawsze

Kanoniczne tożsamości sieci i aktywa.

caip_asset_idstring|nullzawsze

Kanoniczne tożsamości sieci i aktywa.

asset_kindnative | tokenzawsze

Czy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.

payment_railstringzawsze

Kanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.

symbolstringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

namestringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

decimalsintegerzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.

coingecko_idstring | nullzawsze

Toż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_tokenbooleanzawsze

Niestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.

icon_pathpath | nullzawsze

Lokalnie buforowana ikona tokena, jeśli dostępna.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.

metadata_verified_attimestamp | nullzawsze

Czas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.

payment_supportedbooleanzawsze
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.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_readybooleanzawsze
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.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_readybooleanzawsze
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.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 | finalizedzawsze

Domyślny model ostateczności dziedziczony przez nową politykę projektu.

default_required_confirmationsintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

default_monitoring_minutesintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

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.

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

walletobject | nullzawsze

Niepowierniczy portfel projektu w tym blockchainie. Tokeny współdzielą natywny portfel swojego blockchaina.

idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

wallet_readinessreadiness enumzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do danych dostępu.

Parametry zapytania

chain_slugstring

Wymagany slug obsługiwanego blockchaina EVM lub solana.

qstring

Opcjonalny fragment nazwy, symbolu, identyfikatora CoinGecko, kontraktu lub mint; najwyżej 80 znaków.

limitinteger

Opcjonalnie 1–100; domyślnie 50.

Żą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"

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[]
coingecko_idstringzawsze

Tożsamość wykrywania CoinGecko używana przez żądanie rejestracji.

chain_slugstringzawsze

Dopasowany blockchain Wholly Crypto.

symbolstringzawsze

Tożsamość katalogowa do wyświetlania.

namestringzawsze

Tożsamość katalogowa do wyświetlania.

contract_addressstringzawsze

Dopasowany kontrakt lub mint; jest weryfikowany on-chain przed rejestracją.

market_cap_rankinteger | nullzawsze

Pozycja wykrywania, nie sygnał zaufania ani gotowości płatności.

icon_pathpathzawsze

Ścieżka lokalnie buforowanej ikony CoinGecko.

current_price_usddecimal string | nullzawsze

Orientacyjna buforowana cena w USD.

token_standarderc20 | spl-tokenzawsze

Standard tokena obsługiwany przez wybrany adapter blockchaina.

scanner_readybooleanzawsze

True tylko dla kandydatów na kanale tokenów zaimplementowanym w tej kompilacji.

registered_asset_idUUID | nullzawsze

Istniejące trwałe aktywo, jeśli już dodane do rejestru.

project_enabledbooleanzawsze

Czy zarejestrowane aktywo jest włączone w tym projekcie.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Content-Typewymaganeapplication/json
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do danych dostępu.

Żą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
}'

Treść żądania

chain_slugstringwymagane

ethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism lub solana.

coingecko_idstringwymagane
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.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.

enabledbooleanopcjonalne

Stan polityki projektu po weryfikacji; domyślnie true.

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
asset_idUUIDzawsze

Trwały identyfikator aktywa płatniczego.

chain_slugstringzawsze

Zweryfikowany blockchain i zachowana tożsamość wykrywania/wyceny.

coingecko_idstringzawsze

Zweryfikowany blockchain i zachowana tożsamość wykrywania/wyceny.

contract_addressstringzawsze

Kanoniczny zweryfikowany kontrakt lub mint.

token_standarderc20 | spl-tokenzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym.

symbolstringzawsze

Zarejestrowana tożsamość do wyświetlania i dokładna precyzja.

namestringzawsze

Zarejestrowana tożsamość do wyświetlania i dokładna precyzja.

decimalsintegerzawsze

Zarejestrowana tożsamość do wyświetlania i dokładna precyzja.

enabledbooleanzawsze

Początkowy stan polityki projektu.

metadata_verified_atRFC 3339 timestampzawsze

Czas weryfikacji on-chain.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN

Parametry ścieżki

project_idUUIDwymagane

Przypisany projekt.

Parametry zapytania

chain_slugstring

Obsługiwany blockchain tokenów EVM lub solana.

contract_addressstring

Dokładny kontrakt ERC-20 lub klasyczny mint SPL.

Żą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"

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_addressstringzawsze

Dokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.

dex_idstringzawsze

Dokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.

quote_symbolstringzawsze

Dokładny identyfikator puli, identyfikator giełdy (np. uniswap/pancakeswap) i symbol pary wyłącznie do wyświetlania.

price_usddecimal stringzawsze

Cena 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 stringzawsze

Cena 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 timestampzawsze

Czas pobrania obserwacji dostawcy przez serwer, nie znacznik czasu transakcji on-chain.

urlHTTPS URLzawsze

Zweryfikowany link DEX Screener do tej puli.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Content-Typewymaganeapplication/json

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do tych danych dostępu z prawem zapisu.

Żą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"
}'

Treść żądania

chain_slugstringwymagane

ethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism lub solana. Stałe dla tego kontraktu.

contract_addressstringwymagane
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.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.

namestringwymagane
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.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.

symbolstringwymagane
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.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 | dexopcjonalne

Domyślnie fixed dla zgodności wstecznej. DEX używa konkretnej puli wykrytej dla dokładnego blockchaina i kontraktu.

price_usddecimal stringtryb fixed

Stał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 dex
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.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

dataobject
asset_idstring
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do danych dostępu; może być wstrzymany.

store_idUUIDwymagane

Sklep należący do project_id; może być wstrzymany.

Żą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"

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.

idUUIDzawsze

Trwały identyfikator aktywa płatniczego używany przez trasy polityk projektu i sklepu.

asset_keystringzawsze

Kanoniczna tożsamość aktywa natywnego lub kontraktowego w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

networkstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

caip_network_idstringzawsze

Kanoniczne tożsamości sieci i aktywa.

caip_asset_idstring|nullzawsze

Kanoniczne tożsamości sieci i aktywa.

asset_kindnative | tokenzawsze

Czy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.

payment_railstringzawsze

Kanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.

symbolstringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

namestringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

decimalsintegerzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.

coingecko_idstring | nullzawsze

Toż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_tokenbooleanzawsze

Niestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.

icon_pathpath | nullzawsze

Lokalnie buforowana ikona tokena, jeśli dostępna.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.

metadata_verified_attimestamp | nullzawsze

Czas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.

payment_supportedbooleanzawsze
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.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_readybooleanzawsze
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.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_readybooleanzawsze
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.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 | finalizedzawsze

Domyślny model ostateczności dziedziczony przez nową politykę projektu.

default_required_confirmationsintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

default_monitoring_minutesintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

project_policyobject | nullzawsze

Nadrzędna polityka projektu.

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

selectedbooleanzawsze
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.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.

display_orderinteger | nullzawsze

Kolejność na stronie płatności sklepu, gdy wybrana.

confirmation_policyobject | nullzawsze

Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.

finality_modeconfirmations | finalizedzawsze

Czy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.

project_required_confirmationsintegerzawsze

Bieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.

override_required_confirmationsinteger | nullzawsze

Liczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.

effective_required_confirmationsintegerzawsze

Liczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.

editablebooleanzawsze

False dla sieci finalized, których polityki ostateczności nie można nadpisać.

minimum_required_confirmationsintegerzawsze

Dolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.

maximum_required_confirmationsintegerzawsze

Górna granica właściwa dla blockchaina, włącznie.

walletobject | nullzawsze

Portfel blockchaina współdzielony przez aktywa natywne i tokeny.

idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

wallet_readinessreadiness enumzawsze

Tylko 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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

lightningobject
payment_railstring
symbolstring
asset_decimalsinteger
enabledboolean
readyboolean
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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Content-Typewymaganeapplication/json
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do danych dostępu; może być wstrzymany.

store_idUUIDwymagane

Sklep należący do project_id; może być wstrzymany.

Żą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
    }
  ]
}'

Treść żądania

assets[]object[]wymagane

Pełna lista zastępująca, najwyżej 64 wpisy. Każdy wpis zawiera unikalne asset_id i unikalne display_order od 0 do 10 000.

asset_idUUIDwymagane
display_orderintegeropcjonalne

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.

idUUIDzawsze

Trwały identyfikator aktywa płatniczego używany przez trasy polityk projektu i sklepu.

asset_keystringzawsze

Kanoniczna tożsamość aktywa natywnego lub kontraktowego w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

networkstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

caip_network_idstringzawsze

Kanoniczne tożsamości sieci i aktywa.

caip_asset_idstring|nullzawsze

Kanoniczne tożsamości sieci i aktywa.

asset_kindnative | tokenzawsze

Czy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.

payment_railstringzawsze

Kanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.

symbolstringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

namestringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

decimalsintegerzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.

coingecko_idstring | nullzawsze

Toż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_tokenbooleanzawsze

Niestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.

icon_pathpath | nullzawsze

Lokalnie buforowana ikona tokena, jeśli dostępna.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.

metadata_verified_attimestamp | nullzawsze

Czas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.

payment_supportedbooleanzawsze
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.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_readybooleanzawsze
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.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_readybooleanzawsze
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.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 | finalizedzawsze

Domyślny model ostateczności dziedziczony przez nową politykę projektu.

default_required_confirmationsintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

default_monitoring_minutesintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

project_policyobject | nullzawsze

Nadrzędna polityka projektu.

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

selectedbooleanzawsze
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.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.

display_orderinteger | nullzawsze

Kolejność na stronie płatności sklepu, gdy wybrana.

confirmation_policyobject | nullzawsze

Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.

finality_modeconfirmations | finalizedzawsze

Czy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.

project_required_confirmationsintegerzawsze

Bieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.

override_required_confirmationsinteger | nullzawsze

Liczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.

effective_required_confirmationsintegerzawsze

Liczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.

editablebooleanzawsze

False dla sieci finalized, których polityki ostateczności nie można nadpisać.

minimum_required_confirmationsintegerzawsze

Dolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.

maximum_required_confirmationsintegerzawsze

Górna granica właściwa dla blockchaina, włącznie.

walletobject | nullzawsze

Portfel blockchaina współdzielony przez aktywa natywne i tokeny.

idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

wallet_readinessreadiness enumzawsze

Tylko 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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Content-Typewymaganeapplication/json
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do danych dostępu; może być wstrzymany.

store_idUUIDwymagane

Sklep należący do project_id; może być wstrzymany.

asset_idUUIDwymagane

Obecnie wybrane aktywo płatnicze sklepu do aktualizacji.

Żą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
}'

Treść żądania

strategyinherit | customwymagane

Oznaczona strategia. inherit usuwa nadpisanie sklepu; custom wymaga required_confirmations.

required_confirmationsintegertylko custom

Liczba całkowita w granicach minimum/maksimum zwróconych dla tego aktywa. Nieznane lub dodatkowe pola są odrzucane.

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.

idUUIDzawsze

Trwały identyfikator aktywa płatniczego używany przez trasy polityk projektu i sklepu.

asset_keystringzawsze

Kanoniczna tożsamość aktywa natywnego lub kontraktowego w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

networkstringzawsze

Identyfikator blockchaina Wholly Crypto i skonfigurowana sieć.

caip_network_idstringzawsze

Kanoniczne tożsamości sieci i aktywa.

caip_asset_idstring|nullzawsze

Kanoniczne tożsamości sieci i aktywa.

asset_kindnative | tokenzawsze

Czy rozliczenie używa waluty blockchaina, czy zweryfikowanego kontraktu/mint.

payment_railstringzawsze

Kanał wykonawczy: utxo, evm-native, solana-native, account-native, privacy-native lub token-transfer.

symbolstringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

namestringzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

decimalsintegerzawsze

Tożsamość do wyświetlania i dokładna precyzja jednostek atomowych.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla aktywów natywnych.

coingecko_idstring | nullzawsze

Toż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_tokenbooleanzawsze

Niestandardowy kontrakt zweryfikowany on-chain z ceną w zakresie projektu: stałą w USD lub z wybranej puli DEX.

icon_pathpath | nullzawsze

Lokalnie buforowana ikona tokena, jeśli dostępna.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany standard tokena w środowisku uruchomieniowym; null dla aktywów natywnych.

metadata_verified_attimestamp | nullzawsze

Czas weryfikacji metadanych on-chain dla dodanych do rejestru tokenów.

payment_supportedbooleanzawsze
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.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_readybooleanzawsze
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.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_readybooleanzawsze
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.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 | finalizedzawsze

Domyślny model ostateczności dziedziczony przez nową politykę projektu.

default_required_confirmationsintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

default_monitoring_minutesintegerzawsze

Domyślna polityka potwierdzeń i monitorowania.

project_policyobject | nullzawsze

Nadrzędna polityka projektu.

enabledbooleanwymagane

Włącza lub wyłącza aktywo w projekcie. Natywny blockchain musi być włączony przed jakimkolwiek tokenem.

finality_modeconfirmations | finalizedwymagane

Polityka ostateczności obsługiwana przez kanał aktywa. finalized wymaga required_confirmations=1.

required_confirmationsintegerwymagane
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.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.

monitoring_minutesintegerwymagane

Okno odpytywania 1–10 080 minut, gdy faktura jest aktywna.

late_monitoring_daysintegerwymagane

0–3650 dni monitorowania po wygaśnięciu faktury.

selectedbooleanzawsze
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.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.

display_orderinteger | nullzawsze

Kolejność na stronie płatności sklepu, gdy wybrana.

confirmation_policyobject | nullzawsze

Efektywna polityka sklepu dla aktywa skonfigurowanego w projekcie. Null, jeśli brak polityki projektu.

finality_modeconfirmations | finalizedzawsze

Czy rozliczenie używa konfigurowalnej liczby bloków, czy ostateczności sieci.

project_required_confirmationsintegerzawsze

Bieżąca wartość domyślna projektu używana przez przyszłe faktury, gdy nie ustawiono nadpisania sklepu.

override_required_confirmationsinteger | nullzawsze

Liczba właściwa dla sklepu lub null, aby dziedziczyć wartość domyślną projektu.

effective_required_confirmationsintegerzawsze

Liczba, którą nowe faktury tego sklepu i aktywa zapiszą w swoim stanie.

editablebooleanzawsze

False dla sieci finalized, których polityki ostateczności nie można nadpisać.

minimum_required_confirmationsintegerzawsze

Dolna granica właściwa dla blockchaina, włącznie; 0 jest udostępniane tylko w kanałach obsługujących akceptację przy wykryciu.

maximum_required_confirmationsintegerzawsze

Górna granica właściwa dla blockchaina, włącznie.

walletobject | nullzawsze

Portfel blockchaina współdzielony przez aktywa natywne i tokeny.

idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

wallet_readinessreadiness enumzawsze

Tylko 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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia 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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do 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/projects/YOUR_PROJECT_ID/wallets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

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[]
idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

project_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

native_asset_idUUIDzawsze

Identyfikatory portfela, projektu właścicielskiego i natywnego aktywa blockchaina.

chain_slugstringzawsze

Blockchain i sieć portfela.

networkstringzawsze

Blockchain i sieć portfela.

asset_symbolstringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

asset_namestringzawsze

Tożsamość natywnego aktywa blockchaina do wyświetlania.

statuspending | active | disabled | errorzawsze

Stan operacyjny portfela.

labelstringzawsze

Etykieta operatora.

public_keystring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

primary_addressstring | nullzawsze

Publiczna tożsamość portfela; żadna fraza odzyskiwania ani klucz prywatny nie są ujawniane.

derivation_schemestring | nullzawsze

Polityka i format adresów.

address_formatstring | nullzawsze

Polityka i format adresów.

backup_confirmed_attimestamp | nullzawsze

Wartość inna niż null po potwierdzeniu przez operatora kopii zapasowej odzyskiwania.

activation_requiredbooleanzawsze
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.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|nullzawsze
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.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.

readybooleanzawsze

Kontrole 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_attimestampzawsze

Czas 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 znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_idUUIDgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

asset_tickerstringgdy znane

Identyfikuje blockchain i aktywo, których dotyczy problem. Lightning może pominąć asset_id.

reason_codestringzawsze
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.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ępne
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.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ępne
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.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-chain
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.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-chain
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.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-chain

Sprawne pasujące punkty końcowe, nie liczba niezależnych dostawców.

usable_independent_providersintegeron-chain
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ń.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-chain
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ń.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-chain

Ostatnia kontrola stanu pasującego punktu końcowego, oddzielna od czasu oceny.

monero_wallet_rpcMoneroWalletRpcBinding | nullzawsze
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.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.

last_secret_revealed_attimestamp|nullzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

secret_reveal_countintegerzawsze

Metadane audytu ujawniania sekretów po stronie panelu.

next_receive_indexintegerzawsze

Następny zarezerwowany indeks adresu potomnego.

last_scanned_heightinteger|nullzawsze

Stan skanera portfela.

last_scanned_attimestamp|nullzawsze

Stan skanera portfela.

last_errorstring|nullzawsze

Stan skanera portfela.

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.

wallet_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

asset_idUUIDzawsze

Tożsamości portfela i trwale zapisanych aktywów.

project_enabledbooleanzawsze

Czy to aktywo jest obecnie włączone przez politykę aktywów projektu.

active_store_countintegerzawsze

Liczba 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[]zawsze

Włączone sklepy w projekcie, które obecnie akceptują aktywo. Umożliwia dokładne lokalne filtrowanie sklepów bez kolejnego żądania API.

tracking_activebooleanzawsze
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.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.

asset_kindnative | tokenzawsze

Waluta natywna lub aktywo zweryfikowanego kontraktu/mint.

contract_addressstring | nullzawsze

Kontrakt lub mint tokena; null dla waluty natywnej.

symbolstringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

namestringzawsze

Tożsamość do wyświetlania i precyzja atomowa.

decimalsintegerzawsze

Tożsamość do wyświetlania i precyzja atomowa.

coingecko_idstring | nullzawsze

Tożsamość wyceny, jeśli zmapowana.

balancedecimal string|nullzawsze

Dokł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|nullzawsze

Dokł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 | nullzawsze

Orientacyjna buforowana cena jednostkowa USD używana do wyceny wartości.

value_usddecimal string | nullzawsze

Orientacyjna wartość fiducjarna, gdy istnieje aktualny kurs.

statuspending | refreshing | fresh | stale | errorzawsze
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.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.

checked_attimestamp | nullzawsze

Czas reprezentowany przez ukończone skanowanie salda.

last_errorstring | nullzawsze

Bezpieczna diagnostyka dla operatora.

total_value_usddecimal string | nullzawsze

Orientacyjna suma sald z aktualną ceną w USD.

balance_statuspending | refreshing | fresh | stale | error | unknownzawsze

Zbiorcza 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 | nullzawsze

Najstarsza 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.

invoice_public_idUUIDzawsze

Tożsamość faktury widoczna dla klienta, powiązana z obserwacją.

chain_slugstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

symbolstringzawsze

Blockchain i wyświetlany symbol aktywa natywnego lub zweryfikowanego tokena.

transaction_idstringzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

event_indexintegerzawsze

Kanoniczna tożsamość transakcji i zdarzenia przelewu.

amountdecimal stringzawsze

Dokładna zaobserwowana kwota aktywa bez konwersji zmiennoprzecinkowej.

statusdetected | confirming | finalzawsze

Bieżący prawidłowy stan obserwacji. Obserwacje po reorganizacji, zastąpione i nieprawidłowe są wykluczone.

confirmationsintegerzawsze

Ostatnia zaobserwowana liczba potwierdzeń.

observed_atRFC 3339 timestampzawsze

Czas pierwszego zaobserwowania płatności przez Wholly Crypto.

created_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

updated_atRFC 3339 timestampzawsze

Czas utworzenia i ostatniej aktualizacji portfela.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Idempotency-KeywymaganeUnikalne 1–128 widocznych znaków ASCII bez białych znaków.
Content-Typezalecaneapplication/json. Obecny handler surowej treści parsuje JSON bez wymuszania typu mediów.
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Skopiuj identyfikator API projektu z Projekt → Ustawienia → Identyfikatory API. Musi być przypisany do danych dostępu; czytelny identyfikator projektu nie jest akceptowany.

store_idUUIDwymagane

Skopiuj 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"
}'

Treść żądania

amountstringwymagane
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.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 | nullopcjonalne
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ń.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_slugstringwymagane
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.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[] | nullopcjonalne
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.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[] | nullopcjonalne
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.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 | lightningopcjonalne
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.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 | nullopcjonalne

Identyfikator zamówienia sprzedawcy, 1–128 znaków po przycięciu; znaki sterujące są odrzucane.

emailstring | nullopcjonalne

E-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 | nullopcjonalne

Opis widoczny dla klienta, 1–500 znaków; dozwolone są podziały wierszy i tabulatory.

expires_in_secondsinteger | nullopcjonalne

Czas ważności wyceny faktury od 300 do 86 400 sekund; pominięcie lub null dziedziczy politykę sklepu.

exchange_rate_spread_percentdecimal string | nullopcjonalne
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.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 | nullopcjonalne

Akceptowana 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 | nullopcjonalne

Publiczne 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 | nullopcjonalne

Adres 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 | nullopcjonalne

Adres 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 | nullopcjonalne

Pominięcie lub null dziedziczy politykę sklepu. true wymaga obowiązującego redirect_url.

languagestring | nullopcjonalne
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.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_storebooleanopcjonalne
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.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.

titlestringopcjonalne

Nagłówek strony płatności, do 120 znaków. Pusty używa standardowego nagłówka.

introstringopcjonalne
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.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.

outrostringopcjonalne
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.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_sizeintegeropcjonalne

Piksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.

outro_font_sizeintegeropcjonalne

Piksele: 12, 14, 16, 18, 20 lub 24. Domyślnie 16, chyba że odziedziczono inną wartość.

themesystem | light | dim | darkopcjonalne

Dopasuj do urządzenia klienta lub użyj stałego motywu.

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.

logo_sizestringopcjonalne

small, medium lub large; left lub center.

logo_alignmentstringopcjonalne

small, medium lub large; left lub center.

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
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
logo_darkobject | nullopcjonalne
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
faviconobject | nullopcjonalne
store_idUUIDwymagane
kindlogo_light | logo_dark | faviconopcjonalne
show_order_idbooleanopcjonalne

Pokaż 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_descriptionbooleanopcjonalne

Pokaż 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_expandedbooleanopcjonalne

Pokaż 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_namebooleanopcjonalne
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.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_namebooleanopcjonalne
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.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[]opcjonalne
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.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[]opcjonalne
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.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|nullopcjonalne
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.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
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
deobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
esobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
pt-BRobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
itobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
ruobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
zh-CNobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
frobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
koobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
jaobjectopcjonalne
waitingstringopcjonalne
confirmingstringopcjonalne
paidstringopcjonalne
underpaidstringopcjonalne
expiredstringopcjonalne
support_emailstringopcjonalne

E-mail ASCII, do 254 znaków. Pusty czyści.

support_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

terms_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

privacy_urlstringopcjonalne

Adresy HTTPS do 2048 znaków, bez danych dostępu. Puste czyszczą. Linki otwierają się w nowym oknie.

return_button_textstringopcjonalne

Etykieta do 60 znaków. Do zachowania faktury używaj najwyższego poziomu redirect_url/cancel_url/redirect_automatically/language.

show_return_buttonbooleanopcjonalne
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.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.

firstnamestringopcjonalne
lastnamestringopcjonalne
streetstringopcjonalne
street2stringopcjonalne
zipstringopcjonalne
citystringopcjonalne
countrystringopcjonalne
countryiso2stringopcjonalne
companystringopcjonalne
vatidstringopcjonalne
cart_idstring

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
idUUIDzawsze

Wewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.

invoice_idUUIDzawsze

Publiczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.

project_idUUIDzawsze

Projekt właścicielski.

store_idUUIDzawsze

Sklep właścicielski.

sourcemanual | apizawsze

Sposób utworzenia faktury.

order_idstring | nullzawsze

Identyfikator zamówienia sprzedawcy.

emailstring | nullzawsze

E-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.

customer_namestring | nullzawsze

Nazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.

customer_addressstring | nullzawsze

Jednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.

descriptionstring | nullzawsze

Opis widoczny dla klienta.

amountdecimal stringzawsze

Kanoniczna kwota faktury.

currencystringzawsze

Znormalizowany kod waluty/aktywa faktury.

exchange_rate_spread_percentdecimal stringzawsze

Zablokowany 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 stringzawsze

Niezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.

statusinvoice statuszawsze

new, processing, settled, expired, invalid lub cancelled.

amount_statusamount statuszawsze

none, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.

timing_statustiming statuszawsze

on_time lub late.

resolutionresolutionzawsze

automatic, manually_settled lub manually_invalidated.

sequenceintegerzawsze

Monotoniczna sekwencja stanu faktury, zaczynająca się od 1.

winning_payment_intent_idUUID | nullzawsze

Metoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.

expires_atRFC 3339 timestampzawsze

Termin wyceny/płatności.

monitoring_expires_atRFC 3339 timestampzawsze

Najpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.

settled_attimestamp | nullzawsze

Czas rozliczenia, jeśli rozliczona.

cancelled_attimestamp | nullzawsze

Czas anulowania, jeśli anulowana.

archived_attimestamp | nullzawsze

Czas archiwizacji, jeśli zarchiwizowana.

created_atRFC 3339 timestampzawsze

Czas utworzenia.

updated_atRFC 3339 timestampzawsze

Czas ostatniej aktualizacji stanu.

ipn_urlstring | nullzawsze

Obowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.

redirect_urlstring | nullzawsze

Obowiązujący URL sukcesu używany po rozliczeniu.

cancel_urlstring | nullzawsze

Obowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.

redirect_automaticallybooleanzawsze

Czy strona płatności powinna automatycznie przekierować po sukcesie.

checkout_languagestringzawsze

Obowiązujący znacznik języka strony płatności.

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.

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]zawsze

Wycenione metody płatności i stan monitorowania.

idUUIDzawsze

Identyfikator intencji płatności; używany też jako intent_id kodu QR płatności.

payment_railonchain | lightningzawsze
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.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_idUUIDzawsze

Identyfikator skonfigurowanego aktywa płatniczego.

asset_keystringzawsze

Kanoniczny klucz aktywa w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto.

networkstringzawsze

Skonfigurowana sieć, obecnie mainnet dla obsługiwanych aktywów płatniczych.

caip_network_idstringzawsze

Kanoniczny identyfikator sieci CAIP-2.

caip_asset_idstring | nullzawsze

Kanoniczny identyfikator CAIP-19, jeśli zarejestrowany.

symbolstringzawsze

Symbol aktywa.

asset_decimalsintegerzawsze

Precyzja 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.

statusintent statuszawsze

pending, partial, paid, overpaid, expired lub invalid.

finality_modeconfirmations | finalizedzawsze

Polityka ostateczności.

required_confirmationsintegerzawsze

Wymagana liczba potwierdzeń, jeśli dotyczy.

quote_ratedecimal stringzawsze

Jednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.

quote_detailsobject | nullzawsze
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.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 stringzawsze
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.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.

expected_amount_atomicinteger stringzawsze

Dokładna kwota w najmniejszej jednostce aktywa.

minimum_payment_amountdecimal stringzawsze

Najmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.

minimum_payment_amount_atomicinteger stringzawsze

Dokładny akceptowany próg w najmniejszej jednostce aktywa.

received_amountdecimal stringzawsze

Zaobserwowana kwota.

received_amount_atomicinteger stringzawsze

Zaobserwowana kwota atomowa.

confirmed_amountdecimal stringzawsze

Potwierdzona/ostateczna kwota.

confirmed_amount_atomicinteger stringzawsze

Potwierdzona/ostateczna kwota atomowa.

destination_addressstringzawsze

Adres 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 | nullzawsze

Wymagany 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_indexintegerzawsze

Zarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.

quote_expires_atRFC 3339 timestampzawsze

Termin ważności wyceny.

monitoring_expires_atRFC 3339 timestampzawsze

Koniec monitorowania spóźnionych płatności dla tej metody.

next_check_attimestamp | nullzawsze

Następne zaplanowane sprawdzenie blockchaina.

last_checked_attimestamp | nullzawsze

Ostatnie sprawdzenie blockchaina.

last_chain_heightinteger | nullzawsze

Ostatnia wiarygodna wysokość zaobserwowana przez monitor.

last_anchor_hashstring | nullzawsze

Ostatnia kotwica/hash bloku monitora.

last_monitor_errorstring | nullzawsze

Bezpieczna diagnostyka monitorowania dla operatorów.

first_payment_attimestamp | nullzawsze

Czas pierwszej zaobserwowanej płatności.

fully_paid_attimestamp | nullzawsze

Czas pierwszego osiągnięcia akceptowanej kwoty minimalnej.

finalized_attimestamp | nullzawsze

Czas spełnienia polityki ostateczności płatności.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do danych dostępu.

Parametry zapytania

store_idUUID

Opcjonalny dokładny filtr sklepu.

statusenum

Opcjonalnie new, processing, settled, expired, invalid lub cancelled.

limitinteger

Opcjonalnie 1–100; domyślnie 50.

offsetinteger

Opcjonalnie 0–1 000 000; domyślnie 0.

Żą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'

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[]
idUUIDzawsze

Wewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.

invoice_idUUIDzawsze

Publiczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.

project_idUUIDzawsze

Projekt właścicielski.

store_idUUIDzawsze

Sklep właścicielski.

sourcemanual | apizawsze

Sposób utworzenia faktury.

order_idstring | nullzawsze

Identyfikator zamówienia sprzedawcy.

emailstring | nullzawsze

E-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.

customer_namestring | nullzawsze

Nazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.

customer_addressstring | nullzawsze

Jednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.

descriptionstring | nullzawsze

Opis widoczny dla klienta.

amountdecimal stringzawsze

Kanoniczna kwota faktury.

currencystringzawsze

Znormalizowany kod waluty/aktywa faktury.

exchange_rate_spread_percentdecimal stringzawsze

Zablokowany 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 stringzawsze

Niezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.

statusinvoice statuszawsze

new, processing, settled, expired, invalid lub cancelled.

amount_statusamount statuszawsze

none, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.

timing_statustiming statuszawsze

on_time lub late.

resolutionresolutionzawsze

automatic, manually_settled lub manually_invalidated.

sequenceintegerzawsze

Monotoniczna sekwencja stanu faktury, zaczynająca się od 1.

winning_payment_intent_idUUID | nullzawsze

Metoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.

expires_atRFC 3339 timestampzawsze

Termin wyceny/płatności.

monitoring_expires_atRFC 3339 timestampzawsze

Najpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.

settled_attimestamp | nullzawsze

Czas rozliczenia, jeśli rozliczona.

cancelled_attimestamp | nullzawsze

Czas anulowania, jeśli anulowana.

archived_attimestamp | nullzawsze

Czas archiwizacji, jeśli zarchiwizowana.

created_atRFC 3339 timestampzawsze

Czas utworzenia.

updated_atRFC 3339 timestampzawsze

Czas ostatniej aktualizacji stanu.

paginationobject
limitintegerzawsze

Efektywny rozmiar strony, 1–100.

offsetintegerzawsze

Efektywne przesunięcie wierszy liczone od zera, 0–1 000 000.

totalintegerzawsze

Łączna liczba wierszy pasujących do filtrów projektu, sklepu, statusu i wyszukiwania w zapisanym stanie strony.

has_morebooleanzawsze

True, gdy offset plus liczba zwróconych wierszy jest mniejsza niż total.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Włączony projekt przypisany do danych dostępu.

invoice_idUUIDwymagane

invoice_id zwrócone podczas tworzenia/listowania, nie wewnętrzne id.

Żą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'

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
idUUIDzawsze

Wewnętrzny UUID faktury. Nie używaj go w ścieżkach szczegółów sprzedawcy ani strony płatności.

invoice_idUUIDzawsze

Publiczny UUID faktury używany w ścieżkach szczegółów sprzedawcy i strony płatności.

project_idUUIDzawsze

Projekt właścicielski.

store_idUUIDzawsze

Sklep właścicielski.

sourcemanual | apizawsze

Sposób utworzenia faktury.

order_idstring | nullzawsze

Identyfikator zamówienia sprzedawcy.

emailstring | nullzawsze

E-mail klienta tylko dla sprzedawcy. Nigdy nie jest zwracany przez publiczną stronę płatności.

customer_namestring | nullzawsze

Nazwa do wyświetlania wyprowadzona z prywatnych metadanych firstname, lastname i company.

customer_addressstring | nullzawsze

Jednowierszowy adres dla sprzedawcy wyprowadzony z prywatnych metadanych company, street, street2, zip, city, country, countryiso2 i vatid.

descriptionstring | nullzawsze

Opis widoczny dla klienta.

amountdecimal stringzawsze

Kanoniczna kwota faktury.

currencystringzawsze

Znormalizowany kod waluty/aktywa faktury.

exchange_rate_spread_percentdecimal stringzawsze

Zablokowany 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 stringzawsze

Niezmienny procent akceptowanej niedopłaty zapisany przy tworzeniu faktury.

statusinvoice statuszawsze

new, processing, settled, expired, invalid lub cancelled.

amount_statusamount statuszawsze

none, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.

timing_statustiming statuszawsze

on_time lub late.

resolutionresolutionzawsze

automatic, manually_settled lub manually_invalidated.

sequenceintegerzawsze

Monotoniczna sekwencja stanu faktury, zaczynająca się od 1.

winning_payment_intent_idUUID | nullzawsze

Metoda płatności, która rozstrzygnęła fakturę, gdy została wybrana.

expires_atRFC 3339 timestampzawsze

Termin wyceny/płatności.

monitoring_expires_atRFC 3339 timestampzawsze

Najpóźniejszy skonfigurowany termin monitorowania spóźnionych płatności spośród metod płatności.

settled_attimestamp | nullzawsze

Czas rozliczenia, jeśli rozliczona.

cancelled_attimestamp | nullzawsze

Czas anulowania, jeśli anulowana.

archived_attimestamp | nullzawsze

Czas archiwizacji, jeśli zarchiwizowana.

created_atRFC 3339 timestampzawsze

Czas utworzenia.

updated_atRFC 3339 timestampzawsze

Czas ostatniej aktualizacji stanu.

ipn_urlstring | nullzawsze

Obowiązujący cel IPN danej faktury. Tylko odpowiedź dla sprzedawcy; pomijany w publicznej stronie płatności.

redirect_urlstring | nullzawsze

Obowiązujący URL sukcesu używany po rozliczeniu.

cancel_urlstring | nullzawsze

Obowiązujący adres powrotny używany, gdy płatność kończy się bez sukcesu.

redirect_automaticallybooleanzawsze

Czy strona płatności powinna automatycznie przekierować po sukcesie.

checkout_languagestringzawsze

Obowiązujący znacznik języka strony płatności.

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.

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]zawsze

Wycenione metody płatności i stan monitorowania.

idUUIDzawsze

Identyfikator intencji płatności; używany też jako intent_id kodu QR płatności.

payment_railonchain | lightningzawsze
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.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_idUUIDzawsze

Identyfikator skonfigurowanego aktywa płatniczego.

asset_keystringzawsze

Kanoniczny klucz aktywa w stylu CAIP.

chain_slugstringzawsze

Identyfikator blockchaina Wholly Crypto.

networkstringzawsze

Skonfigurowana sieć, obecnie mainnet dla obsługiwanych aktywów płatniczych.

caip_network_idstringzawsze

Kanoniczny identyfikator sieci CAIP-2.

caip_asset_idstring | nullzawsze

Kanoniczny identyfikator CAIP-19, jeśli zarejestrowany.

symbolstringzawsze

Symbol aktywa.

asset_decimalsintegerzawsze

Precyzja 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.

statusintent statuszawsze

pending, partial, paid, overpaid, expired lub invalid.

finality_modeconfirmations | finalizedzawsze

Polityka ostateczności.

required_confirmationsintegerzawsze

Wymagana liczba potwierdzeń, jeśli dotyczy.

quote_ratedecimal stringzawsze

Jednostki aktywa na jedną jednostkę waluty faktury, z zablokowanym narzutem kursowym. Na przykład 1.02 USDC za USD. Nie kurs odwrotny.

quote_detailsobject | nullzawsze
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.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 stringzawsze
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.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.

expected_amount_atomicinteger stringzawsze

Dokładna kwota w najmniejszej jednostce aktywa.

minimum_payment_amountdecimal stringzawsze

Najmniejsza kwota akceptowana jako opłacona po zastosowaniu tolerancji faktury.

minimum_payment_amount_atomicinteger stringzawsze

Dokładny akceptowany próg w najmniejszej jednostce aktywa.

received_amountdecimal stringzawsze

Zaobserwowana kwota.

received_amount_atomicinteger stringzawsze

Zaobserwowana kwota atomowa.

confirmed_amountdecimal stringzawsze

Potwierdzona/ostateczna kwota.

confirmed_amount_atomicinteger stringzawsze

Potwierdzona/ostateczna kwota atomowa.

destination_addressstringzawsze

Adres 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 | nullzawsze

Wymagany 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_indexintegerzawsze

Zarezerwowany indeks potomny portfela; tylko szczegóły dla sprzedawcy.

quote_expires_atRFC 3339 timestampzawsze

Termin ważności wyceny.

monitoring_expires_atRFC 3339 timestampzawsze

Koniec monitorowania spóźnionych płatności dla tej metody.

next_check_attimestamp | nullzawsze

Następne zaplanowane sprawdzenie blockchaina.

last_checked_attimestamp | nullzawsze

Ostatnie sprawdzenie blockchaina.

last_chain_heightinteger | nullzawsze

Ostatnia wiarygodna wysokość zaobserwowana przez monitor.

last_anchor_hashstring | nullzawsze

Ostatnia kotwica/hash bloku monitora.

last_monitor_errorstring | nullzawsze

Bezpieczna diagnostyka monitorowania dla operatorów.

first_payment_attimestamp | nullzawsze

Czas pierwszej zaobserwowanej płatności.

fully_paid_attimestamp | nullzawsze

Czas pierwszego osiągnięcia akceptowanej kwoty minimalnej.

finalized_attimestamp | nullzawsze

Czas spełnienia polityki ostateczności płatności.

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

Kody błędów i zasady ponowień

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łówekObecnośćZasada
AuthorizationwymaganeBearer YOUR_MERCHANT_API_TOKEN
Acceptzalecaneapplication/json

Parametry ścieżki

project_idUUIDwymagane

Projekt przypisany do tych danych dostępu.

invoice_idUUIDwymagane

Publiczne invoice_id zwrócone przy tworzeniu.

Parametry zapytania

payment_method_idUUIDopcjonalne

Ogranicz do jednej metody płatności faktury.

limitinteger

1–100; domyślnie 25.

offsetinteger

0–1 000 000; domyślnie 0.

Żą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'

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_idstring
data[]object[]
payment_idstring
payment_method_idstring
transaction_idstring
payment_hashJSON | null
event_indexinteger
payment_railstring
chain_slugstring
networkstring
asset_idstring
asset_keystring
caip_asset_idstring
symbolstring
asset_decimalsinteger
amountstring
amount_atomicstring
statusstring
counts_towards_receivedboolean
confirmationsinteger
block_heightinteger
observed_atstring
chain_timestring
finalized_atstring
explorer_namestring
explorer_urlstring
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
Uwagi 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

Kody błędów i zasady ponowień

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'

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

Kody błędów i zasady ponowień

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

invoice_idUUIDwymagane

Publiczny UUID faktury zwrócony przez API sprzedawcy.

Żądanie

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID" \
  --output 'checkout.html'

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

Kody błędów i zasady ponowień

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

invoice_idUUIDwymagane

Publiczny UUID faktury.

Żą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'

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
invoice_idUUIDzawsze

Publiczny UUID faktury.

order_idstring | nullzawsze

Identyfikator zamówienia sprzedawcy.

descriptionstring | nullzawsze

Opis widoczny dla klienta.

amountdecimal stringzawsze

Kwota faktury.

currencystringzawsze

Waluta faktury.

exchange_rate_spread_percentdecimal stringzawsze

Obowiązujący narzut wyceny zablokowany przy tworzeniu, w tym nadpisanie dla danej faktury.

underpayment_tolerance_percentdecimal stringzawsze

Procent akceptowanej niedopłaty tej faktury.

statusinvoice statuszawsze

Bieżący status faktury.

amount_statusamount statuszawsze

none, partial, paid lub overpaid. Jawnie dozwolona faktura zerowa rozlicza się z none i bez metod płatności.

timing_statustiming statuszawsze

on_time lub late.

sequenceintegerzawsze

Bieżąca sekwencja stanu.

active_payment_method_idUUID | nullzawsze

Wymieniona 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_lockedbooleanzawsze

True po wybraniu active_payment_method_id przez prawidłową płatność.

server_timeRFC 3339 timestampzawsze

Czas serwera zapisany dla tej odpowiedzi; używaj go z expires_at, aby uniknąć rozbieżności zegara urządzenia klienta.

expires_atRFC 3339 timestampzawsze

Termin faktury.

expires_in_secondsintegerzawsze

Pełne sekundy pozostałe w server_time, zaokrąglone w górę i ograniczone od dołu do zera.

payment_openbooleanzawsze

True tylko wtedy, gdy faktura new lub processing jest przed terminem i ma co najmniej jedną dostępną do opłacenia metodę z pozostałą kwotą.

redirect_urlstring | nullzawsze

Cel powrotu klienta po udanym rozliczeniu.

cancel_urlstring | nullzawsze

Cel powrotu klienta przy wyjściu bez udanego rozliczenia.

redirect_automaticallybooleanzawsze

Polityka automatycznego przekierowania.

checkout_languagestringzawsze

Język strony płatności.

projectobjectzawsze

name, checkout_title, checkout_description, theme, accent_color i logo_url.

namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
storeobjectzawsze

Publiczna nazwa sklepu.

namestring
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_storebooleanzawsze

True, gdy wygląd pochodzi z domyślnego sklepu projektu. False dla niezależnych sklepów i zamrożonych nadpisań faktury.

invoice_overridebooleanzawsze

True, gdy checkout_appearance podano przy tworzeniu faktury. Pominięcie/null zachowuje false.

titlestringzawsze

Zwykł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.

introstringzawsze

Zwykł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.

outrostringzawsze

Zwykł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.

intro_font_sizeintegerzawsze

Rozmiary czcionek w pikselach: 12, 14, 16, 18, 20 lub 24.

outro_font_sizeintegerzawsze

Rozmiary czcionek w pikselach: 12, 14, 16, 18, 20 lub 24.

customer_messagestringzawsze

Wycofywany alias zgodności intro. W nowych integracjach używaj intro.

themesystem | light | dim | darkzawsze

Preferencja urządzenia klienta lub stały motyw.

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_sizestringzawsze

small, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.

logo_alignmentstringzawsze

small, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.

imagesobjectzawsze

Opcjonalne adresy logo_light, logo_dark i favicon: znormalizowane obrazy PNG z tego samego origin, ograniczone zakresem.

show_order_idbooleanzawsze

Widoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.

show_descriptionbooleanzawsze

Widoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.

details_expandedbooleanzawsze

Widoczność 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_namebooleanzawsze

Merchant 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_namebooleanzawsze

Merchant 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[]arrayzawsze

Uporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.

featured_asset_ids[]arrayzawsze

Uporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.

default_asset_idUUID | nullzawsze

Sugerowana 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.

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

support_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

terms_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

privacy_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

return_button_textstringzawsze

Tylko opcjonalna etykieta. Cele sukcesu/anulowania i polityka przekierowań nadal należą do faktury.

show_return_buttonbooleanzawsze

Widoczność 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 | lightningzawsze

Lightning pozostaje metodą Bitcoin, oddzielną od BTC on-chain. Identyfikuj wybór przez identyfikator intencji i kanał, nie samo asset_id.

bolt11string | nullzawsze

Podpisane żądanie Lightning; null dla metod on-chain. Nigdy nie płać po zmianie payable na false.

payment_hashstring | nullzawsze

Hash płatności Lightning do uzgadniania, nie adres odbiorczy. Null dla metod on-chain.

idUUIDzawsze

Identyfikator intencji płatności.

asset_idUUIDzawsze

UUID aktywa używany przez preferencje wyglądu; odrębny od identyfikatora intencji płatności tej faktury.

asset_keystringzawsze

Kanoniczny klucz aktywa.

chain_slugstringzawsze

Maszynowa i wyświetlana nazwa blockchaina.

chain_namestringzawsze

Maszynowa i wyświetlana nazwa blockchaina.

networkstringzawsze

Sieć płatnicza.

caip_network_idstringzawsze

Kanoniczna tożsamość sieci używana do jednoznacznego określenia wybranego blockchaina.

caip_asset_idstring | nullzawsze

Kanoniczna dokładna tożsamość aktywa, obejmująca zweryfikowany kontrakt lub mint tokena, jeśli dotyczy.

asset_namestringzawsze

Wartości aktywa płatniczego do wyświetlania.

symbolstringzawsze

Wartości aktywa płatniczego do wyświetlania.

asset_icon_urlstring | nullzawsze

Lokalnie buforowana ikona aktywa z tego samego origin lub null, gdy brak zweryfikowanego mapowania CoinGecko.

asset_kindnative | tokenzawsze

Rozróżnia walutę natywną i płatność kontraktem/mint.

contract_addressstring | nullzawsze

Kanoniczny kontrakt ERC-20 lub mint SPL dla tokenów; null dla waluty natywnej.

token_standarderc20 | spl-token | nullzawsze

Zweryfikowany typ wykonawczy tokena lub null dla waluty natywnej.

asset_decimalsintegerzawsze

Precyzja jednostek atomowych: 11 dla millisatoshi Lightning BTC, 8 dla satoshi BTC on-chain.

statusintent statuszawsze

Bieżący status metody płatności.

payablebooleanzawsze

True tylko wtedy, gdy dokładnie ta metoda może obecnie przyjąć płatność; false dla nieaktywnych metod po otrzymaniu środków przez inne aktywo.

finality_modestringzawsze

Polityka ostateczności.

required_confirmationsintegerzawsze

Polityka ostateczności.

expected_amountdecimalzawsze
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.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 stringzawsze
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.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_amountdecimalzawsze

Akceptowany próg rozliczenia po zastosowaniu tolerancji niedopłaty.

minimum_payment_amount_atomicinteger stringzawsze

Akceptowany próg rozliczenia po zastosowaniu tolerancji niedopłaty.

received_amountdecimalzawsze

Zaobserwowana kwota.

received_amount_atomicinteger stringzawsze

Zaobserwowana kwota.

remaining_amountdecimal stringzawsze

Dokładna wyświetlana kwota nadal potrzebna do osiągnięcia akceptowanego progu, ograniczona od dołu do zera.

remaining_amount_atomicinteger stringzawsze

Brakująca kwota do akceptowanego progu w jednostkach atomowych. To nie żądana kwota płatności: tolerancja wpływa tylko na akceptację.

confirmed_amountdecimalzawsze

Potwierdzona/ostateczna kwota.

confirmed_amount_atomicinteger stringzawsze

Potwierdzona/ostateczna kwota.

destination_addressstringzawsze

Adres 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|nullzawsze

Adres docelowy on-chain i opcjonalny identyfikator. Dla Lightning jest to hash płatności bez tagu; zamiast tego opłać bolt11/payment_uri.

quote_expires_atRFC 3339 timestampzawsze

Termin ważności wyceny.

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|nullzawsze

Zweryfikowany zapasowy eksplorator sieci głównej, tam gdzie obsługiwany.

address_explorer_urlstring|nullzawsze

Zweryfikowany zapasowy eksplorator sieci głównej, tam gdzie obsługiwany.

transaction_countintegerzawsze

Łączna liczba odrębnych publicznych prawidłowych transakcji zaobserwowanych dla tej metody.

transactions_truncatedbooleanzawsze

True, 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.

transaction_idstringzawsze

Identyfikator zaobserwowanej transakcji.

statusdetected | confirming | finalzawsze

Publiczny stan obserwacji.

confirmationsintegerzawsze

Zaobserwowana liczba potwierdzeń.

block_heightinteger | nullzawsze

Zaobserwowana wysokość bloku/księgi.

explorer_namestringgdy zwracane

Zweryfikowana stała nazwa eksploratora.

explorer_urlstringgdy zwracane

Zweryfikowany stały URL eksploratora sieci głównej.

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

Kody błędów i zasady ponowień

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

project_idUUIDwymagane

UUID projektu skopiowany do linku podglądu przez uwierzytelniony panel.

Parametry zapytania

store_idUUID,opcjonalne

Sklep należący do tego projektu. Pomiń, aby użyć pierwszego/domyślnego sklepu.

statestring,opcjonalne

waiting, confirming, paid, underpaid lub expired. Ilustracja wyłącznie w przeglądarce.

Żą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'

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

Kody błędów i zasady ponowień

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

project_idUUIDwymagane

UUID projektu z linku podglądu panelu.

Parametry zapytania

store_idUUID,opcjonalne

Musi 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'

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
previewboolean
invoice_idstring
amountstring
currencystring
projectobject
namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
appearanceobject
inherit_default_storebooleanzawsze

True, gdy wygląd pochodzi z domyślnego sklepu projektu. False dla niezależnych sklepów i zamrożonych nadpisań faktury.

invoice_overridebooleanzawsze

True, gdy checkout_appearance podano przy tworzeniu faktury. Pominięcie/null zachowuje false.

titlestringzawsze

Zwykł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.

introstringzawsze

Zwykł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.

outrostringzawsze

Zwykł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.

intro_font_sizeintegerzawsze

Rozmiary czcionek w pikselach: 12, 14, 16, 18, 20 lub 24.

outro_font_sizeintegerzawsze

Rozmiary czcionek w pikselach: 12, 14, 16, 18, 20 lub 24.

customer_messagestringzawsze

Wycofywany alias zgodności intro. W nowych integracjach używaj intro.

themesystem | light | dim | darkzawsze

Preferencja urządzenia klienta lub stały motyw.

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_sizestringzawsze

small, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.

logo_alignmentstringzawsze

small, medium lub large; left lub center. Obrazy mieszczą się w obszarze, nie są przycinane.

imagesobjectzawsze

Opcjonalne adresy logo_light, logo_dark i favicon: znormalizowane obrazy PNG z tego samego origin, ograniczone zakresem.

show_order_idbooleanzawsze

Widoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.

show_descriptionbooleanzawsze

Widoczność identyfikatora zamówienia, opis pod tytułem i początkowe rozwinięcie identyfikatora. Kwota pozostaje widoczna; to ustawienia wyświetlania, nie usuwanie danych.

details_expandedbooleanzawsze

Widoczność 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_namebooleanzawsze

Merchant 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_namebooleanzawsze

Merchant 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[]arrayzawsze

Uporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.

featured_asset_ids[]arrayzawsze

Uporządkowane preferencje, stosowane tylko do metod już obecnych na fakturze. Brakujące lub wyłączone metody są pomijane.

default_asset_idUUID | nullzawsze

Sugerowana 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.

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

support_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

terms_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

privacy_urlstringzawsze

Opcjonalne dane kontaktowe i linki HTTPS, bez danych dostępu w URL. Zewnętrzne linki otwierają się w nowym oknie.

return_button_textstringzawsze

Tylko opcjonalna etykieta. Cele sukcesu/anulowania i polityka przekierowań nadal należą do faktury.

show_return_buttonbooleanzawsze

Widoczność 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[]array
payment_methods[]array
Uwagi 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

Kody błędów i zasady ponowień

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

invoice_idUUIDwymagane

Publiczny UUID faktury.

kindenumwymagane

logo_light, logo_dark lub favicon.

revisionUUIDwymagane

Bieżąca rewizja obrazu.

Żą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'

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

Kody błędów i zasady ponowień

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

project_idUUIDwymagane

UUID projektu.

store_idUUIDwymagane

Sklep należący do projektu.

kindenumwymagane

logo_light, logo_dark lub favicon.

revisionUUIDwymagane

Bieżąca rewizja obrazu.

Żą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'

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

Kody błędów i zasady ponowień

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

invoice_idUUIDwymagane

Publiczny UUID faktury.

intent_idUUIDwymagane

Identyfikator metody płatności z JSON strony płatności.

Żą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'

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

Kody błędów i zasady ponowień

Dokumentacja Wholly Crypto 8.3.2. Dla zainstalowanej wersji otwórz Ustawienia → Dostęp API → Dokumentacja w panelu. Zobacz wydania.