Início

Usando a API da Whalestack Construindo Checkouts Autenticação SDKs PHP NodeJS Ruby Conexão de Marca

Objetos Centrais

GET /networks GET /assets GET /currencies

Carteiras

GET /wallet GET /wallets

Checkouts

POST /checkout/hosted POST /checkout POST /checkout/commit GET /checkout GET /checkouts

Depósitos

POST /deposit-address GET /deposit GET /deposits

Trocas

POST /swap POST /swap/commit GET /swap GET /swaps

Transferências

POST /transfer POST /transfer/commit GET /transfer GET /transfers

Contas Destino

POST /target-account GET /target-account GET /target-accounts DELETE /target-account

Clientes

POST /customer GET /customer PUT /customer DELETE /customer GET /customers

Beneficiários

POST /beneficiary GET /beneficiary PUT /beneficiary DELETE /beneficiary GET /beneficiaries

Pontos de Ajuda

GET /ping GET /time GET /auth-test GET /languages GET /exchange-rate GET /exchange-rate-global GET /address-validation

Webhooks

Conceitos de Webhook

Eventos de Checkout

EVENT checkout-completed EVENT checkout-underpaid EVENT underpaid-accepted

Eventos de Depósito

EVENT deposit-pending EVENT deposit-completed

Eventos de Troca

EVENT swap-completed EVENT swap-failed

Eventos de Transferência

EVENT transfer-completed EVENT transfer-failed

Usando a API da Whalestack

Desbloqueie pagamentos de criptomoedas rápidos, seguros e sem esforço com a API Whalestack. Uma vez que você tenha garantido sua API key após o registro, crie um checkout ou gere um endereço de depósito blockchain. Seja Bitcoin, Lightning, Litecoin, Stellar ou outra rede suportada, receber pagamentos é direto. Além disso, aproveite as vantagens do fiat on e off-ramping através do PIX.

Carteiras e Depósitos

Com a Whalestack, você recebe instantaneamente endereços de depósito dedicados para Bitcoin, Lightning, Litecoin, Stellar, PIX e mais. Comece a receber pagamentos blockchain logo após o cadastro. Use as endpoints GET /wallets e POST /deposit-address para buscar seus endereços blockchain e iniciar depósitos personalizados.

Checkouts

Os checkouts Whalestack agilizam os pagamentos dos clientes. Nós oferecemos uma experiência de usuário superior com checkouts hospedados totalmente personalizáveis. Se páginas de pagamento pré-construídas não são o seu estilo, utilize nossas APIs de checkout backend para controle total. Leia nossa introdução a building checkouts ou mergulhe diretamente nas endpoints POST /checkout ou POST /checkout/hosted.

Trocas e Transferências

Após receber fundos, seja através de checkouts ou depósitos personalizados, você pode utilizá-los imediatamente. Troque-os entre diferentes ativos ou mova-os para uma conta bancária ou de blockchain (embora sugerimos o encaminhamento para armazenamento frio para máxima segurança). Use as endpoints POST /swap e POST /transfer para explorar trocas e transferências.

Relatórios Financeiros Transparentes

Sem mais complicações sobre trilhas complexas de pagamento em blockchain. A Whalestack agrega todas as suas transações na seção Relatórios Financeiros de sua conta. Você até pode vincular transações a contrapartes específicas como clientes POST /customer ou beneficiários POST /beneficiary. Fornecemos relatórios em CSV, gráficos visuais e análises perspicazes, simplificando seus processos contábeis.

Kits de Desenvolvimento de Software

A API Whalestack integra-se perfeitamente com clientes REST em todas as linguagens de programação. Para um início rápido, nós criamos SDKs para PHP, Ruby e NodeJS. Explore esses recursos em nossa página GitHub.

PHP Logo

PHP
SDK Oficial Whalestack para PHP


Ruby Logo

Ruby
SDK Oficial Whalestack para Ruby


NodeJS Logo

NodeJS
SDK Oficial Whalestack para NodeJS

Integrações de E-Commerce

Estamos dedicados a refinar regularmente nosso conjunto de ferramentas de e-commerce, garantindo integrações perfeitas com a Whalestack. Nossa suíte de bibliotecas, plugins e extensões é feita para garantir uma integração rápida e sem complicações. Descubra a variedade de integrações de e-commerce prontas para implantação abaixo.

Magento

Magento
Extensão Oficial Whalestack para Magento


PrestaShop

PrestaShop
Extensão Oficial Whalestack para PrestaShop


Shopify

Shopify
Integração Oficial Whalestack para Shopify


WooCommerce

WooCommerce
Plugin Oficial Whalestack para WooCommerce


WordPress

WordPress
Plugin Oficial Whalestack para WordPress


Adobe Commerce

Adobe Commerce
Extensão Oficial Whalestack para Adobe Commerce

Construindo Checkouts

Comece escolhendo entre nossa experiência de página de checkout totalmente personalizável e a opção auto-hospedada, onde você utiliza nossas APIs de backend para manter o controle total sobre a jornada de pagamento.

Opção 1: Checkouts Auto-Hospedados

Entrega o processo de checkout sob a sua marca dentro da sua aplicação web. Opte por checkouts de API de backend auto-hospedados para garantir uma experiência contínua para os usuários, mantendo-os dentro do ecossistema da sua aplicação. Inicie pagamentos com etiqueta branca via endpoint da API POST /checkout.

Opção 2: Páginas de Checkout

Nossos checkouts hospedados e totalmente personalizáveis apresentam a maneira mais direta de receber pagamentos na Whalestack. O endpoint da API POST /checkout/hosted fornece um link de pagamento. Seja direcionando usuários para whalestack.com ou para o seu próprio domínio através do Brand Connect, o processo permanece perfeito. Após obter a URL de checkout, direcione seu cliente para a página hospedada, e eles estarão prontos para pagar. Nós notificamos você via webhooks, e-mails ou consulta API sobre fundos recebidos.

Abaixo, encontre um guia passo a passo para criar um checkout hospedado dinâmico:

Exemplo de Solicitação

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

A autenticação Authentication é fornecida via cabeçalhos HTTP e charge.json é um objeto JSON:

Exemplo de Cobrança (mínimo)

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

O exemplo acima cria uma cobrança para um item com preço de 169.99 R$. Você pode configurar mais detalhes, como custos de envio, descontos, impostos, o cliente relacionado, bem como seu ativo de liquidação preferido conforme documentado here.

Exemplo de Resposta (application/json)

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

A API retorna um identificador único junto com uma URL de checkout hospedado, que você exibe de volta ao seu cliente para que ele possa completar o pagamento. Uma vez que os fundos são obtidos, nós notificamos você via WEBHOOK checkout-completed.

Recebendo Pagamentos

