Utilizzo dell'API di Whalestack

Sblocca pagamenti in criptovaluta veloci, sicuri e senza sforzo con l'API Whalestack. Una volta che hai sicurato la tua chiave API dopo la registrazione, crea un checkout o genera un indirizzo di deposito blockchain. Che si tratti di Bitcoin, Lightning, Litecoin, Stellar o un'altra rete supportata, ricevere pagamenti è semplice. Inoltre, approfitta della possibilità di trasformare valuta fiat dentro e fuori utilizzando SWIFT o SEPA.

Portafogli e Depositi

Con Whalestack, ricevi istantaneamente indirizzi dedicati per depositi in Bitcoin, Lightning, Litecoin, Stellar, SWIFT, SEPA e altri ancora. Inizia a ricevere pagamenti blockchain pochi istanti dopo l'iscrizione. Utilizza gli endpoint GET /wallets e POST /deposit-address per recuperare i tuoi indirizzi blockchain e avviare depositi personalizzati.

Checkouts

I checkout di Whalestack semplificano i pagamenti dei clienti. Offriamo un'esperienza utente superiore con checkout ospitati completamente personalizzabili. Se le pagine di pagamento predefinite non sono di tuo gradimento, sfrutta le nostre API di checkout di backend per avere il controllo completo. Leggi la nostra introduzione alla creazione di checkouts o tuffati direttamente negli endpoint POST /checkout o POST /checkout/hosted per ulteriori dettagli.

Swap e Trasferimenti

Una volta ricevuti i fondi, sia attraverso i checkouts che mediante depositi personalizzati, puoi utilizzarli immediatamente. Scambiali tra diversi asset o trasferiscili a un conto bancario o blockchain (anche se consigliamo di indirizzarli verso un archivio cold storage per una sicurezza massima). Utilizza gli endpoint POST /swap e POST /transfer per esplorare scambi e trasferimenti.

Rendicontazione Finanziaria Trasparente

Niente più confusione su intricati percorsi di pagamento sulla blockchain. Whalestack aggrega tutte le tue transazioni nella sezione "Rapporti Finanziari" del tuo account. Puoi persino collegare le transazioni a controparti specifiche come clienti (POST /customer) o beneficiari (POST /beneficiary). Ti forniamo report CSV, grafici visuali e analisi approfondite, semplificando i tuoi processi di contabilità.

Software Development Kit

L'API Whalestack si integra senza soluzione di continuità con client REST in tutti i linguaggi di programmazione. Per iniziare rapidamente, abbiamo selezionato SDK per PHP, Ruby e NodeJS. Esplora queste risorse sulla nostra pagina GitHub.

PHP
SDK ufficiale di Whalestack per PHP

Ruby
SDK ufficiale di Whalestack per Ruby

NodeJS
SDK ufficiale di Whalestack per NodeJS

Integrazioni per il Commercio Elettronico

Siamo impegnati a perfezionare regolarmente il nostro set di strumenti per l'e-commerce, garantendo integrazioni senza soluzione di continuità con Whalestack. La nostra suite di librerie, plugin ed estensioni è progettata per la tua integrazione rapida e senza problemi. Scopri l'ampia gamma di integrazioni per l'e-commerce pronte per essere implementate qui sotto.

Magento
Estensione ufficiale di Whalestack per Magento

PrestaShop
Estensione ufficiale di Whalestack per PrestaShop

Shopify
Integrazione ufficiale di Whalestack per Shopify

WooCommerce
Plugin ufficiale di Whalestack per WooCommerce

WordPress
Plugin ufficiale di Whalestack per WordPress

Adobe Commerce
Estensione ufficiale di Whalestack per Adobe Commerce

Creazione dei Checkout

Inizia scegliendo tra la nostra esperienza di pagina di checkout completamente personalizzabile e l'opzione self-hosted, in cui sfrutti le nostre API di backend per mantenere il controllo completo sul percorso di pagamento.

Opzione 1: Checkout con Hosting Autonomo

Fornisci il processo di checkout con il tuo brand all'interno della tua applicazione web. Scegli i checkout con backend API in hosting autonomo per garantire un'esperienza senza interruzioni per gli utenti, mantenendoli all'interno dell'ecosistema della tua applicazione. Inizia i pagamenti in modalità white label tramite l'API endpoint POST /checkout.

Opzione 2: Pagine di Checkout

I nostri checkout completamente personalizzabili offrono il modo più diretto per ricevere pagamenti su Whalestack, mantenendo al contempo il tuo brand. L'API endpoint POST /checkout/hosted crea un link di pagamento. Se stai dirigendo gli utenti a whalestack.com o al tuo dominio tramite Brand Connect, il processo rimane senza soluzione di continuità. Dopo aver ottenuto l'URL del checkout, guida il tuo cliente alla pagina ospitata e saranno pronti per effettuare il pagamento. Ti notifichiamo tramite webhooks, email o interrogazione API riguardo ai fondi in entrata.

Di seguito trovi una guida passo-passo per creare un checkout ospitato dinamico:

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/checkout/hosted \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: TIMESTAMP" \
     -d "@charge.json"

L'autenticazione è fornita tramite gli header HTTP, e charge.json è un oggetto JSON:

Esempio di Addebito (essenziale)