Transações de criptomoeda diferem de pagamentos com cartão de crédito tradicionais. Em vez de comerciantes retirarem fundos usando detalhes de cartão de crédito, criptomoeda opera em um modelo push. Isso exige que o cliente ativamente inicie e envie o pagamento ao comerciante.

Ao iniciar um checkout, a Whalestack rastreia vigorosamente a blockchain escolhida para pagamentos recebidos. Há uma janela de 60 minutos para a conclusão da transação. Se o pagamento não for finalizado dentro deste período, ele é marcado como expirado. No entanto, pagamentos atrasados que eventualmente são concluídos ainda são aceitos.

Após receber com sucesso o pagamento, seu saldo é atualizado, seu painel reflete as mudanças e um callback de webhook é enviado para o seu sistema. Isso garante o processamento automatizado do pedido em seu sistema pelo mecanismo WEBHOOK checkout-completed.

Exemplo de Webhook (application/json)

POST /webhook/path/on/your/server 
{
   "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"
      }
   }
}

O webhook contém um objeto JSON no corpo da solicitação HTTP e informa você sobre pagamentos recebidos e seus atributos conforme especificado em WEBHOOK checkout-completed. No exemplo acima, o cliente pagou em BTC e o comerciante foi creditado em USDC.

Brand Connect da Whalestack

O Brand Connect da Whalestack infunde sua experiência de checkout com a identidade única da sua marca. Seja o logo da sua empresa, imagens temáticas, ou uma interface de usuário adaptada à estética da sua marca, o Brand Connect garante que suas páginas de checkout pareçam uma extensão orgânica da nossa plataforma. Escolha entre hospedar em whalestack.com ou implantar em seu próprio domínio com nossa configuração simples de contêiner docker.

O Brand Connect é a solução ideal para prestadores de serviços de pagamento que desejam utilizar o sistema completo de checkout da Whalestack enquanto mantêm sua própria apresentação de marca distintiva. Isso inclui o manuseio hábil de nuances de transação como pagamentos em excesso, insuficientes, reembolsos ou transações múltiplas. Mesmo que você não seja um prestador de serviços, mas apenas deseje uma experiência visual consistente para sua loja online, o Brand Connect é a escolha certa.

Personalização da Marca

Configurar a aparência personalizada do seu checkout é simples com nossa interface Brand Connect nas configurações da sua conta Aqui está como personalizar a sua marca:

  1. Ative o Brand Connect nas suas configurações de conta.
  2. Prossiga para modificar as Informações da Marca, Imagens, Fontes e Cores dentro das configurações.

Uma vez configurado, suas páginas de checkout se mesclarão perfeitamente com a sua marca - logo, favicon, imagens de cripto personalizadas, preferências de fonte e esquemas de cores. Ao inspecionar seu checkout, você notará uma integração impecável sem nenhum sinal da Whalestack como o provedor de serviços subjacente.

Configuração de Domínio Web Personalizado

Por padrão, o Brand Connect funciona no domínio whalestack.com. No entanto, se você aspira a uma imersão de marca mais profunda, pode direcionar seus checkouts através do seu próprio domínio web. Isso é ideal para aqueles que fornecem serviços de pagamento e desejam integrar de forma transparente as capacidades da Whalestack enquanto mantêm sua própria aura de marca distinta.

Esta integração é alcançada via Brand Connect docker container (GitHub). Ao colocá-lo em sua configuração de hospedagem e fazer algumas alterações de DNS, você habilita um fluxo de checkout inteiro em sincronia com sua identidade de marca. Ative o Brand Connect em suas {tagOpen}configurações de conta{tagClose}

  1. Ative o Brand Connect nas suas configurações de conta.
  2. Prossiga para modificar as Informações de Marca, Imagens, Fontes e Cores dentro das configurações.
  3. Designe seu domínio web personalizado para checkouts e obtenha sua WS_BRANDING_KEY (após completar os passos acima)
  4. Implemente o Brand Connect docker container juntamente com seu certificado SSL
  5. Redirecione o DNS do seu domínio web para o endereço IP que hospeda o contêiner docker

E voilà! Suas páginas de checkout da Whalestack agora são uma parte integral do seu domínio, refletindo a essência única da sua marca. Aprofunde-se no GitHub.

GPT Garantindo Autenticação Segura

A API da Whalestack exige principalmente autenticação. Distintamente, os endpoints da API são classificados como públicos () ou protegidos (). Para acessar um endpoint protegido, autentique sua solicitação usando sua chave API via método Basic-Auth ou método mais seguro Digest-Auth. Para verificar facilmente seu método de autenticação, utilize o endpoint GET /auth-test.

Garantindo a Segurança de Suas Credenciais de API

Vá até as Configurações de API para recuperar sua chave API e senha. Aqui, você também pode configurar sua estratégia de autenticação preferida e aumentar a segurança habilitando a "lista de permissões de IP". Em caso de qualquer suspeita sobre a segurança do seu segredo de API, você tem a capacidade de recriá-lo a partir destas configurações.

Digest-Auth: Nossa Escolha Recomendada

Nós recomendamos o método Digest-Auth ao acessar endpoints protegidos da API Whalestack. Cabeçalhos essenciais para cada solicitação incluem X-Digest-Key, X-Digest-Signature e X-Digest-Timestamp, todos detalhados nas seções subsequentes.

Solicitação

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

Cabeçalhos de Solicitação

Chave Tipo Descrição
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

A X-Digest-Signature é gerada criando um hash HMAC SHA256 usando seu Segredo de API como o segredo compartilhado no resumo da mensagem. O payload criptografado é composto da seguinte forma:
ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY, onde . representa a concatenação de strings.

Componentes da X-Digest-Signature

Componente Tipo Descrição
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.

PHP Logo Exemplo de Código (PHP)

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);

Ruby Logo Exemplo de Código (Ruby)

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)

Ruby Logo Exemplo de Código (NodeJS)

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');

Veja estes exemplos se você não tem certeza de como criar uma assinatura HMAC SHA256 na sua linguagem de programação.

Basic-Auth

Você pode optar por usar um cabeçalho de autenticação básica, que é mais fácil de implementar (já que é um hash estático sobre sua chave API e segredo) mas menos seguro que Digest-Auth. Recomendamos usar Basic-Auth apenas durante o desenvolvimento ou em ambientes de teste.

Solicitação

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

Cabeçalhos de Solicitação

Chave Tipo Descrição
X-Basic string SHA256 hash over YOUR_API_KEY:YOUR_API_SECRET mandatory

Exemplo de Código

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

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

Lista de Permissões de Endereços IP

Use as Configurações da API para configurar se sua conta de API pode ser acessada de qualquer endereço IP ou somente de endereços IP na lista de permissões. A lista de permissões de endereços IP é recomendada para ambientes de produção, pois aumenta dramaticamente a segurança. Endereços de retirada só podem ser acessados de endereços IP na lista de permissões.

Kits de Desenvolvimento de Software (SDKs)

Nossos Kits de Desenvolvimento de Software para PHP, Ruby e NodeJS estão aqui para ajudar você a integrar rapidamente com a API de Pagamentos Whalestack sem complicações.

Abaixo está uma lista de SDKs atualmente disponíveis em nosso GitHub..

PHP Logo

PHP
SDK Oficial Whalestack para 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  );
Visualizar no GitHub
Ruby Logo

Ruby
SDK Oficial Whalestack para 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  )
Visualizar no GitHub
NodeJS Logo

NodeJS
SDK Oficial Whalestack para NodeJS 

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

GET/networksprotegido

Retorna uma lista de redes blockchain e bancárias suportadas pela plataforma Whalestack.

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
   "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"
         ]
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/assetsprotegido

Retorna uma lista de ativos suportados pela plataforma Whalestack.

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
   "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"
         ]
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/currenciesprotegido

Retorna uma lista de moedas suportadas pela plataforma Whalestack.

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
    "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
        }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST /checkout protegido

Inicie o processo de pagamento auto-hospedado inicializando um checkout. Este endpoint permite que você crie um checkout diretamente em seu servidor, permitindo total autonomia sobre sua UI ou API. Para uma alternativa que automatiza uma página de checkout na infraestrutura da Whalestack, considere POST /checkout/hosted. Se você é novo em iniciar um processo de checkout, recomendamos começar por here.

Para interagir com este endpoint, você precisará fornecer um objeto de cobrança, que engloba itens de linha, adições potenciais como taxas de envio ou descontos e impostos aplicáveis. Para um toque mais personalizado e geração de fatura, vincule a cobrança a um cliente específico. Você também obtém a alavancagem para ditar a moeda de liquidação, que pode divergir da denominação da cobrança ou da moeda escolhida pelo seu cliente. Uma interação bem-sucedida com este endpoint fornece uma gama de métodos de pagamento e seus respectivos valores, todos configurados para serem apresentados ao seu cliente.

Seus clientes podem então escolher a modalidade de pagamento preferida (por exemplo, Bitcoin). Após a seleção, envie uma nova solicitação com a blockchain escolhida e seu respectivo ID de checkout para POST /checkout/commit, que retorna instruções de depósito para serem exibidas ao seu cliente. Assim que o compromisso de checkout estiver estabelecido, o sistema da Whalestack varre diligentemente a blockchain por pagamentos recebidos, mantendo você informado sobre o progresso dos pagamentos via WEBHOOK checkout-completed.

Observe que os checkouts declaram uma intenção de pagamento e são projetados para uso único. Sempre inicie um novo checkout para cada transação.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Carga (Mínimo)

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

Explicação da Configuração da Carga Acima

Acima está a configuração mínima necessária para iniciar um checkout. A cobrança é denominada em EUR e tem exatamente um item a um custo de 169,99 EUR. O valor do pagamento cobrado pelo seu cliente na criptomoeda de escolha dele é calculado contra o valor total da cobrança especificado aqui.

Exemplo de Carga (Completo)

application/json 
{
   "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"
   }
}

Parâmetros de Requisição (POST)

Vinculando Clientes

Forneça um charge.customerId conforme fornecido por POST /customer para vincular automaticamente o checkout a um cliente. Vincular pagamentos com clientes ajuda com sua contabilidade, fornece mais detalhes em seu histórico de transações e permite que você envie faturas automatizadas e notificações de status de pagamento.

Fórmula do Montante Total

O cálculo do montante total é executado usando a seguinte fórmula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
   "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"
         }
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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.

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/checkout/commitprotegido

Este endpoint serve como uma continuação vital do processo de checkout, que foi iniciado através de POST /checkout. Se você é novo em iniciar um processo de checkout, recomendamos começar por here.

Ao fazer uma solicitação a este endpoint, você precisará fornecer um checkoutId e uma network, conforme obtido pela solicitação POST /checkout. Se a rede selecionada suporta múltiplos ativos, você também precisará incluir um asset (se omitido, o ativo padrão da rede é utilizado). Após uma solicitação bem-sucedida, você receberá informações de depósito, que devem ser apresentadas ao seu cliente para facilitar o processo de pagamento.

Uma vez que este endpoint é invocado, a Whalestack inicia o monitoramento em tempo real da rede blockchain relevante. Quando o pagamento é concluído, seu servidor é automaticamente notificado via WEBHOOK checkout-completed. Alternativamente, você pode verificar periodicamente o status do pagamento usando GET /checkout após exibir as informações de depósito ao seu cliente.

No passo anterior, POST /checkout forneceu-lhe uma lista de métodos de pagamento disponíveis, conforme ilustrado abaixo:

Exemplo de Resposta (conforme dado pelo POST /checkout)

200 OK 
{
   "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"
         }
      }
   ]
}

Como pré-requisito para invocar este endpoint, você deve ter recebido uma resposta como a do endpoint POST /checkout. Contém uma lista de métodos de pagamento, que você exibe ao seu cliente para que ele escolha. Após a seleção, você invoca POST /checkout/commit (este endpoint) com a rede de depósito selecionada (depositNetwork), relatedAssetId (se necessário) e checkoutId para receber as informações de depósito para o seu cliente realizar o pagamento.

Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload (Bitcoin)

application/json 
{
  "checkoutId":"6d55626309d6",
  "network":"BITCOIN"
}

Exemplo de Payload (EURC, Stellar)

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

Exemplo de Payload (XLM, Stellar)

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
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

Exemplo de Resposta de Sucesso (Bitcoin) application/json

200 OK 
{
    "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"
}

Exemplo de Resposta de Sucesso (XLM) application/json

200 OK 
{
   "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"
}

Forneça ao seu cliente o address bem como o memo e memoType quando a rede STELLAR for selecionada para pagamento. Isso é importante para que a Whalestack mapeie o pagamento para sua conta de comerciante.

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Próximos Passos

Exiba as informações de depósito de volta ao seu cliente. Enquanto isso, a Whalestack começa a monitorar o endereço blockchain fornecido na resposta da API e notifica você automaticamente via WEBHOOK checkout-completed quando um pagamento é concluído. Alternativamente, você pode verificar periodicamente o status do pagamento utilizando GET /checkout para atualizações de pagamento.

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST /checkout/hosted protegido

Este endpoint gera e entrega uma URL única que aponta para uma página de checkout, totalmente gerenciada nos servidores da Whalestack. Para uma abordagem mais direta onde você supervisiona a UI e o fluxo de checkout, considere o endpoint POST /checkout em vez disso. Se você é novo em iniciar um processo de checkout, recomendamos começar por here.