{
   "charge":{
      "billingCurrency":"EUR",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

L'esempio sopra crea un addebito per un articolo al prezzo di 169.99 EUR. Puoi configurare ulteriori dettagli, come i costi di spedizione, gli sconti, le tasse, il cliente correlato, così come l'asset di regolamento preferito, come documentato qui.

Esempio di Risposta (application/json)

{
   "id":"b5bcf27e5482",
   "url":"https://www.whalestack.com/en/checkout?id=b5bcf27e5482"
}

L'API restituisce un identificatore univoco insieme a un URL di checkout ospitato, che mostri al tuo cliente affinché possa completare il pagamento. Una volta che i fondi sono stati acquisiti, ti notifichiamo attraverso WEBHOOK checkout-completed.

Ricezione Pagamenti

Le transazioni di criptovaluta differiscono dai pagamenti con carta di credito tradizionali. Invece di consentire ai commercianti di prelevare fondi utilizzando i dettagli della carta di credito, le criptovalute operano su un modello di spinta (push), dove è il cliente a inviare attivamente i fondi. Ciò richiede che il cliente in modo attivo inizi e invii il pagamento al commerciante.

Al momento dell'inizio di un checkout, Whalestack monitora attentamente la blockchain scelta per i pagamenti in arrivo. C'è una finestra temporale di 60 minuti per il completamento della transazione. Se il pagamento non viene finalizzato entro questo periodo, viene contrassegnato come scaduto. Tuttavia, sono ancora accettati i pagamenti ritardati che alla fine vengono elaborati.

Dopo aver ricevuto con successo il pagamento, il tuo saldo viene aggiornato, la tua dashboard riflette le modifiche e viene avviata una chiamata di webhook al tuo server. Ciò garantisce l'elaborazione automatica dell'ordine nel tuo sistema tramite il meccanismo WEBHOOK checkout-completed.

Esempio di Webhook (application/json)

{
   "eventType":"CHECKOUT_COMPLETED",
   "data":{
      "checkout":{
         "id":"a2d963a87d70",
         "timestamp":"2023-05-29T17:36:30+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"117.8379738",
         "settlementAmountReceived":"117.8379738",
         "settlementAmountFeePaid":"0.0000000",
         "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "sourceAmountRequired":"0.0043193",
         "sourceAmountReceived":"0.0043193",
         "sourceNetwork":"BITCOIN",
         "sourceNetworkName":"Bitcoin",
         "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
         "blockchainTransactions":[
            {
               "type":"CHECKOUT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2023-05-29T17:55:52+00:00",
               "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_BRIDGE",
               "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"9e912d924d6a27ee858e011db14825f016f835249302f90b82237a9b9782bde0",
               "amount":"117.8379738",
               "amountAssetCode":"USDC",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "customerId":"bb657e88a23d",
               "currency":"EUR",
               "lineItems":[
                  {
                     "description":"Mobile Data Prepaid Credits",
                     "netAmount":"110.00000"
                  }
               ],
               "shippingCostItems":[
                  {
                     "description":"Instant Delivery",
                     "netAmount":0
                  }
               ],
               "taxItems":[
                  {
                     "name":"Hong Kong Sales Tax",
                     "percent":0
                  }
               ]
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "webhook":"https://www.my-server.com/api/?action=cq-webhook",
            "links":{
               "cancelUrl":"https://www.my-server.com/en/payments",
               "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
            }
         },
         "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
      }
   }
}

Il webhook contiene un oggetto JSON nel corpo della richiesta HTTP e ti informa sui pagamenti in arrivo e sui loro attributi come specificato in WEBHOOK checkout-completed. Nell'esempio sopra, il cliente ha pagato in BTC (Bitcoin) e il commerciante è stato accreditato in USDC (USD Coin).

Collegamento del Brand tramite Whalestack

Brand Connect di Whalestack infonde la tua esperienza di pagamento Whalestack con la tua identità esclusiva di Brand. Sia che si tratti del tuo logo distintivo, di immagini tematiche o di un'interfaccia utente personalizzata secondo l'estetica del tuo marchio, Brand Connect assicura che le tue pagine di pagamento si percepiscano come un'estensione organica della tua piattaforma. Scegli se ospitare su whalestack.com o eseguire il deploy sul tuo dominio con la nostra semplice configurazione di contenitori Docker.

Brand Connect è la soluzione ideale per i fornitori di servizi di pagamento che mirano a sfruttare il completo sistema di checkout di Whalestack, mantenendo al contempo la propria distintiva presentazione del marchio. Questo include la gestione competente di sfumature nelle transazioni come sovrapagamenti, sottopagamenti, rimborsi o transazioni multiple. Tuttavia, anche se non sei un fornitore di servizi ma desideri semplicemente un'esperienza visiva coerente per il tuo negozio online, Brand Connect è la tua scelta ideale.

Personalizzazione del Branding

L'allestimento dell'aspetto personalizzato del tuo checkout è semplice grazie all'interfaccia Brand Connect nelle impostazioni del tuo account. Ecco come personalizzare il tuo brand:

Attiva Brand Connect nelle tue impostazioni dell'account
Procedi a modificare le Informazioni sul Brand, le Immagini, i Caratteri e i Colori all'interno delle impostazioni.

Una volta configurate, le tue pagine di pagamento si integreranno perfettamente con il tuo marchio - logo, favicon, immagini cripto personalizzate, preferenze dei caratteri e schemi di colori. Ispezionando il tuo checkout, noterai un'integrazione senza problemi senza segni di Whalestack come fornitore di servizi sottostante.

Configurazione del Dominio Web Personalizzato

Per impostazione predefinita, Brand Connect funziona sul dominio whalestack.com. Tuttavia, se aspiri a una maggiore immersione nel brand, puoi indirizzare i tuoi pagamenti attraverso il tuo dominio web personale. Questa opzione è ideale per coloro che forniscono servizi di pagamento e desiderano incorporare senza problemi le capacità di Whalestack mantenendo allo stesso tempo la propria aura distintiva del marchio.

Questa integrazione è realizzata tramite il contenitore Docker di Brand Connect (GitHub). Posizionandolo nella tua configurazione di hosting e apportando alcune modifiche al DNS, abiliti un flusso di pagamento perfettamente in sintonia con l'identità del tuo brand. Ecco una guida passo dopo passo:

Attiva Brand Connect nelle tue impostazioni dell'account
Perfeziona le informazioni sul tuo marchio, le immagini, i caratteri e i colori nelle impostazioni.
Designa il tuo dominio web personalizzato per i pagamenti e ottieni la tua WS_BRANDING_KEY (dopo aver completato i passaggi sopra indicati).
Implementa il Brand Connect contenitore Docker insieme al tuo certificato SSL.
Reindirizza il DNS del tuo dominio web all'indirizzo IP che ospita il contenitore Docker.

E voilà! Le tue pagine di pagamento Whalestack sono ora una parte integrante del tuo dominio, riflettendo l'essenza unica del tuo marchio. Approfondisci ulteriormente su GitHub.

Garantita l'Autenticazione Sicura

L'API di Whalestack richiede principalmente l'autenticazione. In modo distintivo, gli endpoint dell'API sono classificati come pubblici () o protetti (). Per accedere a un endpoint protetto, autentica la tua richiesta utilizzando la tua chiave API tramite il metodo Basic-Auth o il metodo più sicuro Digest-Auth. Per verificare senza sforzo il tuo metodo di autenticazione, utilizza l'endpoint GET /auth-test.

Protezione delle Credenziali API

Vai alle Impostazioni API per recuperare la tua chiave API segreta. Qui puoi anche impostare la tua strategia di autenticazione preferita e aumentare la sicurezza abilitando "IP-address whitelisting" (lista bianca degli indirizzi IP). In caso di sospetto sulla sicurezza segreta API, hai la possibilità di rigenerarlo da queste impostazioni.

Digest-Auth: La Nostra Scelta Consigliata

Noi sosteniamo l'utilizzo del metodo Digest-Auth quando si accede agli endpoint protetti dell'API Whalestack. Le intestazioni essenziali per ogni richiesta includono X-Digest-Key, X-Digest-Signature e X-Digest-Timestamp, tutti dettagliati nelle sezioni successive.

Richiesta

curl 'https://www.whalestack.com/api/v1/auth-test' \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Intestazioni Richiesta

Chiave	Categoria	Descrizione
`X-Digest-Key`	string	Your Whalestack API key.	mandatory
`X-Digest-Signature`	string	Unique Digest-Auth Signature (see below).	mandatory
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`).	mandatory

La X-Digest-Signature viene generata creando un SHA256 HMAC utilizzando il tuo API come segreto condiviso nel messaggio digest. Il payload criptato è composto come segue:
ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY , dove . rappresenta la concatenazione di stringhe.

Componenti di X-Digest-Signature

Componente	Categoria	Descrizione
`ENDPOINT_PATH`	string	The path of the endpoint that is being invoked, e.g. `/auth-test` in lower case.
`UNIX_TIMESTAMP`	integer	Current Unix timestamp. Must be less than 30 seconds old (also see `GET /time`).
`REQUEST_METHOD`	string	The request method, e.g. `POST` or `GET` in upper case.
`REQUEST_BODY`	string	The request body string. Only needed in `POST`, `PUT`, or `DELETE` requests. Set `null` for `GET` requests.

Esempio di Codice (PHP)

$path = '/auth-test'
$timestamp = time();
$method = 'GET';
$body = $method == 'GET' ? null : json_encode($params);
$secret = 'YOUR_API_SECRET';

$signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

Esempio di Codice (Ruby)

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Esempio di Codice (NodeJS)

require('crypto');

let path = '/auth-test'
let timestamp = Date.now() / 1000 | 0;
let method = 'GET'
let body = method === 'GET' ? '' : JSON.stringify(params)
let secret = 'YOUR_API_SECRET'

let signature = crypto.createHmac('sha256', secret)
                .update(path + timestamp + method + body)
                .digest('hex');

Visualizza questi esempi se non sei sicuro di come creare una firma HMAC SHA256 nel tuo linguaggio di programmazione.

Basic-Auth

Puoi scegliere di utilizzare un'intestazione di autenticazione di base, che è più facile da implementare (poiché è un hash statico sulla tua chiave API), ma meno sicura rispetto a Digest-Auth. Consigliamo di utilizzare Basic-Auth solo durante lo sviluppo o in ambienti di test.

Richiesta

curl 'https://www.whalestack.com/api/v1/auth-test' \
     -H "X-Basic: BASIC_AUTH_HASH"

Intestazioni Richiesta

Chiave	Categoria	Descrizione
`X-Basic`	string	SHA256 hash over `YOUR_API_KEY:YOUR_API_SECRET`	mandatory

Esempio di Codice

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Inserimento in Lista Bianca degli Indirizzi IP

Utilizza le Impostazioni API per configurare se il tuo account API può essere accessibile da qualsiasi indirizzo IP o solo da indirizzi IP in lista bianca. L'inserimento in lista bianca degli indirizzi IP è consigliato per gli ambienti di produzione, poiché aumenta notevolmente la sicurezza. Gli endpoint di prelievo possono essere accessibili solo dagli indirizzi IP presenti nella lista bianca.

Software Development Kit (SDK)

I nostri Kit di Sviluppo Software per PHP, Ruby e NodeJS sono qui per aiutarti a integrarti rapidamente con l'API di Pagamenti di Whalestack senza problemi.

Ecco una lista degli SDK attualmente disponibili sul nostro GitHub.

PHP
SDK ufficiale di Whalestack per PHP

1  include('WhalestackClient.class.php');
2
3  $client = new WhalestackClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/whalestack.log'
7  );

Visualizza su GitHub

Ruby
SDK ufficiale di Whalestack per Ruby

1  require 'whalestack_sdk/client'
2
3  client = WhalestackSDK::Client.new(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/whalestack.log'
7  )

Visualizza su GitHub

NodeJS
SDK ufficiale di Whalestack per NodeJS

1  require('whalestack-sdk');
2
3  const client = new WhalestackClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET'
6  );

Visualizza su GitHub

GET/networksprotetto

Fornisce un elenco delle reti blockchain e bancarie supportate dalla piattaforma Whalestack.

Richiesta

curl 'https://www.whalestack.com/api/v1/networks'

Risposta di Successo application/json

{
   "networks":[
      {
         "id":"BITCOIN",
         "name":"Bitcoin",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-btc-88.png",
         "deposits":true,
         "transfers":true,
         "bridged":true,
         "assets":[
            "BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT"
         ]
      },
      {
         "id":"SWIFT",
         "name":"SWIFT",
         "type":"BANK",
         "imageSrc":"/images/icon-swift-88.png",
         "deposits":false,
         "transfers":true,
         "bridged":true,
         "assets":[
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2"
         ]
      },
      {
         "id":"SEPA",
         "name":"SEPA",
         "type":"BANK",
         "imageSrc":"/images/icon-sepa-88.png",
         "deposits":false,
         "transfers":true,
         "bridged":true,
         "assets":[
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2"
         ]
      },
      {
         "id":"STELLAR",
         "name":"Stellar",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-xlm-88.png",
         "deposits":true,
         "transfers":true,
         "bridged":false,
         "assets":[
            "XLM:NATIVE",
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "ARS:GCYE7C77EB5AWAA25R5XMWNI2EDOKTTFTTPZKM2SR5DI4B4WFD52DARS",
            "BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP",
            "BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
            "BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
            "LTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
            "EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2"
         ]
      },
      {
         "id":"ETHEREUM",
         "name":"Ethereum",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-eth-88.png",
         "deposits":false,
         "transfers":true,
         "bridged":true,
         "assets":[
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2"
         ]
      },
      {
         "id":"LITECOIN",
         "name":"Litecoin",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-ltc-88.png",
         "deposits":true,
         "transfers":true,
         "bridged":true,
         "assets":[
            "LTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT"
         ]
      },
      {
         "id":"LIGHTNING",
         "name":"Lightning",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-sat-88.png",
         "deposits":true,
         "transfers":true,
         "bridged":true,
         "assets":[
            "BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT"
         ]
      },
      {
         "id":"PIX",
         "name":"Brazilian PIX",
         "type":"BANK",
         "imageSrc":"/images/icon-brl-88.png",
         "deposits":false,
         "transfers":true,
         "bridged":true,
         "assets":[
            "BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP"
         ]
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.networks[]`	array	A list objects representing a blockchain or bank network.	false
`.id`	string	The network identifier.	false
`.name`	string	The network name.	false
`.type`	string	The network type. Can be either `BLOCKCHAIN` or `BANK`.	false
`.imageSrc`	string	The URL of the Whalestack icon depicting the network. A path relative to www.whalestack.com.	false
`.deposits`	boolean	Indicates whether this network can be used as to originate payments towards checkouts and deposits.	false
`.transfers`	boolean	Indicates whether this network can receive transfers.	false
`.bridged`	boolean	Indicates whether this network is native to the Whalestack platform or bridged via Stellar (SEP-6 or OTC).	false
`.assets`	array	A list of asset identifiers as given by `GET /assets` indicating the assets available for redemption and reception via the network.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/assetsprotetto

Fornisce un elenco di asset supportati dalla piattaforma Whalestack.

Richiesta

curl 'https://www.whalestack.com/api/v1/assets'

Risposta di Successo application/json

{
   "assets":[
      {
         "id":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "assetCode":"BTC",
         "assetIssuer":"GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "name":"Bitcoin",
         "group":"BTC",
         "groupImageSrc":"/images/icon-btc-88.png",
         "issuerName":"Whalestack LLC",
         "issuerDomain":"whalestack.com",
         "issuerAddress":"54 Jedności Street, 65-018 Zielona Góra, Poland",
         "imageSrc":"/images/icon-btc-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#f7931a",
         "riskLevel":"LOW",
         "bridge":true,
         "networks":[
            "STELLAR",
            "BITCOIN"
         ]
      },
      {
         "id":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "assetCode":"USDC",
         "assetIssuer":"GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "name":"USD Coin",
         "group":"USD",
         "groupImageSrc":"/images/icon-usd-88.png",
         "issuerName":"Centre",
         "issuerDomain":"centre.io",
         "issuerAddress":"Centre Consortium LLC, United States",
         "imageSrc":"/images/icon-usdc-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#2775ca",
         "riskLevel":"LOW",
         "bridge":true,
         "networks":[
            "STELLAR",
            "SWIFT",
            "SEPA"
         ]
      },
      {
         "id":"XLM:NATIVE",
         "assetCode":"XLM",
         "assetIssuer":"NATIVE",
         "name":"Stellar Lumens",
         "group":"XLM",
         "groupImageSrc":"/images/icon-xlm-88.png",
         "issuerName":"SDF",
         "issuerDomain":"stellar.org",
         "issuerAddress":"Stellar Development Foundation, San Francisco, CA, United States",
         "imageSrc":"/images/icon-xlm-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#5894ca",
         "riskLevel":"LOW",
         "bridge":false,
         "networks":[
            "STELLAR"
         ]
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.assets[]`	array	A list objects representing a Stellar asset.	false
`.id`	string	The identifier of the asset.	false
`.assetCode`	string	The asset code.	false
`.assetIssuer`	string	The identifier of the asset issuer on the Stellar Network.	false
`.name`	string	The asset name.	false
`.group`	string	The group to which the asset belongs. For example, USDC and USDT belong to the USD group. BTC and BTCLN (Lightning) belong to the BTC group.	false
`.groupImageSrc`	string	The URL of the Whalestack icon depicting the asset group. A path relative to www.whalestack.com.	false
`.issuerName`	string	The asset issuer name in English plain text.	false
`.issuerDomain`	string	The asset issuer's web domain.	false
`.issuerAddress`	string	The asset issuer's physical address.	false
`.imageSrc`	string	The URL of the Whalestack icon depicting the asset. A path relative to www.whalestack.com.	false
`.checkouts`	boolean	Indicates whether this asset can be used as payment method in checkouts.	false
`.deposits`	boolean	Indicates whether this asset can be used as payment method in deposits.	false
`.settlement`	boolean	Indicates whether this asset can be used for checkout settlement.	false
`.swaps`	boolean	Indicates whether this asset can be used as source or target asset in swaps.	false
`.transfers`	boolean	Indicates whether this asset can be used as target assets in transfers.	false
`.hexColor`	string(7)	Whalestack's color code for this asset. Useful for charts and other visualizations.	false
`.riskLevel`	string	Indicating the assets risk level as `LOW`, `MEDIUM`, or `HIGH`. Your risk tolerance can be configured in the (browser-based) settlement settings in your account. Assets with a `LOW` risk level are native to the Stellar Network and can be widely redeemed (e.g. XLM and USDC). Assets with a `MEDIUM` risk level assets are bridged onto the Stellar network by trusted custodians (anchors) and can be redeemed via SEP-6 or OTC via Whalestack (e.g. BTC, LTC, ETH, Bitcoin Lightning BTC). Assets with a `HIGH` risk level are only available to you if manually enabled in your account settings (e.g. USDT).	false
`.bridge`	boolean	Indicates whether this asset is bridged via Stellar (SEP-6 or OTC).	false
`.networks`	array	A list of network identifiers as given by `GET /networks` indicating the networks on which payment transactions for this asset can be processed.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/currenciesprotetto

Fornisce una lista delle valute supportate dalla piattaforma Whalestack.

Richiesta

curl 'https://www.whalestack.com/api/v1/currencies'

Risposta di Successo application/json

{
    "currencies": [
        {
            "assetCode": "BTC",
            "name": "Bitcoin",
            "type": "CRYPTO",
            "billing": true,
            "settlement": true,
            "payment": true
        },
        {
            "assetCode": "USD",
            "name": "US Dollar",
            "type": "FIAT",
            "billing": true,
            "settlement": true,
            "payment": false
        },
        {
            "assetCode": "XLM",
            "name": "Stellar Lumens",
            "type": "CRYPTO",
            "billing": true,
            "settlement": true,
            "payment": true
        }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.currencies[]`	array	A list objects representing a currency.	false
`.assetCode`	string	The asset code of the currency.	false
`.name`	string	The name of the currency.	false
`.type`	string	The currency type. Either `CRYPTO` or `FIAT`.	false
`.billing`	boolean	Indicates whether this currency can be specified as billing currency in checkout objects.	false
`.settlement`	boolean	Indicates whether this currency can be specified as settlement currency in checkout objects and deposits.	false
`.payment`	boolean	Indicates whether this currency can used as payment currency in checkout objects and deposits.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST /checkout protetto

Avvia il tuo processo di pagamento auto-ospitato inizializzando un checkout. Questo endpoint ti consente di creare un checkout direttamente sul tuo server, offrendoti piena autonomia sulla sua interfaccia utente o API. Per un'alternativa che automatizza una pagina di checkout sull'infrastruttura di Whalestack, considera il POST /checkout/hosted. Se sei nuovo nell'inizializzare un processo di checkout, ti consigliamo di iniziare qui.

Per interagire con questo endpoint, dovrai fornire un oggetto di addebito, che comprende voci di linea, possibili aggiunte come spese di spedizione o sconti e le tasse applicabili. Per un tocco più personalizzato e la generazione di una fattura, collega l'addebito a un cliente specifico. Hai anche la leva per stabilire la valuta di liquidazione, che potrebbe differire dalla denominazione dell'addebito o dalla valuta scelta dal tuo cliente. Un'interazione riuscita con questo endpoint ti fornisce un array di metodi di pagamento e i rispettivi importi, tutti pronti per essere presentati alla tua clientela.

I tuoi clienti possono quindi selezionare il loro metodo di pagamento preferito (ad esempio, Bitcoin). Dopo la loro scelta, invia una nuova richiesta arricchita con la blockchain scelta e il relativo ID del checkout a POST /checkout/commit, che restituisce istruzioni per il deposito da mostrare al tuo cliente. Non appena l'impegno del checkout è stabilito, il sistema di Whalestack esegue una scansione diligente della blockchain per i pagamenti in arrivo, tenendoti aggiornato sui progressi dei pagamenti tramite il WEBHOOK checkout-completed.

Nota che i checkout dichiarano un'intenzione di pagamento e sono progettati per un uso singolo. Inizia sempre un nuovo checkout per ogni transazione.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/checkout \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload (Minimo)

{
   "charge":{
      "billingCurrency":"EUR",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Spiegazione della Configurazione del Payload Sopra

Quanto sopra rappresenta la configurazione minima necessaria per avviare un checkout. La tariffa è denominata in EUR e ha esattamente una voce di dettaglio con un costo di 169,99 EUR. L'importo del pagamento addebitato al tuo cliente nella sua criptovaluta di scelta viene calcolato in base all'importo totale di fatturazione specificato qui.

Esempio di Payload (Completo)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "billingCurrency":"USD",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":199,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "pageSettings":{
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout",
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   },
   "anchors":{
      "BITCOIN":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "LITECOIN":"LTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT"
   }
}

Parametri della Richiesta (POST)

Collegamento dei Clienti

Fornisci un charge.customerId come fornito da POST /customer per collegare automaticamente il checkout a un cliente. Collegare i pagamenti ai clienti aiuta nella contabilità, fornisce maggiori dettagli nella cronologia delle transazioni e consente l'invio automatico di fatture e notifiche sullo stato dei pagamenti.

Formula dell'Importo Totale

Il calcolo dell'importo totale viene eseguito utilizzando la seguente formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Use the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.billingCurrency`	string	A currency code as given by `GET /currencies`. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	numeric	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementAsset`	string	An asset id as given by `GET /assets`. Specifies the asset you will be credited in when the checkout completes. Set to `ORIGIN` to get credited in the asset your customer pays in without any type of currency conversion.	ORIGIN	optional
`.checkoutLanguage`	string	A language code as given by `GET /languages`. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `it` `tr` `pl` `fr`	auto	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.anchors{}`	object	An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by `GET /networks` and the value being an anchored asset id as given by `GET /assets`.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any).	null	optional
`.returnUrl`	string	Specifies the url to which to redirect the customer when the payment completes successfully. Do not rely on this url to capture completed payments. Always confirm payment status with a call to `GET /checkout` or implement webhooks for reliable payment notifications in your application. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.cancelUrl`	string	Specifies the url to which to redirect the customer when he cancels the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced.	true	optional

Risposta di Successo application/json

{
   "id":"3296a3f29bcd",
   "paymentMethods":[
      {
         "assetCode":"SAT",
         "blockchain":"Lightning",
         "network":"LIGHTNING",
         "relatedAssetId":"BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
         "paymentAmount":"735612",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"XLM:NATIVE",
         "paymentAmount":"1908.8467626",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"USD",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "paymentAmount":"199.0000000",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"EUR",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2",
         "paymentAmount":"197.3775345",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.id`	string(12)	The identifier of the checkout. You should store this persistently to match payments and associated information against this checkout.	false
`.paymentMethods[]`	array	Contains a list of available payment methods for this checkout and associated payment amounts for your customer. The given payment methods and amounts should be displayed back to your customer to let him select his desired form of payment. Upon selection, your application submits a `POST /checkout/commit` with the selected payment method and obtains the deposit information for your customer to make payment.	false
`.assetCode`	string	The corresponding payment asset code, e.g. `BTC`. Inspect `GET /currencies` for a list of possible values.	false
`.blockchain`	string	The blockchain name in plain text.	false
`.network`	string	The payment network identifier as given by `GET /networks`. Use this identifier to select the desired payment network in the next step at `POST /checkout/commit`.	false
`.relatedAssetId`	string	An asset id as given by `GET /assets`. If the related `network` supports more than one asset, then use this identifier to select the desired payment asset in the next step at `POST /checkout/commit`.	false
`.paymentAmount`	string	The required payment amount to display back to your customer.	false
`.settlement{}`	object	An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes. The quote is valid for 60 minutes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The gross amount credited to your account when the payment completes.	false
`.netAmount`	string	The net amount credited to your account when the payment completes. This amount is constituted by the `amount` minus `fee`.	false
`.fee`	string	The settlement fee collected by Whalestack.	false

Next Step

Your application displays the payment methods received in the response back to your customer. The customer then selects his preferred payment method and your server submits the selected network identifier in a new API request to the POST /checkout/commit endpoint. In return you receive the deposit address for the selected blockchain for display to your customer. Continue here.

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/commitprotetto

Questo endpoint rappresenta una continuazione fondamentale del processo di checkout, che è stato avviato tramite POST /checkout. Se sei nuovo nell'inizializzare un processo di checkout, ti consigliamo di iniziare qui.

Quando fai una richiesta a questo endpoint, dovrai fornire un checkoutId e una network, ottenuti dalla richiesta POST /checkout. Se la rete selezionata supporta più asset, dovrai anche includere un asset (se omesso, verrà utilizzato l'asset predefinito della rete). In caso di una richiesta riuscita, riceverai informazioni sul deposito, le quali dovrebbero essere presentate al tuo cliente per agevolare il processo di pagamento.

Una volta che questo endpoint viene invocato, Whalestack avvia il monitoraggio in tempo reale della rete blockchain pertinente. Quando il pagamento viene completato, il tuo server viene automaticamente notificato tramite il WEBHOOK checkout-completed. In alternativa, puoi verificare periodicamente lo stato del pagamento utilizzando GET /checkout dopo aver mostrato le informazioni sul deposito al tuo cliente.

Nel passaggio precedente, POST /checkout ti ha fornito un elenco dei metodi di pagamento disponibili, come illustrato di seguito:

Esempio di Risposta (come fornito da `POST /checkout`)

{
   "id":"3296a3f29bcd",
   "paymentMethods":[
      {
         "assetCode":"SAT",
         "blockchain":"Lightning",
         "network":"LIGHTNING",
         "relatedAssetId":"BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
         "paymentAmount":"735612",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"XLM:NATIVE",
         "paymentAmount":"1908.8467626",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"USD",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "paymentAmount":"199.0000000",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      },
      {
         "assetCode":"EUR",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2",
         "paymentAmount":"197.3775345",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"199",
            "netAmount":"198.005",
            "fee":"0.995"
         }
      }
   ]
}

Come prerequisito per invocare questo endpoint, dovresti aver ricevuto una risposta come sopra dal punto finale POST /checkout. Contiene un elenco di metodi di pagamento, che mostri al tuo cliente per la scelta. Dopo la selezione, invochi POST /checkout/commit (questo endpoint) con la depositNetwork selezionata, relatedAssetId (se necessario) e checkoutId per ricevere le informazioni sul deposito da presentare al tuo cliente per effettuare il pagamento.

Richiesta

curl -X POST 'https://www.whalestack.com/api/v1/checkout/commit'
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload (Bitcoin)

{
  "checkoutId":"6d55626309d6",
  "network":"BITCOIN"
}

Esempio di Payload (EURC, Stellar)

{
  "checkoutId":"6d55626309d6",
  "network":"STELLAR",
  "asset":"EURC:GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2"
}

Esempio di Payload (XLM, Stellar)

{
  "checkoutId":"6d55626309d6",
  "network":"STELLAR",
  "asset":"XLM:NATIVE"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`checkoutId`	string(12)	Unique identifier as given by `POST /checkout`.	null	mandatory
`network`	string	The payment network selected by your customer. As given by `POST /checkout`.	null	mandatory
`asset`	string	The payment asset selected by your customer. As given by `POST /checkout`. If omitted, then the network default asset is used.	null	optional

Esempio di Risposta di Successo (Bitcoin) application/json

{
    "depositInstructions": {
        "assetCode":"BTC",
        "blockchain": "Bitcoin",
        "network": "BITCOIN",
        "amount": "0.0001807",
        "address": "3NBFeR5BBSt9JfL2bodpG89LSqNZrcZdseV",
        "memo": null,
        "memoType": null
    },
    "settlement": {
        "assetId": "BTC:GBSY6HJZLWBUUNJHHDLDE3AIBSQCHI6UMIMWOLZ6GUWI3NPPLP6QNGI2",
        "amount": "0.0001807",
        "netAmount": "0.0001798",
        "fee": "0.0000009"
    },
    "expirationTime": "2023-05-29T20:33:49+00:00",
    "checkoutId": "793f2c605f26"
}

Esempio di Risposta di Successo (XLM) application/json

{
   "depositInstructions":{
      "assetCode":"XLM",
      "blockchain":"Stellar Network",
      "network":"STELLAR",
      "amount":"17.8639906",
      "address":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"4c52bcad95114c52bcad9512",
      "memoType":"text"
   },
   "settlement": {
       "assetId": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
       "amount": "2.3354345"
   },
   "expirationTime":"2020-02-26T18:48:58+00:00",
   "checkoutId":"d95114c52bca"
}

Fornisci al tuo cliente l'address insieme a memo e memoType quando viene selezionata la rete STELLAR per il pagamento. Questo è importante affinché Whalestack possa associare il pagamento al tuo account da commerciante.

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositInstructions{}`	object	The deposit information to display to your customer.	false
`.blockchain`	string	The selected blockchain name as plain text.	false
`.assetCode`	string	The selected payment asset code, e.g. `BTC`, `SAT`, `XLM`, or `LTC`.	false
`.network`	string	The selected payment network as given by `GET /networks`.	false
`.amount`	string	The required payment amount for the selected blockchain. Display this back to your customer. Please note that this field is of type `string` even though it is numeric. You might need to do some type casting here.	false
`.memo`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.memoType`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.settlement{}`	object	An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The amount credited to your account when the payment completes.	false
`.expirationTime`	timestamp	W3C formatted timestamp with the expiration time for this checkout. Whalestack allows for a 60 minutes window to complete the payment, afterwards we mark the charge as expired. Don't worry though, you will still be credited even if the payment arrives late.	false
`.checkoutId`	array	The checkout id as originally given by `POST /checkout`.	false

Passaggi Successivi

Visualizza le informazioni sul deposito al tuo cliente. Nel frattempo, Whalestack inizia a monitorare l'indirizzo blockchain fornito nella risposta dell'API e ti notifica automaticamente tramite WEBHOOK checkout-completed quando un pagamento viene completato. In alternativa, puoi effettuare periodiche richieste di tipo GET /checkout per aggiornamenti sui pagamenti.

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST /checkout/hosted protetto

Questo endpoint genera e fornisce un URL unico che punta a una pagina di checkout, completamente gestita sui server di Whalestack. Per un approccio più pratico, dove hai il controllo sull'interfaccia utente e sul flusso di checkout, considera invece l'endpoint POST /checkout. Se sei nuovo nell'inizializzare un processo di checkout, ti consigliamo di iniziare qui.

Invocando questo endpoint, il tuo server fornisce parametri che includono dettagli di pagamento, voci di imposta opzionali, dati del cliente e la valuta di regolamento desiderata. In cambio, il tuo server ottiene un URL di checkout, pronto per essere presentato alla tua clientela.

Accedendo a questo URL, i clienti si trovano di fronte a una pagina di checkout user-friendly ospitata sull'infrastruttura di Whalestack. Questa pagina interattiva presenta tutte le informazioni essenziali per agevolare il processo di pagamento. Una volta conclusa la transazione, il nostro sistema informa istantaneamente la tua applicazione tramite WEBHOOK checkout-completed. Per coloro interessati alla proattività, l'endpoint GET /checkout consente di monitorare continuamente lo stato del pagamento.

Progettati per l'adattabilità, i checkout ospitati di Whalestack si adattano senza problemi sia ai display mobili che a quei desktop più ampi. Perfeziona il loro aspetto in modo che risuoni con l'estetica del tuo marchio utilizzando Brand Connect.

Ricorda che ogni URL di checkout ospitato è unico e ad uso singolo. Assicurati di generare un nuovo URL per ogni nuova transazione.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/checkout/hosted \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload (Minimo)

{
   "charge":{
      "billingCurrency":"EUR",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Spiegazione della Configurazione del Payload Sopra

Quanto sopra rappresenta la configurazione minima necessaria per avviare un checkout. La tariffa è denominata in EUR e ha esattamente una voce di dettaglio con un costo di 169,99 EUR. L'importo del pagamento addebitato al tuo cliente nella sua criptovaluta di scelta viene calcolato in base all'importo totale di fatturazione specificato qui.

Esempio di Payload (Completo)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "billingCurrency":"USD",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":199,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "pageSettings":{
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout",
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   },
   "anchors":{
      "BITCOIN":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "LITECOIN":"LTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT"
   }
}

Parametri della Richiesta (POST)

Collegamento dei Clienti

Fornisci un charge.customerId come fornito da POST /customer per collegare automaticamente il checkout a un cliente. Collegare i pagamenti ai clienti aiuta nella contabilità, fornisce maggiori dettagli nella cronologia delle transazioni e consente l'invio automatico di fatture e notifiche sullo stato dei pagamenti.

Formula dell'Importo Totale

Il calcolo dell'importo totale viene eseguito utilizzando la seguente formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Use the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.billingCurrency`	string	A currency code as given by `GET /currencies`. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	numeric	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementAsset`	string	An asset id as given by `GET /assets`. Specifies the asset you will be credited in when the checkout completes. Set to `ORIGIN` to get credited in the asset your customer pays in without any type of currency conversion.	ORIGIN	optional
`.checkoutLanguage`	string	A language code as given by `GET /languages`. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `it` `tr` `pl` `fr`	auto	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.anchors{}`	object	An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by `GET /networks` and the value being an anchored asset id as given by `GET /assets`.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any).	null	optional
`.returnUrl`	string	Specifies the url to which to redirect the customer when the payment completes successfully. Do not rely on this url to capture completed payments. Always confirm payment status with a call to `GET /checkout` or implement webhooks for reliable payment notifications in your application. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.cancelUrl`	string	Specifies the url to which to redirect the customer when he cancels the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced.	true	optional

Risposta di Successo application/json

{
   "id":"b5bcf27e5482",
   "url":"https://www.whalestack.com/en/checkout?id=b5bcf27e5482",
   "oracle":[
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "network":"BITCOIN",
         "relatedAssetId":"BTC:GBSY6HJZLWBUUNJHHDLDE3AIBSQCHI6UMIMWOLZ6GUWI3NPPLP6QNGI2",
         "paymentAmount":"0.0001807",
         "settlement":{
            "assetId":"BTC:GBSY6HJZLWBUUNJHHDLDE3AIBSQCHI6UMIMWOLZ6GUWI3NPPLP6QNGI2",
            "amount":"0.0001807",
            "netAmount":"0.0001798",
            "fee":"0.0000009"
         }
      },
      {
         "assetCode":"SAT",
         "blockchain":"Lightning",
         "network":"LIGHTNING",
         "relatedAssetId":"BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
         "paymentAmount":"18074",
         "settlement":{
            "assetId":"BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
            "amount":"18073.3779143",
            "netAmount":"17983.0110247",
            "fee":"90.3668896"
         }
      },
      {
         "assetCode":"LTC",
         "blockchain":"Litecoin",
         "network":"LITECOIN",
         "relatedAssetId":"LTC:GBSY6HJZLWBUUNJHHDLDE3AIBSQCHI6UMIMWOLZ6GUWI3NPPLP6QNGI2",
         "paymentAmount":"0.0548930",
         "settlement":{
            "assetId":"LTC:GBSY6HJZLWBUUNJHHDLDE3AIBSQCHI6UMIMWOLZ6GUWI3NPPLP6QNGI2",
            "amount":"0.054893",
            "netAmount":"0.0546185",
            "fee":"0.0002745"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar",
         "network":"STELLAR",
         "relatedAssetId":"XLM:NATIVE",
         "paymentAmount":"56.0444605",
         "settlement":{
            "assetId":"XLM:NATIVE",
            "amount":"56.0444605",
            "netAmount":"55.7642382",
            "fee":"0.2802223"
         }
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.id`	string(12)	The identifier of the hosted checkout. You should store this persistently to match payments against this checkout.	false
`.url`	string(12)	The hosted checkout URL, which you display back to your customer to initiate payment. Upon visiting this URL your client is presented with a checkout interface where he completes the payment. When completed, your application is automatically notified via `WEBHOOK checkout-completed`. Alternatively you can poll `GET /checkout` using the `id` given in the above response to query information about the payment state. Returns branded URL if Brand Connect is enabled.	false
`.oracle[]`	array	Contains a list of available payment methods for this checkout alongside indicative payment amounts and corresponding indicative settlement amounts. The given amounts are an estimation and and based on the current liquidity and market making situation on Whalestack's decentralized exchange provider. The payment amounts can deviate by the time the buyer initiates payment on the checkout page. We recommend to apply your own sanity checks on the amounts given in this object and only display the checkout URL to the end user if you are satisfied with the quoted settlement and payment amount estimations.	false
`.assetCode`	string	The asset code of the payment currency, e.g. `BTC`.	false
`.blockchain`	string	The payment blockchain name in plain text.	false
`.network`	string	The payment network identifier as given by `GET /networks`.	false
`.relatedAssetId`	string	An asset id as given by `GET /assets`. This asset identifies the Stellar SEP-6 anchor used for capturing the payment, if applicable.	false
`.paymentAmount`	string	The required payment amount currently needed to fill your settlement amount. This amount can deviate on the customer facing payment page.	false
`.settlement{}`	object	An object containing information on the settlement asset and amount to be credited to your account when the payment completes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The gross amount credited to your account when the payment completes. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal.	false
`.netAmount`	string	The net amount credited to your account when the payment completes. This amount is constituted by the `amount` minus `fee`. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal.	false
`.fee`	string	The settlement fee collected by Whalestack.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutprotetto

Recupera informazioni su un determinato checkout.

La risposta di questo endpoint contiene informazioni sui pagamenti blockchain associati a questo checkout, il suo stato di completamento complessivo, nonché informazioni di contesto aggiuntive.

Questo endpoint è adatto per richiedere eventi di pagamento associati al checkout specificato. Un'alternativa più efficiente è ascoltare gli eventi di pagamento utilizzando WEBHOOK checkout-completed sul tuo server.

Richiesta

curl 'https://www.whalestack.com/api/v1/checkout?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `POST /checkout` or `POST /checkout/hosted`.	null	mandatory

Risposta di Successo application/json

{
   "checkout":{
      "id":"a2d963a87d70",
      "timestamp":"2023-05-29T17:36:30+00:00",
      "state":"COMPLETED",
      "type":"HOSTED",
      "origin":"API",
      "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "settlementAmountRequired":"117.8379738",
      "settlementAmountReceived":"117.8379738",
      "settlementAmountFeePaid":"0.0000000",
      "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "sourceAmountRequired":"0.0043193",
      "sourceAmountReceived":"0.0043193",
      "sourceNetwork":"BITCOIN",
      "sourceNetworkName":"Bitcoin",
      "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
      "blockchainTransactions":[
         {
            "type":"CHECKOUT_ORIGIN",
            "typeDescription":"Blockchain payment transaction initiated by customer.",
            "network":"BITCOIN",
            "networkName":"Bitcoin",
            "timestamp":"2023-05-29T17:55:52+00:00",
            "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
            "amount":"0.0043193",
            "amountAssetCode":"BTC",
            "exception":null
         },
         {
            "type":"CHECKOUT_BRIDGE",
            "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2023-05-29T17:56:03+00:00",
            "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
            "amount":"0.0043193",
            "amountAssetCode":"BTC",
            "exception":null
         },
         {
            "type":"CHECKOUT_SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2023-05-29T17:56:03+00:00",
            "tx":"9e912d924d6a27ee858e011db14825f016f835249302f90b82237a9b9782bde0",
            "amount":"117.8379738",
            "amountAssetCode":"USDC",
            "exception":null
         }
      ],
      "payload":{
         "charge":{
            "customerId":"bb657e88a23d",
            "currency":"EUR",
            "lineItems":[
               {
                  "description":"Mobile Data Prepaid Credits",
                  "netAmount":"110.00000"
               }
            ],
            "shippingCostItems":[
               {
                  "description":"Instant Delivery",
                  "netAmount":0
               }
            ],
            "taxItems":[
               {
                  "name":"Hong Kong Sales Tax",
                  "percent":0
               }
            ]
         },
         "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "webhook":"https://www.my-server.com/api/?action=cq-webhook",
         "links":{
            "cancelUrl":"https://www.my-server.com/en/payments",
            "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
         }
      },
      "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.checkout{}`	array	The checkout object.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`, `RESOLVED_REFUNDED`, `RESOLVED_OTHER`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset as given by `GET /assets` that you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for transfer.	false
`.settlementAmountFeePaid`	string	The processing fee collected by Whalestack.	false
`.sourceAssetId`	string	The Stellar representation of the source asset as given by `GET /assets`. Indicates the payment asset selected by your customer. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetwork`	string	A payment network id as given by (`GET /networks`). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetworkName`	string	The selected network name in English plain text.	true
`.depositAddress`	string	The deposit address associated with this checkout. This field is null for checkouts in `PENDING_CHARGE` state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be `CHECKOUT_ORIGIN` (blockchain payment transaction initiated by the sender, `CHECKOUT_BRIDGE` (fund transfer from native blockchain to Stellar Network), or `CHECKOUT_SETTLEMENT` (Stellar transaction crediting your Whalestack account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `EXCHANGE_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`.	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutsprotetto

Recupera un elenco di oggetti del checkout (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/checkouts?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of checkout objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":67,
   "limit":1,
   "offset":0,
   "checkouts":[
      {
         "id":"a2d963a87d70",
         "timestamp":"2023-05-29T17:36:30+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"117.8379738",
         "settlementAmountReceived":"117.8379738",
         "settlementAmountFeePaid":"0.0000000",
         "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "sourceAmountRequired":"0.0043193",
         "sourceAmountReceived":"0.0043193",
         "sourceNetwork":"BITCOIN",
         "sourceNetworkName":"Bitcoin",
         "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
         "blockchainTransactions":[
            {
               "type":"CHECKOUT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2023-05-29T17:55:52+00:00",
               "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_BRIDGE",
               "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"9e912d924d6a27ee858e011db14825f016f835249302f90b82237a9b9782bde0",
               "amount":"117.8379738",
               "amountAssetCode":"USDC",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "customerId":"bb657e88a23d",
               "currency":"EUR",
               "lineItems":[
                  {
                     "description":"Mobile Data Prepaid Credits",
                     "netAmount":"110.00000"
                  }
               ],
               "shippingCostItems":[
                  {
                     "description":"Instant Delivery",
                     "netAmount":0
                  }
               ],
               "taxItems":[
                  {
                     "name":"Hong Kong Sales Tax",
                     "percent":0
                  }
               ]
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "webhook":"https://www.my-server.com/api/?action=cq-webhook",
            "links":{
               "cancelUrl":"https://www.my-server.com/en/payments",
               "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
            }
         },
         "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of checkout URLs in existence for this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.checkouts[]`	array	A list of checkout objects.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`, `RESOLVED_REFUNDED`, `RESOLVED_OTHER`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset as given by `GET /assets` that you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for transfer.	false
`.settlementAmountFeePaid`	string	The processing fee collected by Whalestack.	false
`.sourceAssetId`	string	The Stellar representation of the source asset as given by `GET /assets`. Indicates the payment asset selected by your customer. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetwork`	string	A payment network id as given by (`GET /networks`). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetworkName`	string	The selected network name in English plain text.	true
`.depositAddress`	string	The deposit address associated with this checkout. This field is null for checkouts in `PENDING_CHARGE` state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be `CHECKOUT_ORIGIN` (blockchain payment transaction initiated by the sender, `CHECKOUT_BRIDGE` (fund transfer from native blockchain to Stellar Network), or `CHECKOUT_SETTLEMENT` (Stellar transaction crediting your Whalestack account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `EXCHANGE_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`.	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletsprotetto

Restituisce un elenco di elementi del portafoglio contenenti informazioni sull'asset associato, il saldo, le reti disponibili e gli indirizzi di deposito (se disponibili).

Richiesta

curl 'https://www.whalestack.com/api/v1/wallets'

Risposta di Successo application/json

{
   "wallet":{
      "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "balance":"0.7343414",
      "currencyCode":"USD",
      "networks":[
         {
            "network":"STELLAR",
            "depositAddress":{
               "fields":{
                  "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                  "account":"GBDHWMSXQ24FA2LJTPUH3HNK3WR7BJW3DUUBLMSNSJ7ST4XZK7WJHPCQ",
                  "memo":"sd376139586edb",
                  "memoType":"text"
               },
               "fieldConfig":[
                  {
                     "key":"asset",
                     "label":"Stellar Asset",
                     "description":"The deposit asset identifier on the Stellar network. Consists of asset code and Stellar account."
                  },
                  {
                     "key":"account",
                     "label":"Stellar Account",
                     "description":"The deposit account on the Stellar network. Starting with G."
                  },
                  {
                     "key":"memo",
                     "label":"Memo",
                     "description":"The mandatory memo to be included in the transaction. Do not omit this or your deposit will be delayed."
                  },
                  {
                     "key":"memoType",
                     "label":"Memo Type",
                     "description":"The mandatory memo type to be included in the transaction."
                  }
               ],
               "minAmount":"0.0000001",
               "maxAmount":"1000000"
            }
         },
         {
            "network":"SWIFT",
            "depositAddress":{
               "fields":{
                  "reference":"EUR-BD-USDC-376139586eda",
                  "beneficiary":"Whalestack Sp. z o.o.",
                  "account":"LT293550020000022181",
                  "swiftCode":"UAPELT22XXX",
                  "bankName":"UAB Pervesk",
                  "bankAddress":"Gedimino pr. 5-3, LT-01103 Vilnius, Lithuania",
                  "correspondentBankSwift":"INCOCHZZXXX",
                  "correspondentBankName":"INCORE BANK AG",
                  "correspondentBankAddress":"Wiesenstrasse 17, Schlieren, Switzerland"
               },
               "fieldConfig":[
                  {
                     "key":"reference",
                     "label":"Payment Reference",
                     "description":"Add this reference to your SWIFT deposit. It is needed to map the deposit to your merchant account. Do not omit this or your deposit will be delayed."
                  },
                  {
                     "key":"beneficiary",
                     "label":"Beneficiary",
                     "description":"The beneficiary account name."
                  },
                  {
                     "key":"account",
                     "label":"Bank Account Number",
                     "description":"The bank account number."
                  },
                  {
                     "key":"swiftCode",
                     "label":"SWIFT\/BIC",
                     "description":"The 8-11 character SWIFT or BIC code identifying your bank or financial institution."
                  },
                  {
                     "key":"bankName",
                     "label":"Bank Name",
                     "description":"The beneficiary bank name."
                  },
                  {
                     "key":"bankAddress",
                     "label":"Bank Address",
                     "description":"The beneficiary bank address."
                  },
                  {
                     "key":"correspondentBankSwift",
                     "label":"Correspondent Bank SWIFT\/BIC",
                     "description":"Provide this SWIFT\/BIC code if your bank asks you for an intermediary or correspondent bank."
                  },
                  {
                     "key":"correspondentBankName",
                     "label":"Correspondent Bank Name",
                     "description":"The correspondent bank name. Provide this if your bank asks you for an intermediary or correspondent bank."
                  },
                  {
                     "key":"correspondentBankAddress",
                     "label":"Correspondent Bank Address",
                     "description":"The correspondent bank address."
                  }
               ],
               "minAmount":"250",
               "maxAmount":"1000000"
            }
         },
         {
            "network":"SEPA",
            "depositAddress":{
               "fields":{
                  "reference":"EUR-BD-USDC-376139586eda",
                  "beneficiary":"Whalestack Sp. z o.o.",
                  "iban":"LT293550020000022181",
                  "swiftCode":"UAPELT22XXX",
                  "bankName":"UAB Pervesk",
                  "bankAddress":"Gedimino pr. 5-3, LT-01103 Vilnius, Lithuania"
               },
               "fieldConfig":[
                  {
                     "key":"reference",
                     "label":"Payment Reference",
                     "description":"Add this reference to your SEPA deposit. It is needed to map the deposit to your merchant account. Do not omit this or your deposit will be delayed."
                  },
                  {
                     "key":"beneficiary",
                     "label":"Beneficiary",
                     "description":"The beneficiary account name."
                  },
                  {
                     "key":"iban",
                     "label":"IBAN",
                     "description":"The international bank account number (IBAN)."
                  },
                  {
                     "key":"swiftCode",
                     "label":"SWIFT\/BIC",
                     "description":"The 8-11 character SWIFT or BIC code identifying your bank or financial institution."
                  },
                  {
                     "key":"bankName",
                     "label":"Bank Name",
                     "description":"The beneficiary bank name."
                  },
                  {
                     "key":"bankAddress",
                     "label":"Bank Address",
                     "description":"The beneficiary bank address."
                  }
               ],
               "minAmount":"100",
               "maxAmount":"1000000"
            }
         }
      ]
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.wallets[]`	array	A list objects, representing the wallets in your account.	false
`.asset`	string	The asset identifier as given by `GET /assets`.	false
`.balance`	string	The asset balance in your wallet.	false
`.currencyCode`	string	The asset's normalized currency code as given by `GET /currencies`.	false
`.networks[]`	array	A list of networks with your wallet deposit addresses. Network identifiers as given by `GET /networks`. This list also indicates to which networks the asset can be transferred to.	false
`.network`	string	A network identifier as given by `GET /networks`.	false
`.depositAddress{}`	object	An object containing the deposit address to which the payment was made. Consists of `fields`, `fieldConfig`, `minAmount`, and `maxAmount` as documented in `POST /deposit-address`.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletprotetto

Restituisce un elemento portafoglio contenente informazioni sull'asset associato, il saldo, le reti disponibili e gli indirizzi di deposito (se disponibili).

Richiesta

curl 'https://www.whalestack.com/api/v1/wallet?asset=XXX'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`asset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`.	-	mandatory

Risposta di Successo application/json

{
   "wallet":{
      "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "balance":"7.1403584",
      "currencyCode":"BTC",
      "networks":[
         {
            "network":"BITCOIN",
            "depositAddress":{
               "fields":{
                  "address":"3QdzvaD2pfKEkqguxAfXW274TUJMtiXqG5"
               },
               "fieldConfig":[
                  {
                     "key":"address",
                     "label":"Bitcoin Address",
                     "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
                  }
               ],
               "minAmount":"0.0000100",
               "maxAmount":"100.0000000"
            }
         },
         {
            "network":"STELLAR",
            "depositAddress":{
               "fields":{
                  "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
                  "account":"GBDHWMSXQ24FA2LJTPUH3HNK3WR7BJW3DUUBLMSNSJ7ST4XZK7WJHPCQ",
                  "memo":"sd376139586edb",
                  "memoType":"text"
               },
               "fieldConfig":[
                  {
                     "key":"asset",
                     "label":"Stellar Asset",
                     "description":"The deposit asset identifier on the Stellar network. Consists of asset code and Stellar account."
                  },
                  {
                     "key":"account",
                     "label":"Stellar Account",
                     "description":"The deposit account on the Stellar network. Starting with G."
                  },
                  {
                     "key":"memo",
                     "label":"Memo",
                     "description":"The mandatory memo to be included in the transaction. Do not omit this or your deposit will be delayed."
                  },
                  {
                     "key":"memoType",
                     "label":"Memo Type",
                     "description":"The mandatory memo type to be included in the transaction."
                  }
               ],
               "minAmount":"0.0000001",
               "maxAmount":"1000000"
            }
         }
      ]
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.wallet{}`	array	An object containing information about the wallet.	false
`.asset`	string	The asset identifier as given by `GET /assets`.	false
`.balance`	string	The asset balance in your wallet.	false
`.currencyCode`	string	The asset's normalized currency code as given by `GET /currencies`.	false
`.networks[]`	array	A list of networks with your wallet deposit addresses. Network identifiers as given by `GET /networks`. This list also indicates to which networks the asset can be transferred to.	false
`.network`	string	A network identifier as given by `GET /networks`.	false
`.depositAddress{}`	object	An object containing the deposit address to which the payment was made. Consists of `fields`, `fieldConfig`, `minAmount`, and `maxAmount` as documented in `POST /deposit-address`.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/deposit-addressprotetto

Crea il tuo indirizzo blockchain o di deposito bancario per una rete e un asset specifici.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/deposit \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempi di Payload

Il payload dipende dalla rete di origine dalla quale stai depositando i fondi. Seleziona qui sotto.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

{
    "network": "BITCOIN"
}

{
    "network": "LIGHTNING",
    "amount": "5000"
}

{
    "network": "LITECOIN"
}

{
    "network": "STELLAR",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

{
    "network": "SWIFT",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

{
    "network": "SEPA",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Parametri della Richiesta (POST)

Il payload dipende dalla rete di origine dalla quale stai depositando i fondi. Seleziona qui sotto.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `BITCOIN`.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `LIGHTNING`.	false	mandatory
`.amount`	string	Importo della fattura in SAT.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `LITECOIN`.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `STELLAR`.	false	mandatory
`.asset`	string	L'identificatore dell'asset di deposito sulla rete Stellar. È composto dal codice dell'asset e dall'emittente.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `SWIFT`.	false	mandatory
`.asset`	string	Specifica l'asset accreditato sul tuo account quando il deposito viene completato. Si fa riferimento a USDC o EURC. Un identificatore dell'asset come indicato da `GET /assets`.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	Un identificatore di rete di destinazione come indicato da `GET /networks`, cioè `SEPA`.	false	mandatory
`.asset`	string	Specifica l'asset accreditato sul tuo account quando il deposito viene completato. Si fa riferimento a USDC o EURC. Un identificatore dell'asset come indicato da `GET /assets`.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Risposta di Successo application/json

Il payload dipende dalla rete di origine dalla quale stai depositando i fondi. Seleziona qui sotto.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

{
    "depositAddress": {
        "network": "BITCOIN",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Bitcoin",
                "description": "L'indirizzo Bitcoin. Puu00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "100.0000000"
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.address`	string	L'indirizzo Bitcoin. Può essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH).	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "LIGHTNING",
        "fields": {
            "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9c...",
            "amount": "5000"
        },
        "fieldConfig": [
            {
                "key": "invoice",
                "label": "Fattura Lightning",
                "description": "Una fattura Lightning BOLT 11 con importo codificato."
            },
            {
                "key": "amount",
                "label": "Importo della Fattura",
                "description": "Importo della fattura in SAT."
            }
        ],
        "minAmount": "4000.0000000",
        "maxAmount": "507059.0000000"
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `LIGHTNING`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.invoice`	string	Una fattura Lightning BOLT 11 con importo codificato.	false
`.amount`	string	Importo della fattura in SAT.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "LITECOIN",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdf"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Litecoin",
                "description": "L'indirizzo Litecoin. Puu00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "10000.0000000"
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `LITECOIN`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.address`	string	L'indirizzo Litecoin. Può essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH).	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "STELLAR",
        "fields": {
            "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU7",
            "memo": "sda3195ad7ed65",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "asset",
                "label": "Asset Stellar",
                "description": "L'identificatore dell'asset di deposito sulla rete Stellar. u00c8 composto dal codice dell'asset e dall'emittente."
            },
            {
                "key": "account",
                "label": "Account Stellar",
                "description": "L'account di deposito sulla rete Stellar, inizia con G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "Il memo obbligatorio u00e8 da includere nella transazione. Non ometterlo, altrimenti il tuo deposito subiru00e0 ritardi."
            },
            {
                "key": "memoType",
                "label": "Tipo di Memo",
                "description": "Il tipo di memo obbligatorio u00e8 da includere nella transazione."
            }
        ],
        "minAmount": "0.0000001",
        "maxAmount": "1000000"
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `STELLAR`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.asset`	string	L'identificatore dell'asset di deposito sulla rete Stellar. È composto dal codice dell'asset e dall'emittente.	false
`.account`	string	L'account di deposito sulla rete Stellar, inizia con G.	false
`.memo`	string	Il memo obbligatorio è da includere nella transazione. Non ometterlo, altrimenti il tuo deposito subirà ritardi.	false
`.memoType`	string	Il tipo di memo obbligatorio è da includere nella transazione.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "SWIFT",
        "fields": {
            "reference": "EUR-BD-USDC-1a2b3c4d5e6f",
            "beneficiary": "Whalestack Sp. z o.o.",
            "account": "LT293550020000047621",
            "swiftCode": "UAPELT22XXX",
            "bankName": "UAB Pervesk",
            "bankAddress": "Vilnius, Lithuania",
            "correspondentBankSwift": "INCOCHZZXXX",
            "correspondentBankName": "INCORE BANK AG",
            "correspondentBankAddress": "Schlieren, Switzerland"
        },
        "fieldConfig": [
            {
                "key": "reference",
                "label": "Riferimento di Pagamento",
                "description": "Aggiungi questo riferimento al tuo deposito SWIFT. u00c8 necessario per mappare il deposito sul tuo account commerciante. Non ometterlo, altrimenti il tuo deposito subiru00e0 ritardi."
            },
            {
                "key": "beneficiary",
                "label": "Beneficiario",
                "description": "Il nome del beneficiario dell'account."
            },
            {
                "key": "account",
                "label": "Numero del Conto Bancario",
                "description": "Il numero del conto bancario."
            },
            {
                "key": "swiftCode",
                "label": "SWIFT/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            },
            {
                "key": "correspondentBankSwift",
                "label": "SWIFT/BIC della Banca Corrispondente",
                "description": "Fornisci questo codice SWIFT/BIC se la tua banca ti chiede un intermediario o una banca corrispondente."
            },
            {
                "key": "correspondentBankName",
                "label": "Nome della Banca Corrispondente",
                "description": "Il nome della banca corrispondente. Fornisci questo se la tua banca ti chiede un intermediario o una banca corrispondente."
            },
            {
                "key": "correspondentBankAddress",
                "label": "Indirizzo della Banca Corrispondente",
                "description": "L'indirizzo della banca corrispondente. Fornisci questo se la tua banca ti chiede un intermediario o una banca corrispondente."
            }
        ],
        "minAmount": 250,
        "maxAmount": 500000
    }
}

Invia Pagamento in EUR

Invia il pagamento denominato in EUR.

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `SWIFT`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.reference`	string	Aggiungi questo riferimento al tuo deposito SWIFT. È necessario per mappare il deposito sul tuo account commerciante. Non ometterlo, altrimenti il tuo deposito subirà ritardi.	false
`.beneficiary`	string	Il nome del beneficiario dell'account.	false
`.account`	string	Il numero del conto bancario.	false
`.swiftCode`	string	Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario.	false
`.bankName`	string	Il nome della banca beneficiaria.	false
`.bankAddress`	string	L'indirizzo della banca beneficiaria.	false
`.correspondentBankSwift`	string	Fornisci questo codice SWIFT/BIC se la tua banca ti chiede un intermediario o una banca corrispondente.	false
`.correspondentBankName`	string	Il nome della banca corrispondente. Fornisci questo se la tua banca ti chiede un intermediario o una banca corrispondente.	false
`.correspondentBankAddress`	string	L'indirizzo della banca corrispondente. Fornisci questo se la tua banca ti chiede un intermediario o una banca corrispondente.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "SEPA",
        "fields": {
            "reference": "EUR-BD-USDC-1a2b3c4d5e6f",
            "beneficiary": "Whalestack Sp. z o.o.",
            "iban": "LT293550020000047621",
            "swiftCode": "UAPELT22XXX",
            "bankName": "UAB Pervesk",
            "bankAddress": "Vilnius, Lithuania"
        },
        "fieldConfig": [
            {
                "key": "reference",
                "label": "Riferimento di Pagamento",
                "description": "Aggiungi questo riferimento al tuo deposito SEPA. u00c8 necessario per mappare il deposito sul tuo account commerciante. Non ometterlo, altrimenti il tuo deposito subiru00e0 ritardi."
            },
            {
                "key": "beneficiary",
                "label": "Beneficiario",
                "description": "Il nome del beneficiario dell'account."
            },
            {
                "key": "iban",
                "label": "IBAN",
                "description": "Il numero di conto bancario internazionale (IBAN)."
            },
            {
                "key": "swiftCode",
                "label": "SWIFT/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            }
        ],
        "minAmount": 50,
        "maxAmount": 500000
    }
}

Invia Pagamento in EUR

Invia il pagamento denominato in EUR.

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `SEPA`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.reference`	string	Aggiungi questo riferimento al tuo deposito SEPA. È necessario per mappare il deposito sul tuo account commerciante. Non ometterlo, altrimenti il tuo deposito subirà ritardi.	false
`.beneficiary`	string	Il nome del beneficiario dell'account.	false
`.iban`	string	Il numero di conto bancario internazionale (IBAN).	false
`.swiftCode`	string	Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario.	false
`.bankName`	string	Il nome della banca beneficiaria.	false
`.bankAddress`	string	L'indirizzo della banca beneficiaria.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositprotetto

Recupera i dettagli di un deposito specificato.

Richiesta

curl 'https://www.whalestack.com/api/v1/deposit?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Blockchain transaction id of your deposit or unique identifier as given by `GET /deposits`.	null	mandatory

Risposta di Successo application/json

{
   "deposit":{
      "id":"eb3729168fb2",
      "state":"COMPLETED",
      "timestamp":"2022-10-14T19:49:51+00:00",
      "network":"BITCOIN",
      "networkName":"Bitcoin",
      "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "currencyCode":"BTC",
      "amountGross":"7.1479281",
      "amountNet":"7.1479281",
      "amountFees":"0.0000000",
      "webhook":"https://www.your-server.com/path/to/webhook",
      "blockchainTransactions":[
         {
            "type":"DEPOSIT_ORIGIN",
            "typeDescription":"Blockchain transaction on the source network.",
            "network":"BITCOIN",
            "networkName":"Bitcoin",
            "timestamp":"2022-10-14T20:00:17+00:00",
            "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
            "amount":"7.1479281",
            "amountAssetCode":"BTC"
         },
         {
            "type":"DEPOSIT_SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2022-10-14T20:00:17+00:00",
            "tx":"24c69c410e48ab3f7dd264429ec090e954b3b8b3b9860a5dd6c130f2926e0857",
            "amount":"7.1479281",
            "amountAssetCode":"BTC"
         }
      ],
      "depositAddress":{
         "fields":{
            "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
         },
         "fieldConfig":[
            {
               "key":"address",
               "label":"Bitcoin Address",
               "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
         ]
      },
      "bankTransactions":null
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.deposit{}`	object	An object containing deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.state`	string	The deposit state. Possible values: `COMPLETED`, `FAILED`, `PROCESSING`, `PENDING_EXTERNAL`	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was first detected.	false
`.network`	string	A payment network id as given by `GET /networks`. Indicates the payment network on which the deposit was made.	false
`.networkName`	string	The payment network name in English plain text.	false
`.asset`	string	The Stellar representation of the asset credited to your account as given by `GET /assets`.	false
`.currencyCode`	string	The deposit currency code as given by `GET /currencies`.	false
`.amountGross`	string	The gross amount credited to your account.	false
`.amountNet`	string	The net amount credited to your account. These funds are instantly available for transfer.	false
`.amountFees`	string	The paid fees, if any.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this deposit (as specified in webhook concepts).	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender) or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your Whalestack account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.depositAddress{}`	object	An object containing the deposit address to which the payment was made. Consists of `fields` and `fieldConfig` as documented in `POST /deposit-address`.	true
`.bankTransactions[]`	array	A list of bank transactions associated with this deposit, if any.	true
`.id`	string(12)	A string identifying the bank transaction on Whalestack.	false
`.network`	string	The bank network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The bank network name in English plain text.	false
`.grossAmount`	string	The gross amount received by Whalestack in the bank transaction.	false
`.amountCurrency`	string(3)	The source currency as given by `GET /currencies`.	false
`.bankFee`	string	The fees collected by the bank(s) for processing the payment.	false
`.bankFeeCurrency`	string(3)	The fee currency as given by `GET /currencies`.	false
`.netAmount`	string	The net amount used for minting the deposit asset on Whalestack.	false
`.reference`	string	The reference line used in the bank payment.	false
`.sender`	string	The name of the sender of the originating bank account.	true
`.sourceAccount`	string	The bank account number of the sender.	true
`.sourceBank`	string	A BIC/SWIFT code identifying the sending bank.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositsprotetto

Recupera una lista dei tuoi depositi (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/deposits?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of deposit objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":1,
   "limit":10,
   "offset":0,
   "deposits":[
      {
         "id":"eb3729168fb2",
         "state":"COMPLETED",
         "timestamp":"2022-10-14T19:49:51+00:00",
         "network":"BITCOIN",
         "networkName":"Bitcoin",
         "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "currencyCode":"BTC",
         "amountGross":"7.1479281",
         "amountNet":"7.1479281",
         "amountFees":"0.0000000",
         "webhook":"https://www.your-server.com/path/to/webhook",
         "blockchainTransactions":[
            {
               "type":"DEPOSIT_ORIGIN",
               "typeDescription":"Blockchain transaction on the source network.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            },
            {
               "type":"DEPOSIT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"24c69c410e48ab3f7dd264429ec090e954b3b8b3b9860a5dd6c130f2926e0857",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            }
         ],
         "depositAddress":{
            "fields":{
               "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
            },
            "fieldConfig":[
               {
                  "key":"address",
                  "label":"Bitcoin Address",
                  "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
               }
            ]
         },
         "bankTransactions":null
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of deposits initiated in this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.deposits[]`	array	A list of deposit objects.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.state`	string	The deposit state. Possible values: `COMPLETED`, `FAILED`, `PROCESSING`, `PENDING_EXTERNAL`	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was first detected.	false
`.network`	string	A payment network id as given by `GET /networks`. Indicates the payment network on which the deposit was made.	false
`.networkName`	string	The payment network name in English plain text.	false
`.asset`	string	The Stellar representation of the asset credited to your account as given by `GET /assets`.	false
`.currencyCode`	string	The deposit currency code as given by `GET /currencies`.	false
`.amountGross`	string	The gross amount credited to your account.	false
`.amountNet`	string	The net amount credited to your account. These funds are instantly available for transfer.	false
`.amountFees`	string	The paid fees, if any.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this deposit (as specified in webhook concepts).	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender) or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your Whalestack account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.depositAddress{}`	object	An object containing the deposit address to which the payment was made. Consists of `fields` and `fieldConfig` as documented in `POST /deposit-address`.	true
`.bankTransactions[]`	array	A list of bank transactions associated with this deposit, if any.	true
`.id`	string(12)	A string identifying the bank transaction on Whalestack.	false
`.network`	string	The bank network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The bank network name in English plain text.	false
`.grossAmount`	string	The gross amount received by Whalestack in the bank transaction.	false
`.amountCurrency`	string(3)	The source currency as given by `GET /currencies`.	false
`.bankFee`	string	The fees collected by the bank(s) for processing the payment.	false
`.bankFeeCurrency`	string(3)	The fee currency as given by `GET /currencies`.	false
`.netAmount`	string	The net amount used for minting the deposit asset on Whalestack.	false
`.reference`	string	The reference line used in the bank payment.	false
`.sender`	string	The name of the sender of the originating bank account.	true
`.sourceAccount`	string	The bank account number of the sender.	true
`.sourceBank`	string	A BIC/SWIFT code identifying the sending bank.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swapprotetto

Avvia uno scambio di asset nel tuo account e restituisce un oggetto di scambio in uno stato PENDING_API_COMMIT. L'oggetto contiene una quotazione con importi di origine e destinazione. Per accettare la quotazione, conferma lo scambio invocando POST /swap/commit.

Richiesta

curl -X POST https://www.whalestack.com/api/v1/swap \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio: Swap 100 USDC in BTC

{
   "sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "sourceAmount":100,
   "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT"
}

Esempio: Swap BTC in 100 XLM

{
   "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
   "targetAsset":"XLM:NATIVE",
   "targetAmount":100
}

Parametri della Richiesta (POST)

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`sourceAsset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`. Specifies the source asset in the swap.	null	mandatory
`sourceAmount`	numeric	Specifies the amount of `sourceAsset` you wish to debit from your account to make the swap. The API response contains the calculated target amount, which you can inspect and confirm by invoking a subsequent request to `POST /swap/commit`. If you would like to specify the exact target amount instead, please use the `targetAmount` attribute and don't specify a `sourceAmount`.	null	optional
`targetAsset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`. Specifies the target asset in the swap.	null	mandatory
`targetAmount`	numeric	Specifies the amount of `targetAsset` you wish to credit to your account when the swap completes. The API response contains the required source amount, which you can inspect and confirm by invoking a subsequent request to `POST /swap/commit`. If you would like to specify the exact source amount instead, please use the `sourceAmount` attribute and don't specify a `targetAmount`.	null	optional
`webhook`	string	URL on your server listening for swap state changes as specified in webhook concepts. Overwrites webhook URL API Settings in the UI (if any).	null	optional

Risposta di Successo application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"PENDING_API_COMMIT",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetId":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[],
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.swap{}`	object	An object with swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction, i.e. `SWAP`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this swap (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swap/commitprotetto

Esegue e completa uno swap nello stato PENDING_API_COMMIT precedentemente iniziato con POST /swap.

Fornisce un elemento dello swap in uno stato PROCESSING non finale. Uno stato finale di COMPLETED o FAILED viene inviato tramite webhook e può essere verificato alternativamente utilizzando GET /swap.

Richiesta

curl -X POST 'https://www.whalestack.com/api/v1/swap/commit'
    -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
  "swapId":"12d72c3c8145"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`swapId`	string(12)	Unique identifier as given by `POST /swap`.	null	mandatory

Risposta di Successo application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"PROCESSING",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":"2021-05-06T22:16:01+00:00",
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetIssuer":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[],
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.swap{}`	object	An object containing swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction, i.e. `SWAP`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this swap (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapprotetto

Recupera i dettagli di uno swap specifico.

Richiesta

curl 'https://www.whalestack.com/api/v1/swap?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `GET /swaps` or `POST /swap`.	null	mandatory

Risposta di Successo application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"COMPLETED",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":"2021-05-06T22:16:01+00:00",
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetId":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[
        {
           "type":"SWAP",
           "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
           "network": "STELLAR",
           "networkName": "Stellar",
           "timestamp": "2021-05-06T22:16:01+00:00",
           "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
           "amount":"243.3928192",
           "amountAssetCode":"XLM"
        }
      ],
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.swap{}`	object	An object containing swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction, i.e. `SWAP`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this swap (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapsprotetto

Recupera un elenco dei tuoi swap (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/swaps?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of swap objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":2,
   "limit":10,
   "offset":0,
   "swaps":[
      {
         "id":"23b4f4ee055d",
         "state":"PENDING_API_COMMIT",
         "type":"SOURCE_SPECIFIED",
         "origin":"API",
         "createTime":"2021-05-06T22:15:37+00:00",
         "completeTime":null,
         "expireTime":"2021-05-06T23:15:37+00:00",
         "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "sourceAmount":"10.0000000",
         "targetAssetId":"XLM:NATIVE",
         "targetAmount":"24.1392819",
         "blockchainTransactions":[

         ],
         "webhook":"https://www.your-server.com/path/to/webhook"
      },
      {
         "id":"5074f4ee055d",
         "state":"COMPLETED",
         "type":"SOURCE_SPECIFIED",
         "origin":"API",
         "createTime":"2021-05-06T22:15:37+00:00",
         "completeTime":"2021-05-06T22:16:01+00:00",
         "expireTime":"2021-05-06T23:15:37+00:00",
         "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "sourceAmount":"100.0000000",
         "targetAssetId":"XLM:NATIVE",
         "targetAmount":"243.3928192",
         "blockchainTransactions":[
            {
               "type":"SWAP",
               "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2021-05-06T22:16:01+00:00",
               "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
               "amount":"243.3928192",
               "amountAssetCode":"XLM"
            }
         ],
         "webhook":"https://www.your-server.com/path/to/webhook"
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of swaps initiated in this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.swaps[]`	array	A list of swap objects.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction, i.e. `SWAP`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this swap (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/target-accountprotetto

Gli account di destinazione sono un prerequisito per i trasferimenti di fondi tramite l'API o l'applicazione web. Questo endpoint collega un account blockchain o bancario al tuo account sulla piattaforma Whalestack. Fai riferimento ad esso tramite le tue etichette personalizzate quando utilizzi l'endpoint POST /transfer.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/target-account \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempi di Payload

Il carico dipende dalla rete di destinazione a cui stai trasferendo fondi. Seleziona qui sotto.

Bitcoin Ethereum Lightning Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "network": "SWIFT",
    "label": "My Bank Account on SWIFT",
    "fields": {
        "account": "DE12334567890",
        "bic": "NTSBDEB1XXX",
        "bankName": "N26",
        "bankAddress": "Berlin, Germany"
    }
}

Utilizza solo Conti Bancari in EUR

Il tuo conto bancario deve essere in grado di ricevere depositi denominati in EUR. Altre valute non sono supportate.

Parametri della Richiesta (POST)

Il carico dipende dalla rete di destinazione a cui stai trasferendo fondi. Seleziona qui sotto.

Bitcoin Ethereum Lightning Litecoin Stellar SWIFT SEPA Brazilian PIX

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `BITCOIN`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.address`	string(62)	L'indirizzo Bitcoin. Può essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH).	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `ETHEREUM`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.account`	string(42)	Un account sulla rete Ethereum. Inizia con 0x.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `LITECOIN`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.address`	string(62)	L'indirizzo Litecoin. Può essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH).	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `STELLAR`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.account`	string(56)	Un account sulla rete Stellar. Che inizia con la lettera G.	false	mandatory
`.memo`	string(64)	Identifica il destinatario o lo scopo del pagamento. Un memo è spesso richiesto da borse e portafogli digitali. Assicurati di fornirne uno se necessario.	false	optional
`.memoType`	string(4)	Un ulteriore indicatore che identifica il tipo di memo. Solitamente si tratta di `text`. Available options: `texthashid`	false	optional
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SWIFT`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.account`	string(128)	Il numero del conto bancario.	false	mandatory
`.bic`	string(128)	Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario.	false	mandatory
`.bankName`	string(128)	Il nome della banca beneficiaria.	false	mandatory
`.bankAddress`	string(256)	L'indirizzo della banca beneficiaria.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SEPA`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.iban`	string(128)	Il numero di conto bancario internazionale (IBAN).	false	mandatory
`.bic`	string(128)	Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario.	false	mandatory
`.bankName`	string(128)	Il nome della banca beneficiaria.	false	mandatory
`.bankAddress`	string(256)	L'indirizzo della banca beneficiaria.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `PIX`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.pixKey`	string(256)	La chiave PIX associata al conto bancario del destinatario. Tipicamente un numero di telefono, CPF, indirizzo email o chiave casuale.	false	mandatory
`.taxId`	string(256)	Il codice fiscale del destinatario. Formato CNPJ (00.000.000/0000-00) per entità aziendali o formato CPF (000.000.000-00) per persone fisiche.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Risposta di Successo application/json

Il payload dipende dalla rete di destinazione. Seleziona qui sotto.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "targetAccount": {
        "network": "BITCOIN",
        "label": "Ledger Nano on Bitcoin",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Bitcoin",
                "description": "L'indirizzo Bitcoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "ETHEREUM",
        "label": "Ledger Nano on Ethereum",
        "fields": {
            "account": "0xA2Bf179E09C503262E418FC72261837726f68F36"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Account Ethereum",
                "description": "Un account sulla rete Ethereum. Inizia con 0x."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "LITECOIN",
        "label": "Ledger Nano on Litecoin",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Litecoin",
                "description": "L'indirizzo Litecoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "STELLAR",
        "label": "Ledger Nano on Stellar",
        "fields": {
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo": "EXODUS",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Account Stellar",
                "description": "Un account sulla rete Stellar. Che inizia con la lettera G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "Identifica il destinatario o lo scopo del pagamento. Un memo \u00e8 spesso richiesto da borse e portafogli digitali. Assicurati di fornirne uno se necessario."
            },
            {
                "key": "memoType",
                "label": "Tipo di Memo",
                "description": "Un ulteriore indicatore che identifica il tipo di memo. Solitamente si tratta di `text`."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "SWIFT",
        "label": "My Bank Account on SWIFT",
        "fields": {
            "account": "DE12334567890",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Numero del Conto Bancario",
                "description": "Il numero del conto bancario."
            },
            {
                "key": "bic",
                "label": "SWIFT\/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "SEPA",
        "label": "My Bank Account on SEPA",
        "fields": {
            "iban": "DE23100110012624331586",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "iban",
                "label": "IBAN",
                "description": "Il numero di conto bancario internazionale (IBAN)."
            },
            {
                "key": "bic",
                "label": "SWIFT\/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "PIX",
        "label": "My Bank Account on Brazilian PIX",
        "fields": {
            "pixKey": "34.773.171\/0001-75",
            "taxId": "34.773.171\/0001-75"
        },
        "fieldConfig": [
            {
                "key": "pixKey",
                "label": "PIX Key",
                "description": "La chiave PIX associata al conto bancario del destinatario. Tipicamente un numero di telefono, CPF, indirizzo email o chiave casuale."
            },
            {
                "key": "taxId",
                "label": "Partita IVA",
                "description": "Il codice fiscale del destinatario. Formato CNPJ (00.000.000\/0000-00) per entit\u00e0 aziendali o formato CPF (000.000.000-00) per persone fisiche."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.targetAccount{}`	object	An object with target account information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`, `LITECOIN`, `SWIFT`, or `SEPA`.	false
`.label`	string	An arbitrary account name given by you when creating the target account. This is a unique identifier which you use this to reference this target account in other API requests, such as `POST /transfer`.	false
`.fields`	object	A set of fields (all strings) specifying the account on the target network. Conforms to the field specification used when invoking `POST /target-account`. Inspect the `fieldConfig` attribute for an explanation of each field.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.state`	string	The target account state. Possible values: `ACTIVE`, `PENDING_CONFIRMATION` , `TRANSIENT`	true
`timestamp`	string	W3C formatted time stamp with time zone (UTC) indicating when the target account was added.	true
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary associated this target account with, if any. As given by `GET /beneficiaries` or other beneficiary related endpoints.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/target-accountprotetto

Recupera informazioni su un determinato account di destinazione.

Richiesta

curl 'https://www.whalestack.com/api/v1/target-account?label=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`label`	string	The unique label (account name) as given by you in `POST /post-target-account` or the web app UI.	null	mandatory

Risposta di Successo application/json

Il payload dipende dalla rete di destinazione. Seleziona qui sotto.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "targetAccount": {
        "network": "BITCOIN",
        "label": "Ledger Nano on Bitcoin",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Bitcoin",
                "description": "L'indirizzo Bitcoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "ETHEREUM",
        "label": "Ledger Nano on Ethereum",
        "fields": {
            "account": "0xA2Bf179E09C503262E418FC72261837726f68F36"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Account Ethereum",
                "description": "Un account sulla rete Ethereum. Inizia con 0x."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "LITECOIN",
        "label": "Ledger Nano on Litecoin",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Indirizzo Litecoin",
                "description": "L'indirizzo Litecoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "STELLAR",
        "label": "Ledger Nano on Stellar",
        "fields": {
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo": "EXODUS",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Account Stellar",
                "description": "Un account sulla rete Stellar. Che inizia con la lettera G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "Identifica il destinatario o lo scopo del pagamento. Un memo \u00e8 spesso richiesto da borse e portafogli digitali. Assicurati di fornirne uno se necessario."
            },
            {
                "key": "memoType",
                "label": "Tipo di Memo",
                "description": "Un ulteriore indicatore che identifica il tipo di memo. Solitamente si tratta di `text`."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "SWIFT",
        "label": "My Bank Account on SWIFT",
        "fields": {
            "account": "DE12334567890",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Numero del Conto Bancario",
                "description": "Il numero del conto bancario."
            },
            {
                "key": "bic",
                "label": "SWIFT\/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "SEPA",
        "label": "My Bank Account on SEPA",
        "fields": {
            "iban": "DE23100110012624331586",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "iban",
                "label": "IBAN",
                "description": "Il numero di conto bancario internazionale (IBAN)."
            },
            {
                "key": "bic",
                "label": "SWIFT\/BIC",
                "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
            },
            {
                "key": "bankName",
                "label": "Nome Banca",
                "description": "Il nome della banca beneficiaria."
            },
            {
                "key": "bankAddress",
                "label": "Indirizzo Banca",
                "description": "L'indirizzo della banca beneficiaria."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "PIX",
        "label": "My Bank Account on Brazilian PIX",
        "fields": {
            "pixKey": "34.773.171\/0001-75",
            "taxId": "34.773.171\/0001-75"
        },
        "fieldConfig": [
            {
                "key": "pixKey",
                "label": "PIX Key",
                "description": "La chiave PIX associata al conto bancario del destinatario. Tipicamente un numero di telefono, CPF, indirizzo email o chiave casuale."
            },
            {
                "key": "taxId",
                "label": "Partita IVA",
                "description": "Il codice fiscale del destinatario. Formato CNPJ (00.000.000\/0000-00) per entit\u00e0 aziendali o formato CPF (000.000.000-00) per persone fisiche."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.targetAccount{}`	object	An object with target account information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`, `LITECOIN`, `SWIFT`, or `SEPA`.	false
`.label`	string	An arbitrary account name given by you when creating the target account. This is a unique identifier which you use this to reference this target account in other API requests, such as `POST /transfer`.	false
`.fields`	object	A set of fields (all strings) specifying the account on the target network. Conforms to the field specification used when invoking `POST /target-account`. Inspect the `fieldConfig` attribute for an explanation of each field.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.state`	string	The target account state. Possible values: `ACTIVE`, `PENDING_CONFIRMATION` , `TRANSIENT`	true
`timestamp`	string	W3C formatted time stamp with time zone (UTC) indicating when the target account was added.	true
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary associated this target account with, if any. As given by `GET /beneficiaries` or other beneficiary related endpoints.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/target-accountsprotetto

Fornisce un elenco di elementi dell'account di destinazione (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/target-accounts?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of target account objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

Il payload di ciascun elemento dipende dalla rete di destinazione. Seleziona qui sotto.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "BITCOIN",
            "label": "Ledger Nano on Bitcoin",
            "fields": {
                "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "Indirizzo Bitcoin",
                    "description": "L'indirizzo Bitcoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "ETHEREUM",
            "label": "Ledger Nano on Ethereum",
            "fields": {
                "account": "0xA2Bf179E09C503262E418FC72261837726f68F36"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Account Ethereum",
                    "description": "Un account sulla rete Ethereum. Inizia con 0x."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "LITECOIN",
            "label": "Ledger Nano on Litecoin",
            "fields": {
                "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "Indirizzo Litecoin",
                    "description": "L'indirizzo Litecoin. Pu\u00f2 essere in qualsiasi formato, ad esempio originario SegWit (bech32), SegWit (P2SH) o legacy (P2PKH)."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "STELLAR",
            "label": "Ledger Nano on Stellar",
            "fields": {
                "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
                "memo": "EXODUS",
                "memoType": "text"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Account Stellar",
                    "description": "Un account sulla rete Stellar. Che inizia con la lettera G."
                },
                {
                    "key": "memo",
                    "label": "Memo",
                    "description": "Identifica il destinatario o lo scopo del pagamento. Un memo \u00e8 spesso richiesto da borse e portafogli digitali. Assicurati di fornirne uno se necessario."
                },
                {
                    "key": "memoType",
                    "label": "Tipo di Memo",
                    "description": "Un ulteriore indicatore che identifica il tipo di memo. Solitamente si tratta di `text`."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "SWIFT",
            "label": "My Bank Account on SWIFT",
            "fields": {
                "account": "DE12334567890",
                "bic": "NTSBDEB1XXX",
                "bankName": "N26",
                "bankAddress": "Berlin, Germany"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Numero del Conto Bancario",
                    "description": "Il numero del conto bancario."
                },
                {
                    "key": "bic",
                    "label": "SWIFT\/BIC",
                    "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
                },
                {
                    "key": "bankName",
                    "label": "Nome Banca",
                    "description": "Il nome della banca beneficiaria."
                },
                {
                    "key": "bankAddress",
                    "label": "Indirizzo Banca",
                    "description": "L'indirizzo della banca beneficiaria."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "SEPA",
            "label": "My Bank Account on SEPA",
            "fields": {
                "iban": "DE23100110012624331586",
                "bic": "NTSBDEB1XXX",
                "bankName": "N26",
                "bankAddress": "Berlin, Germany"
            },
            "fieldConfig": [
                {
                    "key": "iban",
                    "label": "IBAN",
                    "description": "Il numero di conto bancario internazionale (IBAN)."
                },
                {
                    "key": "bic",
                    "label": "SWIFT\/BIC",
                    "description": "Il codice SWIFT o BIC di 8-11 caratteri che identifica la tua banca o istituto finanziario."
                },
                {
                    "key": "bankName",
                    "label": "Nome Banca",
                    "description": "Il nome della banca beneficiaria."
                },
                {
                    "key": "bankAddress",
                    "label": "Indirizzo Banca",
                    "description": "L'indirizzo della banca beneficiaria."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "PIX",
            "label": "My Bank Account on Brazilian PIX",
            "fields": {
                "pixKey": "34.773.171\/0001-75",
                "taxId": "34.773.171\/0001-75"
            },
            "fieldConfig": [
                {
                    "key": "pixKey",
                    "label": "PIX Key",
                    "description": "La chiave PIX associata al conto bancario del destinatario. Tipicamente un numero di telefono, CPF, indirizzo email o chiave casuale."
                },
                {
                    "key": "taxId",
                    "label": "Partita IVA",
                    "description": "Il codice fiscale del destinatario. Formato CNPJ (00.000.000\/0000-00) per entit\u00e0 aziendali o formato CPF (000.000.000-00) per persone fisiche."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of target accounts in this account.	false
`.limit`	integer	The limit parameter used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.targetAccounts[]`	array	An list of objects with target account information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`, `LITECOIN`, `SWIFT`, or `SEPA`.	false
`.label`	string	An arbitrary account name given by you when creating the target account. This is a unique identifier which you use this to reference this target account in other API requests, such as `POST /transfer`.	false
`.fields`	object	A set of fields (all strings) specifying the account on the target network. Conforms to the field specification used when invoking `POST /target-account`. Inspect the `fieldConfig` attribute for an explanation of each field.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.state`	string	The target account state. Possible values: `ACTIVE`, `PENDING_CONFIRMATION` , `TRANSIENT`	true
`timestamp`	string	W3C formatted time stamp with time zone (UTC) indicating when the target account was added.	true
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary associated this target account with, if any. As given by `GET /beneficiaries` or other beneficiary related endpoints.	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/target-accountprotetto

Annulla il collegamento di un account di destinazione dalla piattaforma Whalestack.

Richiesta di esempio

curl -X DELETE https://www.whalestack.com/api/v1/target-account \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
    "label":"My SEPA Bank Account"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`label`	string	Unique label (account name) as given in `POST /target-account` or listed in other target account related endpoints.	null	mandatory

Risposta di Successo application/json

{
    "success":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/transferprotetto

Inizia un trasferimento di fondi dal tuo portafoglio al tuo conto bancario esterno o al tuo conto blockchain. Fornisce un elemento di trasferimento in uno stato PENDING_API_COMMIT. L'oggetto contiene una quotazione con importi di origine, destinazione e tassa di rete (se presente). Per accettare la quotazione, conferma il trasferimento invocando POST /transfer/commit.

Dipende dalle chiamate precedenti a POST /target-account che collegano account esterni per i trasferimenti.

Richiesta

curl -X POST https://www.whalestack.com/api/v1/transfer \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio: Trasferisci 5.000 USDC sul tuo conto SEPA (in EUR)

{
   "network":"SEPA",
   "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "amount":5000,
   "targetAccount":"A unique SEPA account label as previously specified in POST /target-account"
}

Esempio: Trasferisci BTC con un importo netto di destinazione di 0,5 BTC

{
   "network":"BITCOIN",
   "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
   "amount":0.5,
   "amountType":"target",
   "targetAccount":"A unique Bitcoin address label as previously specified in POST /target-account"
}

Esempio: Effettua un trasferimento verso una fattura Bitcoin Lightning BOLT 11

{
   "network":"LIGHTNING",
   "asset":"BTCLN:GDPKQ2TSNJOFSEE7XSUXPWRP27H6GFGLWD7JCHNEYYWQVGFA543EVBVT",
   "invoice":"lnbc138200n1p3mxqgwpp53800g24ftkeevp82sfvkm20ygw34f4cst99fq9ar..."
}

Esempio: Trasferisci 5.000 USDC a un account Stellar

{
   "network":"STELLAR",
   "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "amount":5000,
   "targetAccount":"A unique Stellar account label as previously specified in POST /target-account"
}

Esempio: Trasferisci 5.000 USDC a un account Ethereum

{
   "network":"ETHEREUM",
   "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "amount":5000,
   "targetAccount":"A unique Ethereum account label as previously specified in POST /target-account"
}

Parametri della Richiesta (POST)

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`network`	string	A network identifier as given by `GET /networks` or `GET /wallets`. Specifies the target network for the transfer.	null	mandatory
`asset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`. Specifies the source asset in the transfer.	null	mandatory
`amount`	numeric	Specifies the amount of `asset` you wish to send. By default, this amount is debited from your account and the beneficiary is credited the same amount net of network fees, if any. If you wish to specify the exact target amount and carry the network fees on your side, please set `target` on the `amountType` parameter and specify the desired net target amount in this field.	null	mandatory
`amountType`	string	Can be `source` (default) or `target`. If set to `source` then the `amount` field specifies the exact amount debited from your account. Beneficiary receives the same amount net of fees. Obtain fee and target amount details from the response. If set to `target` then the `amount` field specifies the exact target amount received by the beneficiary. Fees are carried by the sender and included in the amount debited from your account. Obtain fee and source amount details from the response.	source	optional
`targetAccount`	string	The target account to which the transfer is sent. Referenced by the unique `label` originally specified in `POST /target-account`. Must match the network of the given `asset`.	null	mandatory
`invoice`	string	This field is only relevant when sending transfers towards the Bitcoin `LIGHTNING` network. It is also the only required field besides `network` and `asset` in that case. Should include a BOLT 11 Lightning invoice with encoded amount. Ignore this field when transferring to other networks.	null	optional
`note`	string	An arbitrary note in plain text providing you with additional context for this transfer.	null	optional
`webhook`	string	URL on your server listening for transfer state changes via `WEBHOOK transfer-completed` or `WEBHOOK transfer-failed`. Overwrites webhook URL API Settings in the UI (if any).	null	optional

Risposta di Successo application/json

{
   "transfer":{
      "id":"8947deb6a087",
      "type":"TRANSFER",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "network":"BITCOIN",
      "timestamp":"2023-05-22 03:06:34+03:00",
      "note":null,
      "sourceAmountGross":"0.5000000",
      "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "networkFeeAmount":"0.0002010",
      "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "targetAmountNet":"0.4997990",
      "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "blockchainTransactions":[],
      "targetAccount":{
         "network":"BITCOIN",
         "label":"Bitcoin (bc1qj)",
         "fields":{
            "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
         },
         "fieldConfig":[
            {
               "key":"address",
               "label":"Bitcoin Address",
               "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
         ],
         "state":"ACTIVE",
         "timestamp":"2023-05-21T21:00:26+00:00",
         "beneficiaryId":null
      },
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.transfer{}`	object	An object with transfer information.	false
`.id`	string(12)	Unique identifier of this transfer.	false
`.type`	string	The transfer type, i.e. `TRANSFER`	false
`.state`	string	The transfer state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.origin`	string	Indicates how the transfer was initiated, either `UI` or `API`.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the transfer was created.	false
`.note`	note	An arbitrary text submitted when invoking `POST /transfer`.	true
`.sourceAmountGross`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account during the transfer.	false
`.sourceAsset`	string	The source asset. An asset id as given by `GET /assets`.	false
`.networkFeeAmount`	string	A numeric string indicating the total amount of `networkFeeAsset` used during the transfer.	false
`.networkFeeAsset`	string	The network fee asset. An asset id as given by `GET /assets`.	false
`.targetAmountNet`	string	A numeric string indicating the total amount of `targetAsset` received by the beneficiary.	false
`.targetAsset`	string	The target asset. An asset id as given by `GET /assets`.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction, i.e. `TRANSFER_PAYOUT`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.targetAccount`	object	An object specifying the target account for this transfer, as documented here: `GET /target-account`.	true
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this transfer (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/transfer/commitprotetto

Conferma ed esegue un trasferimento di fondi nello stato PENDING_API_COMMIT precedentemente avviato con POST /transfer.

Restituisce un elemento del trasferimento in uno stato non finale PROCESSING. Uno stato finale di COMPLETED o FAILED viene inviato tramite webhook e può essere verificato alternativamente utilizzando GET /transfer.

Richiesta

curl -X POST 'https://www.whalestack.com/api/v1/transfer/commit'
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
  "transferId":"12d72c3c8145"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`transferId`	string(12)	Unique identifier as given by `POST /transfer`.	null	mandatory

Risposta di Successo application/json

{
   "transfer":{
      "id":"8947deb6a087",
      "type":"TRANSFER",
      "state":"PROCESSING",
      "origin":"API",
      "network":"BITCOIN",
      "timestamp":"2023-05-22 03:06:34+03:00",
      "note":null,
      "sourceAmountGross":"0.5000000",
      "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "networkFeeAmount":"0.0002010",
      "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "targetAmountNet":"0.4997990",
      "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "blockchainTransactions":[],
      "targetAccount":{
         "network":"BITCOIN",
         "label":"Bitcoin (bc1qj)",
         "fields":{
            "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
         },
         "fieldConfig":[
            {
               "key":"address",
               "label":"Bitcoin Address",
               "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
         ],
         "state":"ACTIVE",
         "timestamp":"2023-05-21T21:00:26+00:00",
         "beneficiaryId":null
      },
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.transfer{}`	object	An object containing transfer information.	false
`.id`	string(12)	Unique identifier of this transfer.	false
`.type`	string	The transfer type, i.e. `TRANSFER`	false
`.state`	string	The transfer state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.origin`	string	Indicates how the transfer was initiated, either `UI` or `API`.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the transfer was created.	false
`.note`	note	An arbitrary text submitted when invoking `POST /transfer`.	true
`.sourceAmountGross`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account during the transfer.	false
`.sourceAsset`	string	The source asset. An asset id as given by `GET /assets`.	false
`.networkFeeAmount`	string	A numeric string indicating the total amount of `networkFeeAsset` used during the transfer.	false
`.networkFeeAsset`	string	The network fee asset. An asset id as given by `GET /assets`.	false
`.targetAmountNet`	string	A numeric string indicating the total amount of `targetAsset` received by the beneficiary.	false
`.targetAsset`	string	The target asset. An asset id as given by `GET /assets`.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction, i.e. `TRANSFER_PAYOUT`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.targetAccount`	object	An object specifying the target account for this transfer, as documented here: `GET /target-account`.	true
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this transfer (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/transferprotetto

Recupera i dettagli di un trasferimento specifico.

Richiesta

curl 'https://www.whalestack.com/api/v1/transfer?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `GET /transfers` or `POST /transfer`.	null	mandatory

Risposta di Successo application/json

{
   "transfer":{
      "id":"8947deb6a087",
      "type":"TRANSFER",
      "state":"COMPLETED",
      "origin":"API",
      "network":"BITCOIN",
      "timestamp":"2023-05-22 03:06:34+03:00",
      "note":null,
      "sourceAmountGross":"0.5000000",
      "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "networkFeeAmount":"0.0002010",
      "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "targetAmountNet":"0.4997990",
      "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "blockchainTransactions":[
         {
            "type":"TRANSFER_PAYOUT",
            "typeDescription":"Transaction transferring funds from Whalestack to target account.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2022-10-14T20:06:34+00:00",
            "tx":"9be365f2a550ef83cb0bdab6a606e9a892a896e69a44393e177b7537872d4688",
            "amount":"0.5000000",
            "amountAssetCode":"BTC"
         },
         {
            "type":"TRANSFER_PAYOUT",
            "typeDescription":"Transaction transferring funds from Whalestack to target account.",
            "network":"BITCOIN",
            "networkName":"Bitcoin",
            "timestamp":"2022-10-14T20:06:39+00:00",
            "tx":"f0ddcd0cc9f989c75ce5141f5b85a81d762fb7a8754243e6de977cfa91dd7cb6",
            "amount":"0.4997990",
            "amountAssetCode":"BTC"
         }
      ],
      "targetAccount":{
         "network":"BITCOIN",
         "label":"Bitcoin (bc1qj)",
         "fields":{
            "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
         },
         "fieldConfig":[
            {
               "key":"address",
               "label":"Bitcoin Address",
               "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
         ],
         "state":"ACTIVE",
         "timestamp":"2023-05-21T21:00:26+00:00",
         "beneficiaryId":null
      },
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.transfer{}`	object	An object containing transfer information.	false
`.id`	string(12)	Unique identifier of this transfer.	false
`.type`	string	The transfer type, i.e. `TRANSFER`	false
`.state`	string	The transfer state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.origin`	string	Indicates how the transfer was initiated, either `UI` or `API`.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the transfer was created.	false
`.note`	note	An arbitrary text submitted when invoking `POST /transfer`.	true
`.sourceAmountGross`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account during the transfer.	false
`.sourceAsset`	string	The source asset. An asset id as given by `GET /assets`.	false
`.networkFeeAmount`	string	A numeric string indicating the total amount of `networkFeeAsset` used during the transfer.	false
`.networkFeeAsset`	string	The network fee asset. An asset id as given by `GET /assets`.	false
`.targetAmountNet`	string	A numeric string indicating the total amount of `targetAsset` received by the beneficiary.	false
`.targetAsset`	string	The target asset. An asset id as given by `GET /assets`.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction, i.e. `TRANSFER_PAYOUT`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.targetAccount`	object	An object specifying the target account for this transfer, as documented here: `GET /target-account`.	true
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this transfer (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/transfersprotetto

Recupera una lista dei tuoi trasferimenti (in ordine decrescente, dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/transfers?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of transfer objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":1,
   "limit":10,
   "offset":0,
   "transfers":[
      {
         "transfer":{
            "id":"8947deb6a087",
            "type":"TRANSFER",
            "state":"COMPLETED",
            "origin":"API",
            "network":"BITCOIN",
            "timestamp":"2023-05-22 03:06:34+03:00",
            "note":null,
            "sourceAmountGross":"0.5000000",
            "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
            "networkFeeAmount":"0.0002010",
            "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
            "targetAmountNet":"0.4997990",
            "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
            "blockchainTransactions":[
               {
                  "type":"TRANSFER_PAYOUT",
                  "typeDescription":"Transaction transferring funds from Whalestack to target account.",
                  "network":"STELLAR",
                  "networkName":"Stellar",
                  "timestamp":"2022-10-14T20:06:34+00:00",
                  "tx":"9be365f2a550ef83cb0bdab6a606e9a892a896e69a44393e177b7537872d4688",
                  "amount":"0.5000000",
                  "amountAssetCode":"BTC"
               },
               {
                  "type":"TRANSFER_PAYOUT",
                  "typeDescription":"Transaction transferring funds from Whalestack to target account.",
                  "network":"BITCOIN",
                  "networkName":"Bitcoin",
                  "timestamp":"2022-10-14T20:06:39+00:00",
                  "tx":"f0ddcd0cc9f989c75ce5141f5b85a81d762fb7a8754243e6de977cfa91dd7cb6",
                  "amount":"0.4997990",
                  "amountAssetCode":"BTC"
               }
            ],
            "targetAccount":{
               "network":"BITCOIN",
               "label":"Bitcoin (bc1qj)",
               "fields":{
                  "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
               },
               "fieldConfig":[
                  {
                     "key":"address",
                     "label":"Bitcoin Address",
                     "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
                  }
               ],
               "state":"ACTIVE",
               "timestamp":"2023-05-21T21:00:26+00:00",
               "beneficiaryId":null
            },
            "webhook":"https://www.your-server.com/path/to/webhook"
         }
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of transfers initiated in this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.transfers[]`	array	A list of transfer objects.	false
`.id`	string(12)	Unique identifier of this transfer.	false
`.type`	string	The transfer type, i.e. `TRANSFER`	false
`.state`	string	The transfer state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.origin`	string	Indicates how the transfer was initiated, either `UI` or `API`.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the transfer was created.	false
`.note`	note	An arbitrary text submitted when invoking `POST /transfer`.	true
`.sourceAmountGross`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account during the transfer.	false
`.sourceAsset`	string	The source asset. An asset id as given by `GET /assets`.	false
`.networkFeeAmount`	string	A numeric string indicating the total amount of `networkFeeAsset` used during the transfer.	false
`.networkFeeAsset`	string	The network fee asset. An asset id as given by `GET /assets`.	false
`.targetAmountNet`	string	A numeric string indicating the total amount of `targetAsset` received by the beneficiary.	false
`.targetAsset`	string	The target asset. An asset id as given by `GET /assets`.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction, i.e. `TRANSFER_PAYOUT`.	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.network`	string	The network id as given by `GET /networks`. Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on Whalestack.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.targetAccount`	object	An object specifying the target account for this transfer, as documented here: `GET /target-account`.	true
`.webhook`	string	The webhook URL on your server to which Whalestack posts callback notifications during events related to this transfer (as specified in webhook concepts).	true

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/pingPubblico

Invia una richiesta di ping all'API. Questo endpoint è adatto per testare la connettività di rete con l'API di Whalestack.

Richiesta

curl 'https://www.whalestack.com/api/v1/ping'

Risposta di Successo application/json

{
    "success":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates the request was processed successfully.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/address-validationprotetto

Valida le chiavi pubbliche (indirizzi o account) sulle blockchain supportate. Può essere utilizzato come un endpoint di utilità per convalidare l'input dell'utente nella tua applicazione.

Richiesta

curl 'https://www.whalestack.com/api/v1/address-validation?network=BITCOIN&address=bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`, `STELLAR`, `ETHEREUM`, or `LITECOIN`.	null	mandatory
`address`	string	An address or account public key corresponding to the selected network.	null	mandatory

Risposta di Successo application/json

{
    "valid":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`valid`	boolean	Indicates whether the given address or account public key is valid.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/exchange-rateprotetto

Questo endpoint restituisce il tasso di cambio attuale tra due asset per una determinata quantità, tenendo conto della liquidità applicabile e della profondità del libro degli ordini. Questo endpoint può essere utilizzato per calcolare il tasso di cambio provvisorio durante il processo di checkout o degli swap su Whalestack.

Per interrogare il tasso di cambio medio globale tra due valute arbitrarie, utilizzare invece il punto finale GET /exchange-rate-global.

Richiesta

curl 'https://www.whalestack.com/api/v1/exchange-rate?sourceAsset=USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN&targetAsset=BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT&amount=5000'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`sourceAsset`	string	A source asset id as given by `GET /assets`.	null	mandatory
`targetAsset`	string	A target asset id as given by `GET /assets`.	null	mandatory
`amount`	numeric	The source amount in `send-amount` queries or the target amount in `receive-amount` queries (see `switch`).	null	mandatory
`switch`	string	Set to `send-amount` to indicate that you want to query the tentative amount of targetAsset you will receive for sending a given amount of sourceAsset. Set to `receive-amount` to indicate that you want to query the tentative amount of sourceAsset you will have to send to receive a given amount of targetAsset.	send-amount	mandatory

Risposta di Successo application/json

{
    "sourceAsset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
    "sourceAmount": "5000",
    "targetAsset": "BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
    "targetAmount": "0.1622371",
    "pair": "BTC/USD",
    "exchangeRate": "1:30819.0913175",
    "deviation": "0.182",
    "switch": "send-amount"
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`sourceAsset`	string	The given source asset.	false
`sourceAmount`	string	The given source amount for send-amount lookups, or the calculated source amount in receive-amount lookups.	false
`targetAsset`	string	The given target asset.	false
`targetAmount`	string	The given target amount for receive-amount lookups, or the calculated target amount in send-amount lookups.	false
`pair`	string	The currency pair. Base currency followed by the quote currency.	false
`exchangeRate`	string	A numeric string indicating the tentative exchange rate for the given assets and amount.	false
`deviation`	string	A numeric string indicating how much the given exchange rate deviates from the global average exchange rate in percentage points. A negative value indicates that the exchange rate is better than the global average and a positive value indicates that the exchange rate is worse than the global average.	false
`switch`	string	The given `send-amount` or `receive-amount` setting.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/exchange-rate-globalprotetto

Fornisce il tasso di cambio medio globale tra due valute arbitrarie. Questo endpoint è puramente informativo e non riflette i tassi di cambio disponibili su Whalestack. Per interrogare i tassi di cambio utilizzati dalla piattaforma Whalestack, utilizzare il punto finale GET /exchange-rate.

Richiesta

curl 'https://www.whalestack.com/api/v1/exchange-rate-global?baseCurrency=CHF&quoteCurrency=EUR'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`baseCurrency`	string	The ISO code of the base currency. See below for a list of supported currencies.	null	mandatory
`quoteCurrency`	string	The ISO code of the quote (counter) currency. See below for a list of supported currencies.	null	mandatory
`timestamp`	string	A timestamp in the format `YYYY-MM-DD` (2019-01-01 or later). Defaults to the current time.	null	optional

Supported Currencies

Asset Code	Nome	Categoria
`AED`	Emirati Dirham	FIAT
`ARS`	Argentine Peso	FIAT
`AUD`	Australian Dollar	FIAT
`BDT`	Bangladeshi Taka	FIAT
`BHD`	Bahraini Dinar	FIAT
`BMD`	Bermudian Dollar	FIAT
`BRL`	Brazilian Real	FIAT
`BTC`	Bitcoin	CRYPTO
`CAD`	Canadian Dollar	FIAT
`CHF`	Swiss Franc	FIAT
`CLP`	Chilean Peso	FIAT
`CNY`	Chinese Yuan	FIAT
`CZK`	Czech Koruna	FIAT
`DKK`	Danish Krone	FIAT
`ETH`	Ether	CRYPTO
`EUR`	Euro	FIAT
`GBP`	British Pound	FIAT
`HKD`	Hong Kong Dollar	FIAT
`HUF`	Hungarian Forint	FIAT
`IDR`	Indonesian Rupiah	FIAT
`ILS`	Israeli Shekel	FIAT
`INR`	Indian Rupee	FIAT
`JPY`	Japanese Yen	FIAT
`KRW`	Korean Won	FIAT
`KWD`	Kuwaiti Dinar	FIAT
`LKR`	Sri Lankan Rupee	FIAT
`LTC`	Litecoin	CRYPTO
`MMK`	Myanmar Kyat	FIAT
`MXN`	Mexican Peso	FIAT
`MYR`	Malaysian Ringgit	FIAT
`NGN`	Nigerian Naira	FIAT
`NOK`	Norwegian Krone	FIAT
`NZD`	New Zealand Dollar	FIAT
`PHP`	Philippine Peso	FIAT
`PKR`	Pakistani Rupee	FIAT
`PLN`	Polish Zloty	FIAT
`RUB`	Russian Ruble	FIAT
`SAR`	Saudi Arabian Riyal	FIAT
`SAT`	Satoshi	CRYPTO
`SEK`	Swedish Krona	FIAT
`SGD`	Singapore Dollar	FIAT
`THB`	Thai Baht	FIAT
`TRY`	Turkish Lira	FIAT
`TWD`	Taiwan Dollar	FIAT
`UAH`	Ukrainian Hryvnia	FIAT
`USD`	US Dollar	FIAT
`VEF`	Venezuelan Bolivar	FIAT
`VND`	Vietnamese Dong	FIAT
`XLM`	Stellar Lumens	CRYPTO
`XRP`	XRP	CRYPTO
`ZAR`	South African Rand	FIAT

Risposta di Successo application/json

{
    "baseCurrency": "CHF",
    "quoteCurrency": "EUR",
    "pair": "CHF/EUR",
    "exchangeRate": "0.9339042",
    "timestamp": "2021-09-04T21:29:10+00:00"
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`baseCurrency`	string	The base currency as given in the API request.	false
`quoteCurrency`	string	The quote (counter) currency as given in the API request.	false
`pair`	string	The currency pair used for this exchange. Base currency followed by the quote (counter) currency.	false
`exchangeRate`	numeric	The exchange rate at the given timestamp.	false
`timestamp`	string	W3C formatted timestamp at which the exchange rate was calculated.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/timePubblico

Fornisce un timestamp Unix con l'orario corrente del server Whalestack. Utilizza questo endpoint quando generi la firma Digest-Auth per l'autenticazione se percepisci un disallineamento temporale tra il tuo server e il server Whalestack.

Richiesta

curl 'https://www.whalestack.com/api/v1/time'

Risposta di Successo application/json

{
    "time":1525898643
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`time`	integer	Unix timestamp with Whalestack server time.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/auth-testprotetto

Un buon punto di partenza per testare la tua implementazione di Basic-Auth o Digest-Auth per l'autenticazione API. L'esempio sottostante dimostra una richiesta Digest-Auth.

Richiesta

curl 'https://www.whalestack.com/api/v1/auth-test' \
-H "X-Digest-Key: YOUR_API_KEY" \
-H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
-H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Intestazioni Richiesta

Chiave	Categoria	Descrizione
`X-Digest-Key`	string	Your Whalestack API Key
`X-Digest-Signature`	string	Unique Digest-Auth signature (see authentication)
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`).

Risposta di Successo application/json

{
    "success":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates the request was processed successfully.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/languagesprotetto

Fornisce una lista di lingue supportate da POST /checkout/hosted e POST /checkout.

Richiesta

curl 'https://www.whalestack.com/api/v1/languages'

Risposta di Successo application/json

{
   "languages":[
      {
         "name":"English",
         "languageCode":"en",
         "countryCode":"EN",
         "locale":"en_US"
      },
      {
         "name":"Português",
         "languageCode":"pt",
         "countryCode":"PT",
         "locale":"pt_PT"
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.languages[]`	array	A list of supported languages.	false
`.name`	string	Name of the language.	false
`.languageCode`	string	ISO-639 language code.	false
`.countryCode`	string	ISO-3166 country code.	false
`.locale`	string	Code of the locale.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/customersprotetto

Recupera un elenco di clienti (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/customers?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of customer objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":1,
   "limit":"250",
   "offset":"0",
   "customers":[
      {
         "id":"fd4f47a50c7f",
         "email":"john@doe.com",
         "firstname":"John",
         "lastname":"Doe",
         "name":"John Doe",
         "company":"ACME Inc.",
         "adr1":"810 Beach St",
         "adr2":"Finance Dept",
         "zip":"CA 94133",
         "city":"San Francisco",
         "countrycode":"US",
         "country":"United States",
         "phonenumber":"+14156226819",
         "taxid":"US1234567890",
         "note":"Always pays on time. Never late.",
         "meta":{
            "reference":123
         },
         "inserttime":"2018-12-10T16:16:18+00:00",
         "updatetime":"2018-12-11T17:34:09+00:00",
         "invoiceable":true
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of customers in existence for this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.customers[]`	array	A list of customer objects.	false
`.id`	string(12)	Unique identifier.	false
`.email`	string	The customer's email address.	false
`.firstname`	string	The customer's first name.	true
`.lastname`	string	The customer's last name.	true
`.name`	string	The customer's first name and last name conveniently concatenated into a single attribute.	true
`.company`	string	The customer's company name.	true
`.adr1`	string	The customer's first address line.	true
`.adr2`	string	The customer's second address line.	true
`.zip`	string	The customer's zip code.	true
`.city`	string	The customer's city.	true
`.countrycode`	string(2)	The customer's country in two character ISO format.	true
`.country`	string	The customer's country in plain English.	true
`.phonenumber`	string	The customer's phone number in international standard format (leading plus).	true
`.taxid`	string	The customer's tax id.	true
`.note`	string	An arbitrary note associated with the customer.	true
`.meta`	string	An arbitrary JSON object associated with the customer.	true
`.inserttime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the customer was created.	true
`.updatetime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated.	true
`.invoiceable`	boolean	Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, `adr1`, `zip`, `city`, `countrycode` and either `firstname` and `lastname` or `company`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/customerprotetto

Crea un oggetto cliente, che può essere associato a check-out, pagamenti e fatture. Se un cliente con l'indirizzo email fornito esiste già, viene eseguito un aggiornamento.

I check-out associati a un cliente generano maggiori dettagli sulla transazione, facilitano la contabilità e possono generare automaticamente fatture sia per il cliente che per te.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/customer \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
   "customer":{
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Parametri della Richiesta (POST)

Fatture

Per abilitare la fatturazione per i clienti, è necessario fornire un nome o una società, oltre a un indirizzo completo con almeno adr1, zip, city e countrycode.

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`customer{}`	object	An object containing information about your customer.	false	mandatory
`.email`	string	The customer's email address. If a customer with the given email address already exists an update of below records is performed.	false	mandatory
`.firstname`	string	The customer's first name.	true	optional
`.lastname`	string	The customer's last name.	true	optional
`.company`	string	The customer's company name.	true	optional
`.adr1`	string	The customer's first address line. Must be provided alongside `zip`, `city`, and `countrycode`	true	optional
`.adr2`	string	The customer's second address line.	true	optional
`.zip`	string	The customer's zip code. Must be provided alongside `adr1`, `city`, and `countrycode`	true	optional
`.city`	string	The customer's city. Must be provided alongside `adr1`, `zip`, and `countrycode`	true	optional
`.countrycode`	string	The customer's country as two character ISO code. Must be provided alongside `adr1`, `zip`, and `city`	true	optional
`.phonenumber`	string	The customer's phone number.	true	optional
`.taxid`	string	The customer's tax id. Useful for accounting and invoicing purposes.	true	optional
`.note`	string	An arbitrary note associated with the customer.	true	optional
`.meta`	object	An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use.	true	optional

Risposta di Successo application/json

{
    "customerId":"fd4f47a50c7f"
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.customerId`	string(12)	Unique identifier of the new customer object. Store this persistently for later use.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/customerprotetto

Recupera i dettagli di un cliente specifico.

Richiesta

curl 'https://www.whalestack.com/api/v1/customer?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `POST /customer`.	null	mandatory

Risposta di Successo application/json

{
   "customer":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "name":"John Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "country":"United States",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      },
      "inserttime":"2018-12-10T16:16:18+00:00",
      "updatetime":"2018-12-11T17:34:09+00:00",
      "invoiceable":true
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.customer{}`	array	An object with details about the customer.	false
`.id`	string(12)	Unique identifier.	false
`.email`	string	The customer's email address.	false
`.firstname`	string	The customer's first name.	true
`.lastname`	string	The customer's last name.	true
`.name`	string	The customer's first name and last name conveniently concatenated into a single attribute.	true
`.company`	string	The customer's company name.	true
`.adr1`	string	The customer's first address line.	true
`.adr2`	string	The customer's second address line.	true
`.zip`	string	The customer's zip code.	true
`.city`	string	The customer's city.	true
`.countrycode`	string(2)	The customer's country in two character ISO format.	true
`.country`	string	The customer's country in plain English.	true
`.phonenumber`	string	The customer's phone number in international standard format (leading plus).	true
`.taxid`	string	The customer's tax id.	true
`.note`	string	An arbitrary note associated with the customer.	true
`.meta`	string	An arbitrary JSON object associated with the customer.	true
`.inserttime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the customer was created.	true
`.updatetime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated.	true
`.invoiceable`	boolean	Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, `adr1`, `zip`, `city`, `countrycode` and either `firstname` and `lastname` or `company`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

PUT/customerprotetto

Aggiorna un oggetto cliente esistente.

Tutte le caratteristiche, oltre a id e email, sono opzionali. Puoi inviare un oggetto cliente parziale includendo solo i campi che desideri aggiornare. Per annullare un attributo, imposta il suo valore su null.

Richiesta di esempio

curl -X PUT https://www.whalestack.com/api/v1/customer \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
   "customer":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Parametri della Richiesta (PUT)

PRO Tip

To make a customer invoiceable you need to provide a name or a company as well as a complete address with adr1, zip, city, and countrycode at a minimum.

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`customer{}`	object	The customer object to be included in the request.	false	mandatory
`.id`	string(12)	The customer's unique identifier as given by `POST /customer`.	false	mandatory
`.email`	string	The customer's email address.	false	optional
`.firstname`	string	The customer's first name.	true	optional
`.lastname`	string	The customer's last name.	true	optional
`.company`	string	The customer's company name.	true	optional
`.adr1`	string	The customer's first address line. Must be provided alongside `zip`, `city`, and `countrycode`	true	optional
`.adr2`	string	The customer's second address line.	true	optional
`.zip`	string	The customer's zip code. Must be provided alongside `adr1`, `city`, and `countrycode`	true	optional
`.city`	string	The customer's city. Must be provided alongside `adr1`, `zip`, and `countrycode`	true	optional
`.countrycode`	string	The customer's country as two character ISO code. Must be provided alongside `adr1`, `zip`, and `city`	true	optional
`.phonenumber`	string	The customer's phone number.	true	optional
`.taxid`	string	The customer's tax id. Useful for accounting and invoicing purposes.	true	optional
`.note`	string	An arbitrary note associated with the customer.	true	optional
`.meta`	object	An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use.	true	optional

Risposta di Successo application/json

{
    "success": true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates that the request was processed successfully	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/customerprotetto

Cancella un elemento cliente esistente.

Richiesta di esempio

curl -X DELETE https://www.whalestack.com/api/v1/customer \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
    "id":"fd4f47a50c7f"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `POST /customer`.	null	mandatory

Risposta di Successo application/json

{
    "success":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/beneficiaryprotetto

Crea un oggetto beneficiario, che può essere associato ai checkout, pagamenti e fatture. Se esiste già un beneficiario con l'indirizzo email fornito, viene eseguito un aggiornamento.

Richiesta di esempio

curl -X POST https://www.whalestack.com/api/v1/beneficiary \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
   "beneficiary":{
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Parametri della Richiesta (POST)

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`beneficiary{}`	object	An object containing information about your beneficiary.	false	mandatory
`.email`	string	The beneficiary's email address. If a beneficiary with the given email address already exists an update of below records is performed.	false	mandatory
`.firstname`	string	The beneficiary's first name.	true	optional
`.lastname`	string	The beneficiary's last name.	true	optional
`.company`	string	The beneficiary's company name.	true	optional
`.adr1`	string	The beneficiary's first address line. Must be provided alongside `zip`, `city`, and `countrycode`	true	optional
`.adr2`	string	The beneficiary's second address line.	true	optional
`.zip`	string	The beneficiary's zip code. Must be provided alongside `adr1`, `city`, and `countrycode`	true	optional
`.city`	string	The beneficiary's city. Must be provided alongside `adr1`, `zip`, and `countrycode`	true	optional
`.countrycode`	string	The beneficiary's country as two character ISO code. Must be provided alongside `adr1`, `zip`, and `city`	true	optional
`.phonenumber`	string	The beneficiary's phone number.	true	optional
`.taxid`	string	The beneficiary's tax id. Useful for accounting and invoicing purposes.	true	optional
`.note`	string	An arbitrary note associated with the beneficiary.	true	optional
`.meta`	object	An arbitrary JSON object associated with the beneficiary. Useful for storing additional reference information for later use.	true	optional

Risposta di Successo application/json

{
    "beneficiaryId":"fd4f47a50c7f"
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.beneficiaryId`	string(12)	Unique identifier of the new beneficiary object. Store this persistently for later use.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/beneficiaryprotetto

Recupera i dettagli di un beneficiario specifico.

Richiesta

curl 'https://www.whalestack.com/api/v1/beneficiary?id=xxx'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `POST /beneficiary`.	null	mandatory

Risposta di Successo application/json

{
   "beneficiary":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "name":"John Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "country":"United States",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      },
      "inserttime":"2018-12-10T16:16:18+00:00",
      "updatetime":"2018-12-11T17:34:09+00:00",
      "invoiceable":true
   }
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.beneficiary{}`	array	An object with details about the beneficiary.	false
`.id`	string(12)	Unique identifier.	false
`.email`	string	The beneficiary's email address.	false
`.firstname`	string	The beneficiary's first name.	true
`.lastname`	string	The beneficiary's last name.	true
`.name`	string	The beneficiary's first name and last name conveniently concatenated into a single attribute.	true
`.company`	string	The beneficiary's company name.	true
`.adr1`	string	The beneficiary's first address line.	true
`.adr2`	string	The beneficiary's second address line.	true
`.zip`	string	The beneficiary's zip code.	true
`.city`	string	The beneficiary's city.	true
`.countrycode`	string(2)	The beneficiary's country in two character ISO format.	true
`.country`	string	The beneficiary's country in plain English.	true
`.phonenumber`	string	The beneficiary's phone number in international standard format (leading plus).	true
`.taxid`	string	The beneficiary's tax id.	true
`.note`	string	An arbitrary note associated with the beneficiary.	true
`.meta`	string	An arbitrary JSON object associated with the beneficiary.	true
`.inserttime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the beneficiary was created.	true
`.updatetime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the beneficiary was last updated.	true
`.invoiceable`	boolean	Indicates whether this beneficiary can be invoiced. To qualify for invoices the following fields must be set, `adr1`, `zip`, `city`, `countrycode` and either `firstname` and `lastname` or `company`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

PUT/beneficiaryprotetto

Aggiorna un elemento beneficiario esistente.

Tutte le caratteristiche, oltre a id e email, sono opzionali. Puoi inviare un elemento beneficiario parziale includendo solo i campi che desideri aggiornare. Per annullare un dettaglio, imposta il suo valore su null.

Richiesta di esempio

curl -X PUT https://www.whalestack.com/api/v1/beneficiary \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
   "beneficiary":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Parametri della Richiesta (PUT)

Chiave	Categoria	Descrizione	Nullable	Obbligatorio
`beneficiary{}`	object	The beneficiary object to be included in the request.	false	mandatory
`.id`	string(12)	The beneficiary's unique identifier as given by `POST /beneficiary`.	false	mandatory
`.email`	string	The beneficiary's email address.	false	optional
`.firstname`	string	The beneficiary's first name.	true	optional
`.lastname`	string	The beneficiary's last name.	true	optional
`.company`	string	The beneficiary's company name.	true	optional
`.adr1`	string	The beneficiary's first address line. Must be provided alongside `zip`, `city`, and `countrycode`	true	optional
`.adr2`	string	The beneficiary's second address line.	true	optional
`.zip`	string	The beneficiary's zip code. Must be provided alongside `adr1`, `city`, and `countrycode`	true	optional
`.city`	string	The beneficiary's city. Must be provided alongside `adr1`, `zip`, and `countrycode`	true	optional
`.countrycode`	string	The beneficiary's country as two character ISO code. Must be provided alongside `adr1`, `zip`, and `city`	true	optional
`.phonenumber`	string	The beneficiary's phone number.	true	optional
`.taxid`	string	The beneficiary's tax id. Useful for accounting and invoicing purposes.	true	optional
`.note`	string	An arbitrary note associated with the beneficiary.	true	optional
`.meta`	object	An arbitrary JSON object associated with the beneficiary. Useful for storing additional reference information for later use.	true	optional

Risposta di Successo application/json

{
    "success": true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates that the request was processed successfully	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/beneficiaryprotetto

Cancella un elemento beneficiario esistente.

Richiesta di esempio

curl -X DELETE https://www.whalestack.com/api/v1/beneficiary \
     -d "@payload.json"

Dove payload.json è un elemento JSON.

Esempio di Payload

{
    "id":"fd4f47a50c7f"
}

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`id`	string(12)	Unique identifier as given by `POST /beneficiary`.	null	mandatory

Risposta di Successo application/json

{
    "success":true
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/beneficiariesprotetto

Recupera un elenco di beneficiari (in ordine decrescente dal più recente al più vecchio).

Richiesta

curl 'https://www.whalestack.com/api/v1/beneficiaries?limit=250&offset=0'

Parametri della Richiesta

Chiave	Categoria	Descrizione	Predefinito	Obbligatorio
`limit`	integer	Maximum number of beneficiary objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Risposta di Successo application/json

{
   "count":1,
   "limit":"250",
   "offset":"0",
   "beneficiaries":[
      {
         "id":"fd4f47a50c7f",
         "email":"john@doe.com",
         "firstname":"John",
         "lastname":"Doe",
         "name":"John Doe",
         "company":"ACME Inc.",
         "adr1":"810 Beach St",
         "adr2":"Finance Dept",
         "zip":"CA 94133",
         "city":"San Francisco",
         "countrycode":"US",
         "country":"United States",
         "phonenumber":"+14156226819",
         "taxid":"US1234567890",
         "note":"Always pays on time. Never late.",
         "meta":{
            "reference":123
         },
         "inserttime":"2018-12-10T16:16:18+00:00",
         "updatetime":"2018-12-11T17:34:09+00:00",
         "invoiceable":true
      }
   ]
}

Caratteristiche della Risposta di Successo

Nome	Categoria	Descrizione	Nullable
`.count`	integer	The total number of beneficiaries in existence for this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.beneficiaries[]`	array	A list of beneficiary objects.	false
`.id`	string(12)	Unique identifier.	false
`.email`	string	The beneficiary's email address.	false
`.firstname`	string	The beneficiary's first name.	true
`.lastname`	string	The beneficiary's last name.	true
`.name`	string	The beneficiary's first name and last name conveniently concatenated into a single attribute.	true
`.company`	string	The beneficiary's company name.	true
`.adr1`	string	The beneficiary's first address line.	true
`.adr2`	string	The beneficiary's second address line.	true
`.zip`	string	The beneficiary's zip code.	true
`.city`	string	The beneficiary's city.	true
`.countrycode`	string(2)	The beneficiary's country in two character ISO format.	true
`.country`	string	The beneficiary's country in plain English.	true
`.phonenumber`	string	The beneficiary's phone number in international standard format (leading plus).	true
`.taxid`	string	The beneficiary's tax id.	true
`.note`	string	An arbitrary note associated with the beneficiary.	true
`.meta`	string	An arbitrary JSON object associated with the beneficiary.	true
`.inserttime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the beneficiary was created.	true
`.updatetime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the beneficiary was last updated.	true
`.invoiceable`	boolean	Indicates whether this beneficiary can be invoiced. To qualify for invoices the following fields must be set, `adr1`, `zip`, `city`, `countrycode` and either `firstname` and `lastname` or `company`.	false

Risposta di Errore application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Parametri di Risposta dell'Errore

Nome	Categoria	Descrizione	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

Fondamenti di Webhooks

I webhook fungono come meccanismo per trasmettere informazioni al tuo server in tempo reale quando si verificano eventi specifici, come pagamenti riusciti o discrepanze, ad esempio sotto-pagamenti durante il checkout.

Per coloro che cercano di automatizzare i flussi di lavoro all'interno della loro applicazione, i webhook sono indispensabili. Essi facilitano procedure automatiche, consentendo azioni come la conferma di un checkout da parte del cliente o l'avvio della consegna di beni e servizi.

Definire l'URL del Webhook

Il tuo URL del webhook designata viene definita durante la tua chiamata API iniziale, che sia attraverso POST /checkout, POST /checkout/hosted, o POST /deposit-address. Sebbene tu possa impostare l'URL predefinito per i webhook nelle impostazioni API, ogni URL fornito durante le chiamate API avrà la precedenza. Una volta specificata un URL di webhook, il nostro sistema ti informa prontamente attraverso una richiesta HTTP POST per gli eventi pertinenti.

Comprendere gli Eventi del Webhook

Gli eventi del webhook vengono attivati in scenari come il completamento di un checkout riuscito (WEBHOOK checkout-completed) o anomalie come un pagamento insufficiente (WEBHOOK checkout-underpaid). Poiché continuiamo a migliorare la nostra piattaforma, resta sintonizzato per ulteriori eventi del webhook. Puoi esplorare un elenco completo degli eventi del webhook nel menu a sinistra.

Anatomia del Webhook

Immagina un webhook come una tradizionale richiesta HTTP POST che parte dalla nostra parte per raggiungere il tuo server. Questa richiesta comprende gli header HTTP, che possono aiutare ad autenticarne l'origine, insieme a un corpo HTTP che racchiude i dati principali, dettagliando il tipo di evento del webhook e i dati pertinenti.

Webhook Headers

POST / HTTP/1.1
User-Agent: Whalestack Webhook Engine 1.0.1
Host: www.merchant.com
Accept: */*
Content-Type: application/json
Connection: close
X-Webhook-Auth: 06b7ff792a30a172c51c163f666dd6908d85fdda78451b36de9f3f8e985412be
Content-Length: 532

Webhook Body

{
  "eventType": "CHECKOUT_COMPLETED",
  "data": {...}
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type. Different types have different payloads and you should implement a parser for each event type. Valid types are: `CHECKOUT_COMPLETED`, `CHECKOUT_UNDERPAID`, `UNDERPAID_ACCEPTED`, `DEPOSIT_PENDING`, `DEPOSIT_COMPLETED`, `SWAP_COMPLETED`, `SWAP_FAILED`, `TRANSFER_COMPLETED`, `TRANSFER_FAILED`.	false
`.data`	string	An object containing the payload associated with this event type.	false

Parsing Webhook Payloads

I payload del webhook differiscono tra i tipi di evento. Il tuo sistema dovrebbe ispezionare il campo eventType e implementare un parser per ciascun tipo di evento che desideri supportare.

Esempio: Analisi in base al tipo di evento (PHP)

$payload = json_decode(file_get_contents("php://input"), true);
$type = $payload['eventType'];
$data = $payload['data'];

switch($type) {
    case('CHECKOUT_COMPLETED'):
        // do something when a checkout was successfully completed (and your account is credited)
        break;
    case('CHECKOUT_UNDERPAID'):
        // do something when a checkout was underpaid (and your account is not credited yet)
        break;
    case('UNDERPAID_ACCEPTED'):
        // do something when an underpaid checkout was manually accepted (and your account is credited)
        break;
    case('DEPOSIT_PENDING'):
        // do something when a deposit was detected on chain but is still unconfirmed (and your account is not credited yet)
        break;
    case('DEPOSIT_COMPLETED'):
        // do something when a deposit completed (and your account is credited)
        break;
    case('SWAP_COMPLETED'):
        // do something when a swap completed (and funds in your account are exchanged)
        break;
    case('SWAP_FAILED'):
        // do something when a swap failed (and no funds are affected)
        break;
    case('TRANSFER_COMPLETED'):
        // do something when a transfer completed (and your account is debited)
        break;
    case('TRANSFER_FAILED'):
        // do something when a transfer failed (and no funds were affected)
        break;
    break;
}

Autenticazione Webhook

Aggiungi sicurezza aggiuntiva al tuo endpoint e previeni la falsificazione analizzando l'header X-Webhook-Auth e verificando il suo valore.

Verifica che la richiesta sia stata inviata dalla piattaforma Whalestack creando un hash hash('sha256', YOUR_API_SECRET . WEBHOOK_REQUEST_BODY) (dove . rappresenta la concatenazione) e confrontandolo con il valore dell'header X-Webhook-Auth.

Esempio: Controllo dell'Autenticazione (PHP)

$authHeader = $_SERVER['HTTP_X_WEBHOOK_AUTH'];
$payload = file_get_contents("php://input");

if ($authHeader != hash('sha256', $yourApiSecret . $payload)) {
    // this is not a valid webhook
}

Risposta ai Webhook

Rispondi con HTTP 200 OK. Il tuo server deve rispondere con un codice di stato 200 nella risposta HTTP dopo aver analizzato con successo e conservato il payload del webhook. Il nostro sistema continuerà a inviare richieste di webhook con intervalli crescenti fino a un massimo di 48 ore, finché non rileveremo un codice di stato 200. Se non riceviamo un codice di stato HTTP 200 per un periodo più lungo, il webhook scade e smette di tentare l'invio.

Ispezionare la Cronologia dei Webhook

Ispeziona i webhook inviati da Whalestack insieme alle risposte HTTP nella sezione registri dei webhook della piattaforma.

Questo può essere estremamente utile durante la fase di implementazione perché aiuta a individuare e risolvere problemi nelle richieste e risposte HTTP.

WEBHOOK EVENTcheckout-completed

Questo evento di webhook viene attivato quando un pagamento del cliente è stato completato con successo, il tuo portafoglio Whalestack è stato accreditato ed è sicuro spedire eventuali beni o servizi.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"CHECKOUT_COMPLETED",
   "data":{
      "checkout":{
         "id":"a2d963a87d70",
         "timestamp":"2023-05-29T17:36:30+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"117.8379738",
         "settlementAmountReceived":"117.8379738",
         "settlementAmountFeePaid":"0.0000000",
         "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "sourceAmountRequired":"0.0043193",
         "sourceAmountReceived":"0.0043193",
         "sourceNetwork":"BITCOIN",
         "sourceNetworkName":"Bitcoin",
         "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
         "blockchainTransactions":[
            {
               "type":"CHECKOUT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2023-05-29T17:55:52+00:00",
               "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_BRIDGE",
               "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"9e912d924d6a27ee858e011db14825f016f835249302f90b82237a9b9782bde0",
               "amount":"117.8379738",
               "amountAssetCode":"USDC",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "customerId":"bb657e88a23d",
               "currency":"EUR",
               "lineItems":[
                  {
                     "description":"Mobile Data Prepaid Credits",
                     "netAmount":"110.00000"
                  }
               ],
               "shippingCostItems":[
                  {
                     "description":"Instant Delivery",
                     "netAmount":0
                  }
               ],
               "taxItems":[
                  {
                     "name":"Hong Kong Sales Tax",
                     "percent":0
                  }
               ]
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "webhook":"https://www.my-server.com/api/?action=cq-webhook",
            "links":{
               "cancelUrl":"https://www.my-server.com/en/payments",
               "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
            }
         },
         "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`CHECKOUT_COMPLETED`).	false
`.data`	object	Contains an object of type `checkout`.	false
`.checkout`	object	An object of type `checkout` with a `COMPLETED` state as documented in `GET checkout`	false

WEBHOOK EVENTcheckout-underpaid

Questo evento di webhook viene attivato quando un pagamento del cliente è stato catturato ma l'importo del pagamento è inferiore a quanto previsto. In questa situazione, i fondi non sono stati accreditati sul tuo account e non dovresti ancora spedire eventuali beni o servizi.

I pagamenti non risolti sono elencati nel tuo pannello di controllo UI e contengono opzioni di azione, come l'emissione di un rimborso o l'accettazione del pagamento insufficiente emettendo uno sconto personalizzato.

Se si tratta di un checkout di tipo HOSTED e hai associato un cliente a questo checkout, il nostro sistema notifica automaticamente il cliente con istruzioni su come completare il checkout e pagare la differenza rimanente.

Se si tratta di un checkout di tipo SELF-HOSTED o non è stato associato a un cliente, dovresti notificare all'utente di inviare un altro pagamento che copra la differenza tra sourceAmountRequired e sourceAmountReceived. Il pagamento dovrebbe essere inviato allo stesso indirizzo di deposito originariamente associato a questo checkout.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"CHECKOUT_COMPLETED",
   "data":{
      "checkout":{
         "id":"a2d963a87d70",
         "timestamp":"2023-05-29T17:36:30+00:00",
         "state":"UNRESOLVED_UNDERPAID",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"117.8379738",
         "settlementAmountReceived":"0.0000000",
         "settlementAmountFeePaid":"0.0000000",
         "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "sourceAmountRequired":"0.0043193",
         "sourceAmountReceived":"0.0040000",
         "sourceNetwork":"BITCOIN",
         "sourceNetworkName":"Bitcoin",
         "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
         "blockchainTransactions":[
            {
               "type":"CHECKOUT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2023-05-29T17:55:52+00:00",
               "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_BRIDGE",
               "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
               "amount":"0.0040000",
               "amountAssetCode":"BTC",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "customerId":"bb657e88a23d",
               "currency":"EUR",
               "lineItems":[
                  {
                     "description":"Mobile Data Prepaid Credits",
                     "netAmount":"110.00000"
                  }
               ],
               "shippingCostItems":[
                  {
                     "description":"Instant Delivery",
                     "netAmount":0
                  }
               ],
               "taxItems":[
                  {
                     "name":"Hong Kong Sales Tax",
                     "percent":0
                  }
               ]
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "webhook":"https://www.my-server.com/api/?action=cq-webhook",
            "links":{
               "cancelUrl":"https://www.my-server.com/en/payments",
               "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
            }
         },
         "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`CHECKOUT_UNDERPAID`).	false
`.data`	object	Contains an object of type `checkout`.	false
`.checkout`	object	An object of type `checkout` with a `UNRESOLVED_UNDERPAID` state as documented in `GET checkout`	false

WEBHOOK EVENTunderpaid-accepted

Questo evento di webhook viene attivato quando accetti manualmente un pagamento insufficiente tramite l'interfaccia utente della piattaforma Whalestack o hai abilitato la liquidazione automatica dei pagamenti insufficienti nelle impostazioni del tuo account. In questi eventi, al tuo account viene accreditata una parte dell'importo originariamente richiesto per la liquidazione.

Il campo dell'informazione settlementAmountReceived fornisce l'importo esatto accreditato al tuo account. I campi sourceAmountRequired e sourceAmountReceived indicano di quanto è stato pagato in meno rispetto all'importo richiesto per il pagamento.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"UNDERPAID_ACCEPTED",
   "data":{
      "checkout":{
         "id":"a2d963a87d70",
         "timestamp":"2023-05-29T17:36:30+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"117.8379738",
         "settlementAmountReceived":"108.7364213",
         "settlementAmountFeePaid":"0.0000000",
         "sourceAssetId":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "sourceAmountRequired":"0.0043193",
         "sourceAmountReceived":"0.0040000",
         "sourceNetwork":"BITCOIN",
         "sourceNetworkName":"Bitcoin",
         "depositAddress":"3Qg8rR28fPZXMiEbM2QB9RjQfM1MjuN9f8",
         "blockchainTransactions":[
            {
               "type":"CHECKOUT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2023-05-29T17:55:52+00:00",
               "tx":"27a3e9425ef73e80a2c2d97886a0e1f88662df9358150f773f39cfef7cb39621",
               "amount":"0.0043193",
               "amountAssetCode":"BTC",
               "exception":null
            },
            {
               "type":"CHECKOUT_BRIDGE",
               "typeDescription":"Fund transfer from native blockchain to Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2023-05-29T17:56:03+00:00",
               "tx":"f016f835249302f90b82237a9b9782bde09e912d924d6a27ee858e011db14825",
               "amount":"0.0040000",
               "amountAssetCode":"BTC",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "customerId":"bb657e88a23d",
               "currency":"EUR",
               "lineItems":[
                  {
                     "description":"Mobile Data Prepaid Credits",
                     "netAmount":"110.00000"
                  }
               ],
               "shippingCostItems":[
                  {
                     "description":"Instant Delivery",
                     "netAmount":0
                  }
               ],
               "taxItems":[
                  {
                     "name":"Hong Kong Sales Tax",
                     "percent":0
                  }
               ]
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "webhook":"https://www.my-server.com/api/?action=cq-webhook",
            "links":{
               "cancelUrl":"https://www.my-server.com/en/payments",
               "returnUrl":"https://www.my-server.com/en/invoice/57abff04a03d"
            }
         },
         "hostedCheckoutUrl":"https://www.whalestack.com/en/checkout/a2d963a87d70"
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`UNDERPAID_ACCEPTED`).	false
`.data`	object	Contains an object of type `checkout`.	false
`.checkout`	object	An object of type `checkout` with a `COMPLETED` state as documented in `GET checkout`	false

WEBHOOK EVENTdeposit-pending

Questo evento di webhook viene attivato quando un deposito è stato rilevato sulla catena ma è ancora non confermato e il tuo account non è stato ancora accreditato. Sono necessarie da una a sei conferme sulla blockchain affinché un deposito raggiunga la finalità.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"DEPOSIT_PENDING",
   "data":{
      "deposit":{
         "id":"eb3729168fb2",
         "state":"PENDING_EXTERNAL",
         "timestamp":"2022-10-14T19:49:51+00:00",
         "network":"BITCOIN",
         "networkName":"Bitcoin",
         "depositAddress":"bc1q2acmt0h28k0n5zlazj2m8k3zwxaklzpcx0kf34",
         "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "currencyCode":"BTC",
         "amountGross":"7.1479281",
         "amountNet":"7.1479281",
         "amountFees":"0.0000000",
         "webhook":"https://www.your-server.com/path/to/webhook",
         "customerId":null,
         "blockchainTransactions":[
            {
               "type":"DEPOSIT_ORIGIN",
               "typeDescription":"Blockchain transaction on the source network.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            }
         ]
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`PENDING_EXTERNAL`).	false
`.data`	object	Contains an object of type `deposit`.	false
`.deposit`	object	An object of type `deposit` with a `PENDING_EXTERNAL` state as documented in `GET deposit`	false

WEBHOOK EVENTdeposit-completed

Questo evento di webhook viene attivato quando un deposito è stato completato con successo.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"DEPOSIT_COMPLETED",
   "data":{
      "deposit":{
         "id":"eb3729168fb2",
         "state":"COMPLETED",
         "timestamp":"2022-10-14T19:49:51+00:00",
         "network":"BITCOIN",
         "networkName":"Bitcoin",
         "depositAddress":"bc1q2acmt0h28k0n5zlazj2m8k3zwxaklzpcx0kf34",
         "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "currencyCode":"BTC",
         "amountGross":"7.1479281",
         "amountNet":"7.1479281",
         "amountFees":"0.0000000",
         "webhook":"https://www.your-server.com/path/to/webhook",
         "customerId":null,
         "blockchainTransactions":[
            {
               "type":"DEPOSIT_ORIGIN",
               "typeDescription":"Blockchain transaction on the source network.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            },
            {
               "type":"DEPOSIT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your Whalestack merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"24c69c410e48ab3f7dd264429ec090e954b3b8b3b9860a5dd6c130f2926e0857",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            }
         ]
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`DEPOSIT_COMPLETED`).	false
`.data`	object	Contains an object of type `deposit`.	false
`.deposit`	object	An object of type `deposit` with a `COMPLETED` state as documented in `GET deposit`	false

WEBHOOK EVENTswap-completed

Questo evento di webhook viene attivato quando uno scambio è stato completato con successo.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"SWAP_COMPLETED",
   "data":{
      "swap":{
         "id":"5074f4ee055d",
         "state":"COMPLETED",
         "type":"SOURCE_SPECIFIED",
         "origin":"API",
         "createTime":"2021-05-06T22:15:37+00:00",
         "completeTime":"2021-05-06T22:16:01+00:00",
         "expireTime":"2021-05-06T23:15:37+00:00",
         "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "sourceAmount":"100.0000000",
         "targetAssetId":"XLM:NATIVE",
         "targetAmount":"243.3928192",
         "blockchainTransactions":[
            {
               "type":"SWAP",
               "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2021-05-06T22:16:01+00:00",
               "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
               "amount":"243.3928192",
               "amountAssetCode":"XLM"
            }
         ]
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`SWAP_COMPLETED`).	false
`.data`	object	Contains an object of type `swap`.	false
`.swap`	object	An object of type `swap` with a `COMPLETED` state as documented in `GET swap`	false

WEBHOOK EVENTswap-failed

Questo evento di webhook viene attivato quando uno scambio fallisce (e non si verifica nessuna transazione che influisce sul saldo).

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"SWAP_FAILED",
   "data":{
      "swap":{
         "id":"5074f4ee055d",
         "state":"FAILED",
         "type":"SOURCE_SPECIFIED",
         "origin":"API",
         "createTime":"2021-05-06T22:15:37+00:00",
         "completeTime":"2021-05-06T22:16:01+00:00",
         "expireTime":"2021-05-06T23:15:37+00:00",
         "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "sourceAmount":"100.0000000",
         "targetAssetId":"XLM:NATIVE",
         "targetAmount":"243.3928192",
         "blockchainTransactions":[]
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`SWAP_FAILED`).	false
`.data`	object	Contains an object of type `swap`.	false
`.swap`	object	An object of type `swap` with a `FAILED` state as documented in `GET swap`	false

WEBHOOK EVENTtransfer-completed

Questo evento di webhook viene attivato quando un trasferimento è stato completato con successo.

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"TRANSFER_COMPLETED",
   "data":{
      "transfer":{
         "id":"8947deb6a087",
         "type":"TRANSFER",
         "state":"COMPLETED",
         "origin":"API",
         "network":"BITCOIN",
         "timestamp":"2023-05-22 03:06:34+03:00",
         "note":null,
         "sourceAmountGross":"0.5000000",
         "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "networkFeeAmount":"0.0002010",
         "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "targetAmountNet":"0.4997990",
         "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "blockchainTransactions":[
            {
               "type":"TRANSFER_PAYOUT",
               "typeDescription":"Transaction transferring funds from Whalestack to target account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2022-10-14T20:06:34+00:00",
               "tx":"9be365f2a550ef83cb0bdab6a606e9a892a896e69a44393e177b7537872d4688",
               "amount":"0.5000000",
               "amountAssetCode":"BTC"
            },
            {
               "type":"TRANSFER_PAYOUT",
               "typeDescription":"Transaction transferring funds from Whalestack to target account.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2022-10-14T20:06:39+00:00",
               "tx":"f0ddcd0cc9f989c75ce5141f5b85a81d762fb7a8754243e6de977cfa91dd7cb6",
               "amount":"0.4997990",
               "amountAssetCode":"BTC"
            }
         ],
         "targetAccount":{
            "network":"BITCOIN",
            "label":"Bitcoin (bc1qj)",
            "fields":{
               "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
            },
            "fieldConfig":[
               {
                  "key":"address",
                  "label":"Bitcoin Address",
                  "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
               }
            ],
            "state":"ACTIVE",
            "timestamp":"2023-05-21T21:00:26+00:00",
            "beneficiaryId":null
         },
         "webhook":"https://www.your-server.com/path/to/webhook"
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`TRANSFER_COMPLETED`).	false
`.data`	object	Contains an object of type `transfer`.	false
`.transfer`	object	An object of type `transfer` with a `COMPLETED` state as documented in `GET transfer`	false

WEBHOOK EVENTtransfer-failed

Questo evento di webhook viene attivato quando un trasferimento fallisce (e non si verifica alcuna transazione che influisce sul saldo).

Si prega di leggere riguardo ai concetti dei webhook per saperne di più su come lavorare con i webhook.

Webhook Body

{
   "eventType":"TRANSFER_FAILED",
   "data":{
      "transfer":{
         "id":"8947deb6a087",
         "type":"TRANSFER",
         "state":"FAILED",
         "origin":"API",
         "network":"BITCOIN",
         "timestamp":"2023-05-22 03:06:34+03:00",
         "note":null,
         "sourceAmountGross":"0.5000000",
         "sourceAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "networkFeeAmount":"0.0002010",
         "networkFeeAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "targetAmountNet":"0.4997990",
         "targetAsset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "blockchainTransactions":[

         ],
         "targetAccount":{
            "network":"BITCOIN",
            "label":"Bitcoin (bc1qj)",
            "fields":{
               "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
            },
            "fieldConfig":[
               {
                  "key":"address",
                  "label":"Bitcoin Address",
                  "description":"The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
               }
            ],
            "state":"ACTIVE",
            "timestamp":"2023-05-21T21:00:26+00:00",
            "beneficiaryId":null
         },
         "webhook":"https://www.your-server.com/path/to/webhook"
      }
   }
}

Informazioni Webhook Payload

Nome	Categoria	Descrizione	Nullable
`.eventType`	string	Indicates the webhook event type (`TRANSFER_FAILED`).	false
`.data`	object	Contains an object of type `transfer`.	false
`.transfer`	object	An object of type `transfer` with a `FAILED` state as documented in `GET transfer`	false

Inizia

Oggetti Principali

Portafogli

Checkouts

Depositi

Swaps

Trasferimenti

Account di Destinazione

Clienti

Beneficiari

Punti di Accesso Ausiliari

Webhooks

Utilizzo dell'API di Whalestack

Portafogli e Depositi

Checkouts

Swap e Trasferimenti

Rendicontazione Finanziaria Trasparente

Software Development Kit

PHP SDK ufficiale di Whalestack per PHP

Ruby SDK ufficiale di Whalestack per Ruby

NodeJS SDK ufficiale di Whalestack per NodeJS

Integrazioni per il Commercio Elettronico

Magento Estensione ufficiale di Whalestack per Magento

PrestaShop Estensione ufficiale di Whalestack per PrestaShop

Shopify Integrazione ufficiale di Whalestack per Shopify

WooCommerce Plugin ufficiale di Whalestack per WooCommerce

WordPress Plugin ufficiale di Whalestack per WordPress

Adobe Commerce Estensione ufficiale di Whalestack per Adobe Commerce

Creazione dei Checkout

Opzione 1: Checkout con Hosting Autonomo

Opzione 2: Pagine di Checkout

Richiesta di esempio

Esempio di Addebito (essenziale)

Esempio di Risposta (application/json)

Ricezione Pagamenti

Esempio di Webhook (application/json)

Collegamento del Brand tramite Whalestack

Personalizzazione del Branding

Configurazione del Dominio Web Personalizzato

Garantita l'Autenticazione Sicura

Protezione delle Credenziali API

Digest-Auth: La Nostra Scelta Consigliata

Richiesta

Intestazioni Richiesta

Componenti di X-Digest-Signature

Esempio di Codice (PHP)

Esempio di Codice (Ruby)

Esempio di Codice (NodeJS)

Basic-Auth

Richiesta

Intestazioni Richiesta

Esempio di Codice

Inserimento in Lista Bianca degli Indirizzi IP

Software Development Kit (SDK)

PHP SDK ufficiale di Whalestack per PHP

Ruby SDK ufficiale di Whalestack per Ruby

NodeJS SDK ufficiale di Whalestack per NodeJS

GET/networksprotetto

Richiesta

Risposta di Successo application/json

Caratteristiche della Risposta di Successo

Risposta di Errore application/json

Parametri di Risposta dell'Errore

GET/assetsprotetto

Richiesta

Risposta di Successo application/json

Caratteristiche della Risposta di Successo

Risposta di Errore application/json

Parametri di Risposta dell'Errore

GET/currenciesprotetto

Richiesta

Risposta di Successo application/json

Caratteristiche della Risposta di Successo

Risposta di Errore application/json

Parametri di Risposta dell'Errore

POST /checkout protetto

Richiesta di esempio

Esempio di Payload (Minimo)

Spiegazione della Configurazione del Payload Sopra

Esempio di Payload (Completo)

PHP
SDK ufficiale di Whalestack per PHP

Ruby
SDK ufficiale di Whalestack per Ruby

NodeJS
SDK ufficiale di Whalestack per NodeJS

Magento
Estensione ufficiale di Whalestack per Magento

PrestaShop
Estensione ufficiale di Whalestack per PrestaShop

Shopify
Integrazione ufficiale di Whalestack per Shopify

WooCommerce
Plugin ufficiale di Whalestack per WooCommerce

WordPress
Plugin ufficiale di Whalestack per WordPress

Adobe Commerce
Estensione ufficiale di Whalestack per Adobe Commerce

PHP
SDK ufficiale di Whalestack per PHP

Ruby
SDK ufficiale di Whalestack per Ruby

NodeJS
SDK ufficiale di Whalestack per NodeJS

Esempio di Risposta (come fornito da `POST /checkout`)