Ao invocar este endpoint, seu servidor fornece parâmetros que abrangem especificações de pagamento, itens de linha de impostos opcionais, dados do cliente e a moeda desejada de liquidação. Em troca, seu servidor obtém uma URL de checkout, pronta para ser exibida para sua clientela.

Ao acessar esta URL, os clientes encontram uma página de checkout amigável ao usuário hospedada na infraestrutura da Whalestack. Esta página interativa apresenta todas as informações essenciais para facilitar o processo de pagamento. Uma vez que a transação é concluída, nosso sistema informa instantaneamente sua aplicação através do WEBHOOK checkout-completed. Para aqueles que prezam pela proatividade, o endpoint GET /checkout permite que você monitore continuamente o status do pagamento.

Projetado para adaptabilidade, os checkouts hospedados da Whalestack ajustam-se perfeitamente tanto para displays móveis quanto para telas de desktop expansivas. Ajuste a aparência deles para ressoar com a estética da sua marca usando Brand Connect.

Lembre-se, cada URL de checkout hospedado é distinta e de uso único. Garanta a geração de uma nova URL para cada nova transação.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Carga (Mínimo)

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

Explicação da Configuração da Carga Acima

Acima está a configuração mínima necessária para iniciar um checkout. A cobrança é denominada em EUR e tem exatamente um item a um custo de 169,99 EUR. O valor do pagamento cobrado pelo seu cliente na criptomoeda de escolha dele é calculado contra o valor total da cobrança especificado aqui.

Exemplo de Carga (Completo)

application/json 
{
   "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"
   }
}

Parâmetros de Requisição (POST)

Vinculando Clientes

Forneça um charge.customerId conforme fornecido por POST /customer para vincular automaticamente o checkout a um cliente. Vincular pagamentos com clientes ajuda com sua contabilidade, fornece mais detalhes em seu histórico de transações e permite que você envie faturas automatizadas e notificações de status de pagamento.

Fórmula do Montante Total

O cálculo do montante total é executado usando a seguinte fórmula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
   "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"
         }
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/checkoutprotegido

Recupera informações sobre um determinado checkout.

A resposta deste endpoint contém informações sobre pagamentos blockchain associados a este checkout, seu estado geral de conclusão, bem como informações contextuais adicionais.

Este endpoint é adequado para a sondagem de eventos de pagamento associados ao checkout fornecido. Uma alternativa mais eficiente é ouvir eventos de pagamento usando WEBHOOK checkout-completed no seu servidor.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by POST /checkout or POST /checkout/hosted. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/checkoutsprotegido

Recupera uma lista de objetos de checkout (em ordem decrescente do mais novo para o mais antigo).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of checkout objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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"
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/walletsprotegido

Retorna uma lista de objetos de carteira contendo informações sobre o ativo associado, saldo, redes disponíveis e endereços de depósito (se disponíveis).

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
   "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"
            }
         }
      ]
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/walletprotegido

Retorna um objeto de carteira contendo informações sobre o ativo associado, saldo, redes disponíveis e endereços de depósito (se disponíveis).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
asset string An asset identifier as given by GET /assets or GET /wallets. - mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
            }
         }
      ]
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/deposit-addressprotegido

Cria seu endereço de depósito em blockchain ou banco para uma rede e ativo específicos.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplos de Cargas de Mensagens

A carga da transação depende da rede de origem de onde você está depositando os fundos. Selecione abaixo.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA
application/json 
{
    "network": "BITCOIN"
}
application/json 
{
    "network": "LIGHTNING",
    "amount": "5000"
}
application/json 
{
    "network": "LITECOIN"
}
application/json 
{
    "network": "STELLAR",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
application/json 
{
    "network": "SWIFT",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
application/json 
{
    "network": "SEPA",
    "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Parâmetros de Requisição (POST)

A carga da transação depende da rede de origem de onde você está depositando os fundos. Selecione abaixo.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, 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
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, LIGHTNING false mandatory
.amount string Valor da fatura em 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
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, 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
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, STELLAR false mandatory
.asset string O identificador do ativo de depósito na rede Stellar. Consiste no código do ativo e no emissor. 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
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, SWIFT false mandatory
.asset string Especifica o ativo creditado na sua conta quando seu depósito for concluído. Referências USDC ou EURC. Um identificador de ativo conforme fornecido por 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
Chave Tipo Descrição Anulável Obrigatório
.network string Um identificador da rede de destino conforme fornecido por GET /networks, ou seja, SEPA false mandatory
.asset string Especifica o ativo creditado na sua conta quando seu depósito for concluído. Referências USDC ou EURC. Um identificador de ativo conforme fornecido por 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

Resposta de Sucesso application/json

A carga da transação depende da rede de origem de onde você está depositando os fundos. Selecione abaixo.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA
200 OK 
{
    "depositAddress": {
        "network": "BITCOIN",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew24"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Endereu00e7o Bitcoin",
                "description": "O endereu00e7o Bitcoin. Pode estar em qualquer formato, isto u00e9, SegWit nativo (bech32), SegWit (P2SH) ou legado (P2PKH)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "100.0000000"
    }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 O endereço Bitcoin. Pode estar em qualquer formato, isto é, SegWit nativo (bech32), SegWit (P2SH) ou legado (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
200 OK 
{
    "depositAddress": {
        "network": "LIGHTNING",
        "fields": {
            "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9c...",
            "amount": "5000"
        },
        "fieldConfig": [
            {
                "key": "invoice",
                "label": "Fatura Lightning",
                "description": "Uma fatura Lightning BOLT 11 com valor codificado."
            },
            {
                "key": "amount",
                "label": "Valor da Fatura",
                "description": "Valor da fatura em SAT."
            }
        ],
        "minAmount": "4000.0000000",
        "maxAmount": "2498545.0000000"
    }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 Uma fatura Lightning BOLT 11 com valor codificado. false
.amount string Valor da fatura em 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
200 OK 
{
    "depositAddress": {
        "network": "LITECOIN",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdf"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Endereu00e7o Litecoin",
                "description": "O endereu00e7o Litecoin. Pode estar em qualquer formato, isto u00e9, SegWit nativo (bech32), SegWit (P2SH) ou legado (P2PKH)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "10000.0000000"
    }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 O endereço Litecoin. Pode estar em qualquer formato, isto é, SegWit nativo (bech32), SegWit (P2SH) ou legado (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
200 OK 
{
    "depositAddress": {
        "network": "STELLAR",
        "fields": {
            "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU7",
            "memo": "sda3195ad7ed65",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "asset",
                "label": "Ativo Stellar",
                "description": "O identificador do ativo de depu00f3sito na rede Stellar. Consiste no cu00f3digo do ativo e no emissor."
            },
            {
                "key": "account",
                "label": "Conta Stellar",
                "description": "A conta de depu00f3sito na rede Stellar. Comeu00e7ando com G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "O memo obrigatu00f3rio a ser incluu00eddo na transau00e7u00e3o. Nu00e3o omita isso ou seu depu00f3sito seru00e1 atrasado."
            },
            {
                "key": "memoType",
                "label": "Tipo de Memo",
                "description": "O tipo de memo obrigatu00f3rio a ser incluu00eddo na transau00e7u00e3o."
            }
        ],
        "minAmount": "0.0000001",
        "maxAmount": "1000000"
    }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 O identificador do ativo de depósito na rede Stellar. Consiste no código do ativo e no emissor. false
.account string A conta de depósito na rede Stellar. Começando com G. false
.memo string O memo obrigatório a ser incluído na transação. Não omita isso ou seu depósito será atrasado. false
.memoType string O tipo de memo obrigatório a ser incluído na transação. 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
200 OK 
{
    "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": "Referu00eancia de Pagamento",
                "description": "Adicione esta referu00eancia ao seu depu00f3sito SWIFT. u00c9 necessu00e1rio para mapear o depu00f3sito para a sua conta mercantil. Nu00e3o omita isso ou seu depu00f3sito seru00e1 atrasado."
            },
            {
                "key": "beneficiary",
                "label": "Beneficiu00e1rio",
                "description": "O nome da conta do beneficiu00e1rio."
            },
            {
                "key": "account",
                "label": "Nu00famero da Conta Bancu00e1ria",
                "description": "O nu00famero da conta bancu00e1ria."
            },
            {
                "key": "swiftCode",
                "label": "SWIFT/BIC",
                "description": "O cu00f3digo SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou instituiu00e7u00e3o financeira."
            },
            {
                "key": "bankName",
                "label": "Nome do Banco",
                "description": "O nome do banco beneficiu00e1rio."
            },
            {
                "key": "bankAddress",
                "label": "Endereu00e7o do Banco",
                "description": "O endereu00e7o do banco beneficiu00e1rio."
            },
            {
                "key": "correspondentBankSwift",
                "label": "SWIFT/BIC do Banco Correspondente",
                "description": "Forneu00e7a este cu00f3digo SWIFT/BIC se o seu banco solicitar um banco intermediu00e1rio ou correspondente."
            },
            {
                "key": "correspondentBankName",
                "label": "Nome do Banco Correspondente",
                "description": "O nome do banco correspondente. Forneu00e7a isso se o seu banco solicitar um banco intermediu00e1rio ou correspondente."
            },
            {
                "key": "correspondentBankAddress",
                "label": "Endereu00e7o do Banco Correspondente",
                "description": "O endereu00e7o do banco correspondente. Forneu00e7a isso se o seu banco solicitar um banco intermediu00e1rio ou correspondente."
            }
        ],
        "minAmount": 250,
        "maxAmount": 500000
    }
}

Enviar Pagamento em Reais

Envie pagamento denominado em Reais.

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 Adicione esta referência ao seu depósito SWIFT. É necessário para mapear o depósito para a sua conta mercantil. Não omita isso ou seu depósito será atrasado. false
.beneficiary string O nome da conta do beneficiário. false
.account string O número da conta bancária. false
.swiftCode string O código SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou instituição financeira. false
.bankName string O nome do banco beneficiário. false
.bankAddress string O endereço do banco beneficiário. false
.correspondentBankSwift string Forneça este código SWIFT/BIC se o seu banco solicitar um banco intermediário ou correspondente. false
.correspondentBankName string O nome do banco correspondente. Forneça isso se o seu banco solicitar um banco intermediário ou correspondente. false
.correspondentBankAddress string O endereço do banco correspondente. Forneça isso se o seu banco solicitar um banco intermediário ou correspondente. 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
200 OK 
{
    "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": "Referu00eancia de Pagamento",
                "description": "Adicione esta referu00eancia ao seu depu00f3sito PIX. u00c9 necessu00e1rio para mapear o depu00f3sito para sua conta mercantil. Nu00e3o omita isto ou seu depu00f3sito seru00e1 atrasado."
            },
            {
                "key": "beneficiary",
                "label": "Beneficiu00e1rio",
                "description": "O nome da conta do beneficiu00e1rio."
            },
            {
                "key": "iban",
                "label": "IBAN",
                "description": "O nu00famero da conta bancu00e1ria internacional (IBAN)."
            },
            {
                "key": "swiftCode",
                "label": "SWIFT/BIC",
                "description": "O cu00f3digo SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou instituiu00e7u00e3o financeira."
            },
            {
                "key": "bankName",
                "label": "Nome do Banco",
                "description": "O nome do banco beneficiu00e1rio."
            },
            {
                "key": "bankAddress",
                "label": "Endereu00e7o do Banco",
                "description": "O endereu00e7o do banco beneficiu00e1rio."
            }
        ],
        "minAmount": 50,
        "maxAmount": 500000
    }
}

Enviar Pagamento em Reais

Envie pagamento denominado em Reais.

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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 Adicione esta referência ao seu depósito PIX. É necessário para mapear o depósito para sua conta mercantil. Não omita isto ou seu depósito será atrasado. false
.beneficiary string O nome da conta do beneficiário. false
.iban string O número da conta bancária internacional (IBAN). false
.swiftCode string O código SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou instituição financeira. false
.bankName string O nome do banco beneficiário. false
.bankAddress string O endereço do banco beneficiário. 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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/depositprotegido

Recupera detalhes de um depósito específico.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Blockchain transaction id of your deposit or unique identifier as given by GET /deposits. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/depositsprotegido

Recupera uma lista de seus depósitos (em ordem decrescente do mais novo para o mais antigo).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of deposit objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/swapprotegido

Inicia uma troca de ativos na sua conta e retorna um objeto de troca em um estado PENDING_API_COMMIT. O objeto contém uma cotação com os valores de origem e de destino. Para aceitar a cotação, confirme a troca invocando POST /swap/commit.

Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo: Trocar 100 USDC por BTC

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

Exemplo: Trocar BTC por 100 XLM

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

Parâmetros de Requisição (POST)

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/swap/commitprotegido

Confirma e executa uma troca no estado PENDING_API_COMMIT previamente iniciada com POST /swap.

Retorna um objeto de troca em um estado não final PROCESSING. Um estado final de COMPLETED ou FAILED é enviado por webhook e também pode ser verificado usando GET /swap.

Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
  "swapId":"12d72c3c8145"
}

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
swapId string(12) Unique identifier as given by POST /swap. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/swapprotegido

Recupera detalhes de uma troca específica.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by GET /swaps or POST /swap. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/swapsprotegido

Recupera uma lista das suas trocas (em ordem decrescente da mais nova para a mais antiga).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of swap objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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"
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/target-accountsprotegido

Retorna uma lista de objetos de conta alvo (em ordem decrescente da mais nova para a mais antiga).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of target account objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

O payload de cada objeto depende da sua rede de destino. Selecione abaixo.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX
200 OK 
{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "BITCOIN",
            "label": "Ledger Nano on Bitcoin",
            "fields": {
                "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "Endere\u00e7o Bitcoin",
                    "description": "O endere\u00e7o Bitcoin. Pode estar em qualquer formato, isto \u00e9, SegWit nativo (bech32), SegWit (P2SH) ou legado (P2PKH)."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}
200 OK 
{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "ETHEREUM",
            "label": "Ledger Nano on Ethereum",
            "fields": {
                "account": "0xA2Bf179E09C503262E418FC72261837726f68F36"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Conta Ethereum",
                    "description": "Uma conta na rede Ethereum. Come\u00e7ando com 0x."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}
200 OK 
{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "LITECOIN",
            "label": "Ledger Nano on Litecoin",
            "fields": {
                "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "Endere\u00e7o Litecoin",
                    "description": "O endere\u00e7o Litecoin. Pode estar em qualquer formato, isto \u00e9, SegWit nativo (bech32), SegWit (P2SH) ou legado (P2PKH)."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}
200 OK 
{
    "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": "Conta Stellar",
                    "description": "Uma conta na rede Stellar. Come\u00e7a com G."
                },
                {
                    "key": "memo",
                    "label": "Memo",
                    "description": "Identifica o destinat\u00e1rio ou o prop\u00f3sito do pagamento. Uma mensagem \u00e9 frequentemente exigida por bolsas e carteiras. Certifique-se de fornecer uma se necess\u00e1rio."
                },
                {
                    "key": "memoType",
                    "label": "Tipo de Memo",
                    "description": "Uma bandeira adicional identificando o tipo de mensagem. Geralmente \u00e9 'texto'."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}
200 OK 
{
    "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": "N\u00famero da Conta Banc\u00e1ria",
                    "description": "O n\u00famero da conta banc\u00e1ria."
                },
                {
                    "key": "bic",
                    "label": "SWIFT\/BIC",
                    "description": "O c\u00f3digo SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou institui\u00e7\u00e3o financeira."
                },
                {
                    "key": "bankName",
                    "label": "Nome do Banco",
                    "description": "O nome do banco benefici\u00e1rio."
                },
                {
                    "key": "bankAddress",
                    "label": "Endere\u00e7o do Banco",
                    "description": "O endere\u00e7o do banco benefici\u00e1rio."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}
200 OK 
{
    "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": "O n\u00famero da conta banc\u00e1ria internacional (IBAN)."
                },
                {
                    "key": "bic",
                    "label": "SWIFT\/BIC",
                    "description": "O c\u00f3digo SWIFT ou BIC de 8-11 caracteres que identifica seu banco ou institui\u00e7\u00e3o financeira."
                },
                {
                    "key": "bankName",
                    "label": "Nome do Banco",
                    "description": "O nome do banco benefici\u00e1rio."
                },
                {
                    "key": "bankAddress",
                    "label": "Endere\u00e7o do Banco",
                    "description": "O endere\u00e7o do banco benefici\u00e1rio."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}
200 OK 
{
    "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": "Chave PIX",
                    "description": "A chave PIX associada \u00e0 conta banc\u00e1ria do destinat\u00e1rio. Geralmente um n\u00famero de telefone, CPF, endere\u00e7o de e-mail ou chave aleat\u00f3ria."
                },
                {
                    "key": "taxId",
                    "label": "CPF\/CNPJ",
                    "description": "O identificador fiscal do destinat\u00e1rio. Formato CNPJ (00.000.000\/0000-00) para Pessoas Juridicas ou formato CPF (000.000.000-00) para Pessoas Fisicas."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/transferprotegido

Inicia uma transferência de fundos da sua carteira para o seu banco externo ou conta de blockchain. Retorna um objeto de transferência em estado PENDING_API_COMMIT. O objeto contém uma cotação com origem, destino e montantes das taxas de rede (se houver). Para aceitar a cotação, confirme a transferência invocando POST /transfer/commit.

Depende de chamadas anteriores ao POST /target-account para vincular contas externas para transferências.

Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo: Transferir 5.000 USDC para sua conta PIX (como R$)

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

Exemplo: Transferir BTC com um montante alvo líquido de 0,5 BTC

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

Exemplo: Transferência para uma fatura BOLT 11 Bitcoin Lightning

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

Exemplo: Transferir 5.000 USDC para uma conta Stellar

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

Exemplo: Transferir 5.000 USDC para uma conta Ethereum

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

Parâmetros de Requisição (POST)

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/transfer/commitprotegido

Efetua e executa uma transferência de fundos no estado PENDING_API_COMMIT previamente iniciada com POST /transfer.

Retorna um objeto de transferência em um estado não final PROCESSING. Um estado final de COMPLETED ou FAILED é enviado por webhook e também pode ser verificado usando GET /transfer.

Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
  "transferId":"12d72c3c8145"
}

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
transferId string(12) Unique identifier as given by POST /transfer. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/transferprotegido

Recupera detalhes de uma transferência específica.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by GET /transfers or POST /transfer. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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"
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/transfersprotegido

Recupera uma lista das suas transferências (em ordem decrescente, da mais recente para a mais antiga).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of transfer objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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"
         }
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/pingpúblico

Envia uma solicitação de ping para a API. Este endpoint é adequado para testar a conectividade de rede com a API da Whalestack.

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
    "success":true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates the request was processed successfully. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/address-validationprotegido

Valida chaves públicas (endereços ou contas) em blockchains suportadas. Pode ser usado como um endpoint de utilidade para validar entradas de usuários em sua aplicação.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
    "valid":true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
valid boolean Indicates whether the given address or account public key is valid. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/exchange-rateprotegido

Este endpoint retorna a taxa de câmbio atual entre dois ativos em uma determinada quantia, levando em conta a liquidez aplicável e a profundidade do livro de ofertas. Este endpoint pode ser usado para calcular a taxa de câmbio provisória durante checkouts ou trocas na Whalestack.

Para consultar a taxa de câmbio média global entre duas moedas arbitrárias, use o endpoint GET /exchange-rate-global em vez disso.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
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

Resposta de Sucesso application/json

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

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/exchange-rate-globalprotegido

Retorna a taxa de câmbio média global entre duas moedas arbitrárias. Este endpoint é puramente informativo e não reflete as taxas de câmbio disponíveis na Whalestack. Para consultar as taxas de câmbio usadas pela plataforma Whalestack, por favor, use o endpoint GET /exchange-rate em vez disso.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
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 Tipo
AEDEmirati DirhamFIAT
ARSArgentine PesoFIAT
AUDAustralian DollarFIAT
BDTBangladeshi TakaFIAT
BHDBahraini DinarFIAT
BMDBermudian DollarFIAT
BRLBrazilian RealFIAT
BTCBitcoinCRYPTO
CADCanadian DollarFIAT
CHFSwiss FrancFIAT
CLPChilean PesoFIAT
CNYChinese YuanFIAT
CZKCzech KorunaFIAT
DKKDanish KroneFIAT
ETHEtherCRYPTO
EUREuroFIAT
GBPBritish PoundFIAT
HKDHong Kong DollarFIAT
HUFHungarian ForintFIAT
IDRIndonesian RupiahFIAT
ILSIsraeli ShekelFIAT
INRIndian RupeeFIAT
JPYJapanese YenFIAT
KRWKorean WonFIAT
KWDKuwaiti DinarFIAT
LKRSri Lankan RupeeFIAT
LTCLitecoinCRYPTO
MMKMyanmar KyatFIAT
MXNMexican PesoFIAT
MYRMalaysian RinggitFIAT
NGNNigerian NairaFIAT
NOKNorwegian KroneFIAT
NZDNew Zealand DollarFIAT
PHPPhilippine PesoFIAT
PKRPakistani RupeeFIAT
PLNPolish ZlotyFIAT
RUBRussian RubleFIAT
SARSaudi Arabian RiyalFIAT
SATSatoshiCRYPTO
SEKSwedish KronaFIAT
SGDSingapore DollarFIAT
THBThai BahtFIAT
TRYTurkish LiraFIAT
TWDTaiwan DollarFIAT
UAHUkrainian HryvniaFIAT
USDUS DollarFIAT
VEFVenezuelan BolivarFIAT
VNDVietnamese DongFIAT
XLMStellar LumensCRYPTO
XRPXRPCRYPTO
ZARSouth African RandFIAT

Resposta de Sucesso application/json

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

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/timepúblico

Retorna um timestamp de data/hora Unix com o horário atual do servidor da Whalestack. Use este ponto de extremidade ao gerar a assinatura de Digest-Auth para autenticação se você sentir que o tempo entre o seu servidor e o servidor da Whalestack está desalinhado.

Solicitação

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

Resposta de Sucesso application/json

200 OK 
{
    "time":1525898643
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
time integer Unix timestamp with Whalestack server time. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/auth-testprotegido

Um bom ponto de partida para testar sua implementação de Basic-Auth ou Digest-Auth para API authentication. O exemplo abaixo demonstra uma requisição Digest-Auth.

Solicitação

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

Cabeçalhos de Solicitação

Chave Tipo Descrição
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).

Resposta de Sucesso application/json

200 OK 
{
    "success":true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates the request was processed successfully. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/languagesprotegido

Retorna uma lista de idiomas suportados por POST /checkout/hosted e POST /checkout.

Solicitação

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

Resposta de Sucesso application/json

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

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/customersprotegido

Recupera uma lista de clientes (em ordem decrescente do mais novo para o mais antigo).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of customer objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/customerprotegido

Cria um objeto de cliente, que pode ser associado a checkouts, pagamentos e faturas. Se um cliente com o endereço de e-mail fornecido já existe, uma atualização é realizada.

Checkouts associados a um cliente geram mais detalhes de transação, ajudam com sua contabilidade e podem gerar automaticamente faturas para seu cliente e para você mesmo.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
   "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
      }
   }
}

Parâmetros de Requisição (POST)

Faturas

Para habilitar a faturação de clientes, você precisa fornecer um nome ou uma empresa, bem como um endereço completo com adr1, zip, city e countrycode como mínimo.

Chave Tipo Descrição Anulável Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
    "customerId":"fd4f47a50c7f"
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.customerId string(12) Unique identifier of the new customer object. Store this persistently for later use. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/customerprotegido

Recupera detalhes de um cliente específico.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by POST /customer. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

PUT/customerprotegido

Atualiza um objeto de cliente existente.

Todos os atributos, exceto id e email são opcionais. Você pode submeter um objeto de cliente parcial incluindo apenas os campos que deseja atualizar. Para desconfigurar um atributo, defina seu valor como null.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
   "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
      }
   }
}

Parâmetros de Requisição (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.

Chave Tipo Descrição Anulável Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
    "success": true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates that the request was processed successfully false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

DELETE/customerprotegido

Exclui um objeto de cliente existente.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
    "id":"fd4f47a50c7f"
}

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by POST /customer. null mandatory

Resposta de Sucesso application/json

200 OK 
{
    "success":true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates that request was processed successfully. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

POST/beneficiaryprotegido

Cria um objeto beneficiário, que pode ser associado a checkouts, pagamentos e faturas. Se um beneficiário com o endereço de e-mail fornecido já existe, uma atualização é realizada.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
   "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
      }
   }
}

Parâmetros de Requisição (POST)

Chave Tipo Descrição Anulável Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
    "beneficiaryId":"fd4f47a50c7f"
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.beneficiaryId string(12) Unique identifier of the new beneficiary object. Store this persistently for later use. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/beneficiaryprotegido

Recupera detalhes de um beneficiário específico.

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by POST /beneficiary. null mandatory

Resposta de Sucesso application/json

200 OK 
{
   "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
   }
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

PUT/beneficiaryprotegido

Atualiza um objeto beneficiário existente.

Todos os atributos, exceto id e email são opcionais. Você pode enviar um objeto beneficiário parcial, incluindo apenas os campos que deseja atualizar. Para desfazer um atributo, defina seu valor para null.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
   "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
      }
   }
}

Parâmetros de Requisição (PUT)

Chave Tipo Descrição Anulável Obrigatório
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

Resposta de Sucesso application/json

200 OK 
{
    "success": true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates that the request was processed successfully false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

DELETE/beneficiaryprotegido

Exclui um objeto beneficiário existente.

Exemplo de Solicitação

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

Onde payload.json é um objeto JSON.

Exemplo de Payload

application/json 
{
    "id":"fd4f47a50c7f"
}

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
id string(12) Unique identifier as given by POST /beneficiary. null mandatory

Resposta de Sucesso application/json

200 OK 
{
    "success":true
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
success boolean Indicates that request was processed successfully. false

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

GET/beneficiariesprotegido

Recupera uma lista de beneficiários (em ordem decrescente do mais novo para o mais antigo).

Solicitação

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

Parâmetros de Requisição

Chave Tipo Descrição Padrão Obrigatório
limit integer Maximum number of beneficiary objects to be retrieved. 250 optional
offset integer Specifies the pagination offset. 0 optional

Resposta de Sucesso application/json

200 OK 
{
   "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
      }
   ]
}

Atributos da Resposta de Sucesso

Nome Tipo Descrição Anulável
.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

Resposta de Erro application/json

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

Parâmetros da Resposta de Erro

Nome Tipo Descrição Anulável
errors[] string[ ] A list of strings explaining the error. false

Conceitos de Webhook

Webhooks servem como um mecanismo para transmitir informações ao seu servidor em tempo real quando eventos específicos ocorrem, como pagamentos bem-sucedidos ou discrepâncias como subpagamentos durante o checkout.

Para aqueles que procuram automatizar fluxos de trabalho dentro de sua aplicação, webhooks são indispensáveis. Eles facilitam procedimentos automáticos, permitindo ações como confirmar um checkout de cliente ou iniciar a entrega de bens e serviços.

Definindo a URL do Webhook

Sua URL de webhook designada é definida durante sua chamada inicial de API, seja ela POST /checkout, POST /checkout/hosted, ou POST /deposit-address. Embora você possa definir URLs de webhook padrão em suas configurações de API, qualquer URL fornecida durante chamadas de API terá precedência. Ao especificar uma URL de webhook, nosso sistema informa prontamente através de um POST HTTP para eventos pertinentes.

Entendendo Eventos de Webhook

Eventos de webhook são ativados em cenários como a conclusão bem-sucedida de um checkout (WEBHOOK checkout-completed) ou anomalias como um subpagamento (WEBHOOK checkout-underpaid). À medida que continuamos aprimorando nossa plataforma, fique atento para mais eventos de webhook. Você pode explorar uma lista abrangente de eventos de webhook no menu à esquerda.

Desenho do Webhook

Visualize um webhook como uma solicitação HTTP POST convencional emanando de nosso servidor para o seu. Esta solicitação contém cabeçalhos HTTP, que podem auxiliar na autenticação de sua origem, juntamente com um corpo HTTP que encapsula os dados principais, detalhando o tipo de evento de webhook e os dados relevantes.

Cabeçalhos do Webhook

HTTP Request 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

Corpo do Webhook

HTTP Request Body (application/json) 
{
  "eventType": "CHECKOUT_COMPLETED",
  "data": {...}
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Análise de Cargas Úteis do Webhook

As cargas úteis do webhook diferem entre tipos de eventos. Seu sistema deve inspecionar o eventType e implementar um analisador para cada tipo de evento que você deseja suportar.

PHP Logo Exemplo: Análise Baseada em Tipo de Evento (PHP)

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

Autenticação de Webhook

Adicione segurança adicional ao seu endpoint e previna falsificações analisando o cabeçalho X-Webhook-Auth e verificando seu valor.

Verifique se a solicitação foi enviada pela plataforma Whalestack criando um hash hash('sha256', YOUR_API_SECRET . WEBHOOK_REQUEST_BODY) (onde . representa a concatenação) e comparando-o com o valor do cabeçalho X-Webhook-Auth.

PHP Logo Exemplo: Verificação de Autenticação (PHP)

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
}

Respondendo a Webhooks

Responda com HTTP 200 OK. Seu servidor deve responder com um status de código 200 na resposta HTTP depois de analisar e persistir com sucesso a carga útil do webhook. Nosso sistema continuará enviando solicitações de webhook por até 48 horas em intervalos crescentes até detectarmos um código de status 200. Se não recebermos um status de código HTTP 200 por um período mais longo que esse, o webhook expira e para de tentar.

Inspeção do Histórico de Webhook

Inspecione webhooks enviados pelo Whalestack junto com suas respostas HTTP na plataforma .

Isso pode ser extremamente útil durante a fase de implementação porque ajuda a depurar problemas nas solicitações e respostas HTTP.

WEBHOOK EVENTcheckout-completed

Este evento de webhook é acionado quando um pagamento do cliente é concluído com sucesso, sua carteira Whalestack foi creditada, e é seguro enviar quaisquer bens ou serviços.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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"
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando um pagamento do cliente é capturado, mas o valor do pagamento é menor do que o esperado. Nesta situação, os fundos não foram creditados na sua conta e você não deve enviar nenhum bem ou serviço ainda.

Pagamentos não resolvidos são listados no seu painel de controle da UI e contêm opções de ação, como emitir um reembolso ou aceitar o checkout subpago emitindo um desconto personalizado.

Se este é um checkout do tipo HOSTED e você associou um cliente a este checkout, nosso sistema automaticamente notifica o cliente com instruções sobre como completar o checkout e pagar a diferença restante.

Se este é um checkout do tipo SELF-HOSTED ou você não o associou a um cliente, você deve notificar seu usuário para enviar outro pagamento cobrindo a diferença entre sourceAmountRequired e sourceAmountReceived. O pagamento deve ser enviado para o mesmo endereço de depósito originalmente associado com este checkout.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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"
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando você aceita manualmente um checkout subpago via interface de usuário da plataforma Whalestack ou tem a liquidação automática de checkouts subpagos habilitada nas configurações da sua conta. Nestes eventos, sua conta é creditada com uma parte do montante de liquidação originalmente solicitado.

O campo de atributo settlementAmountReceived fornece o valor exato creditado à sua conta. Os campos sourceAmountRequired e sourceAmountReceived indicam o quanto o checkout foi subpago.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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"
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando um depósito foi detectado na cadeia, mas ainda não está confirmado e sua conta ainda não foi creditada. Leva de uma a seis confirmações na blockchain para que um depósito atinja a finalidade.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

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

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando um depósito é concluído com sucesso.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

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

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando uma troca é realizada com sucesso.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

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

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando uma troca falha (e nenhuma transação que afeta o saldo ocorre).

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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":[]
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando uma transferência é completada com sucesso.

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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"
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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

Este evento de webhook é acionado quando uma transferência falha (e nenhuma transação que afeta o saldo ocorre).

Por favor, leia sobre conceitos de webhook para aprender mais sobre como trabalhar com webhooks.

Corpo do Webhook

HTTP Request 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"
      }
   }
}

Atributos da Carga Útil do Webhook

Nome Tipo Descrição Anulável
.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
© Whalestack LLC 2018-2024 · Termos de Serviço · Política de Privacidade · Política de PLD e CSC · Política Anti-Fraude · Processamento de Dados · Licença A Whalestack LLC (Número da Empresa 0000970546) é uma companhia de responsabilidade limitada incorporada na Rua Jedności, 65-018 Zielona Góra, Polônia. A Whalestack LLC reporta-se ao Inspetor Geral de Informações Financeiras e é autorizada pelo Ministério das Finanças da Polônia a prover serviços de câmbio e custódia de moeda virtual sob o número de Provedor de Serviços de Ativos Virtuais RDWW-311. União Europeia Licenciada e Regulamentada na UE © Whalestack LLC 2018-2024 · Termos de Serviço · Política de Privacidade · Política de PLD e CSC · Política Anti-Fraude · Processamento de Dados · Licença
Space Cat
Gato Espacial! Miau. 🐱🚀