Using the Whalestack API

Unlock fast, secure, and effortless cryptocurrency payments with the Whalestack API. Once you've secured your API key post-registration, create a checkout or generate a blockchain deposit address. Whether it's Bitcoin, Lightning, Litecoin, Stellar, or another supported network, getting paid is straightforward. Plus, take advantage of fiat on- and off-ramping through SWIFT or SEPA.

Wallets and Deposits

With Whalestack, you instantly receive dedicated deposit addresses for Bitcoin, Lightning, Litecoin, Stellar, SWIFT, SEPA, and more. Begin receiving blockchain payments moments after signup. Use the GET /wallets and POST /deposit-address endpoints to fetch your blockchain addresses and initiate custom deposits.

Checkouts

Whalestack checkouts streamline customer payments. We offer a superior user experience with fully customizable hosted checkouts. If pre-built payment pages aren't your style, harness our backend checkout APIs for full control. Read our introduction to building checkouts or dive directly into the POST /checkout or POST /checkout/hosted endpoints.

Swaps and Transfers

Upon receiving funds, either through checkouts or custom deposits, you can immediately utilize them. Swap them across different assets or move them to a bank or blockchain account (though we suggest forwarding to cold storage for maximum security). Use the POST /swap and POST /transfer endpoints to explore swaps and transfers.

Transparent Financial Reporting

No more puzzling over complex blockchain payment trails. Whalestack aggregates all your transactions in the Financial Reports section in your account. You can even link transactions to specific counter-parties like customers (POST /customer) or beneficiaries (POST /beneficiary). We furnish you with CSV reports, visual charts, and insightful analytics, streamlining your accounting processes.

Software Development Kits

The Whalestack API seamlessly integrates with REST clients across all programming languages. For a jump-start, we've curated SDKs for PHP, Ruby, and NodeJS. Explore these resources on our GitHub page.

PHP
Official Whalestack SDK for PHP

Ruby
Official Whalestack SDK for Ruby

NodeJS
Official Whalestack SDK for NodeJS

E-Commerce Integrations

We're dedicated to regularly refining our e-commerce toolset, ensuring seamless integrations with Whalestack. Our suite of libraries, plugins, and extensions is crafted for your swift and hassle-free onboarding. Discover the array of e-commerce integrations ready for deployment below.

Magento
Official Whalestack Extension for Magento

PrestaShop
Official Whalestack Extension for PrestaShop

Shopify
Official Whalestack Integration for Shopify

WooCommerce
Official Whalestack Plugin for WooCommerce

WordPress
Official Whalestack Plugin for WordPress

Adobe Commerce
Official Whalestack Extension for Adobe Commerce

Building Checkouts

Begin by choosing between our fully customizable checkout page experience and the self-hosted option, where you harness our backend APIs to maintain complete control over the payment journey.

Option 1: Self-Hosted Checkouts

Deliver the checkout process under your brand within your web application. Opt for self-hosted backend API checkouts to ensure a seamless experience for users, keeping them within your application's ecosystem. Initiate whitelabel payments via the POST /checkout API endpoint.

Option 2: Checkout Pages

Our fully brandable hosted checkouts present the most straightforward way to receive payments on Whalestack. The POST /checkout/hosted API endpoint crafts a payment link. Whether directing users to whalestack.com or your own domain via Brand Connect, the process remains seamless. After obtaining the checkout URL, navigate your customer to the hosted page, and they're all set to pay. We notify you via webhooks, emails, or API polling, about inbound funds.

Below, find a step-by-step guide to creating a dynamic hosted checkout:

Example Request

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"

Authentication is supplied via HTTP headers and charge.json is a JSON object:

Example Charge (minimal)

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

Above example creates a charge for an item priced at 169.99 EUR. You can configure more details, such as shipping costs, discounts, taxes, the related customer, as well as your preferred settlement asset as documented here.

Example Response (application/json)

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

The API returns a unique identifier along with a hosted checkout URL, which you display back to your customer in order for him or her to complete payment. Once the funds are captured we notify you via WEBHOOK checkout-completed.

Receiving Payments

Cryptocurrency transactions differ from traditional credit card payments. Instead of merchants pulling funds using credit card details, cryptocurrency operates on a push model. This requires the customer to actively initiate and send the payment to the merchant.

Upon initiating a checkout, Whalestack vigilantly tracks the chosen blockchain for incoming payments.. There's a 60-minute window for the completion of the transaction. If the payment isn't finalized within this period, it's marked as expired. However, delayed payments that eventually come through are still accepted.

After successfully receiving the payment, your balance gets updated, your dashboard reflects the changes, and a webhook callback is dispatched to your server. This ensures the automated processing of the order in your system via the WEBHOOK checkout-completed mechanism.

Example Webhook (application/json)

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

The webhook contains a JSON object in the HTTP request body and informs you about incoming payments and their attributes as specified in WEBHOOK checkout-completed. In above example the customer paid in BTC and the merchant got credited in USDC.

Brand Connect by Whalestack

Whalestack's Brand Connect infuses your Whalestack checkout experience with your unique brand identity. Whether it's your distinct logo, thematic images, or a UI tailored to your brand's aesthetics, Brand Connect ensures your checkout pages feel like an organic extension of your platform. Choose between hosting on whalestack.com or deploy on your own domain with our straightforward docker container setup.

Brand Connect is the ideal solution for payment service providers aiming to harness Whalestack's comprehensive checkout system while maintaining their own distinctive brand presentation. This includes adept handling of transaction nuances like overpayments, underpayments, refunds, or multi-transactions. Yet, even if you're not a service provider but just want a consistent visual experience for your online shop, Brand Connect is your go-to.

Branding Customization

Setting up your tailored checkout appearance is straightforward with our Brand Connect interface in your account settings. Here's how to personalize your brand:

Activate Brand Connect in your account settings
Proceed to modify Brand Information, Images, Fonts, and Colors within the settings.

Once configured, your checkout pages will seamlessly blend with your branding - logo, favicon, tailored crypto images, font preferences, and color schemes. Inspecting your checkout, you'll notice a flawless integration with no sign of Whalestack as the underlying service provider.

Custom Web Domain Setup

By default, Brand Connect runs on the whalestack.com domain. However, if you aspire for a deeper brand immersion, you can direct your checkouts through your own web domain. This is ideal for those providing payment services who wish to seamlessly embed Whalestack's capabilities while retaining their distinct brand aura throughout.

This integration is achieved via the Brand Connect docker container (GitHub). By placing it in your hosting setup and making a few DNS tweaks, you enable a checkout flow that's entirely in sync with your brand identity. Here's a step-by-step guide:

Activate Brand Connect in your account settings
Refine your Brand Information, Images, Fonts, and Colors in settings
Designate your custom web domain for checkouts and get your WS_BRANDING_KEY (after completing the above steps)
Implement the Brand Connect docker container alongside your SSL certificate
Redirect your web domain's DNS to the IP address hosting the docker container.

And voila! Your Whalestack checkout pages are now an integral part of your domain, reflecting your unique brand essence. Dive deeper on GitHub.

Ensuring Secure Authentication

The Whalestack API primarily demands authentication. Distinctly, API endpoints are classified as either public () or protected (). To access a protected endpoint, authenticate your request using your API key via the Basic-Auth or more secure Digest-Auth method. To effortlessly verify your authentication method, employ the GET /auth-test endpoint.

Securing Your API Credentials

Head to the API Settings to retrieve your API key and secret. Here, you can also set your favored authentication strategy and amplify security by enabling "IP-address whitelisting". In case of any suspicion regarding your API secret's safety, you have the provision to regenerate it from these settings.

Digest-Auth: Our Recommended Choice

We advocate for the Digest-Auth method when tapping into protected Whalestack API endpoints. Essential headers for every request include X-Digest-Key, X-Digest-Signature, and X-Digest-Timestamp, all elaborated in the subsequent sections.

Request

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"

Request Headers

Key	Type	Description
`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

The X-Digest-Signature is generated by creating a SHA256 HMAC hash using your API Secret as the shared secret in the message digest. The encrypted payload is composed as follows:
ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY, where . represents string concatenation.

X-Digest-Signature Components

Component	Type	Description
`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.

Code Example (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);

Code Example (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)

Code Example (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');

View these examples if you are unsure how to create an HMAC SHA256 signature in your programming language.

Basic-Auth

You can choose to use a basic authentication header, which is easier to implement (as it is a static hash over your API key and secret) but less secure than Digest-Auth. We recommend to use Basic-Auth during development or in test environments only.

Request

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

Request Headers

Key	Type	Description
`X-Basic`	string	SHA256 hash over `YOUR_API_KEY:YOUR_API_SECRET`	mandatory

Code Example

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

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

IP Address Whitelisting

Use the API Settings to configure whether your API account can be accessed from any IP address or whitelisted IP addresses only. IP address whitelisting is recommended for production environments as it dramatically increases security. Withdrawal endpoints can only be accessed from whitelisted IP addresses.

Software Development Kits (SDKs)

Our Software Development Kits for PHP, Ruby, and NodeJS are here to help you quickly integrate with the Whalestack Payments API without hassle.

Below is a list of SDKs currently available on our GitHub.

PHP
Official Whalestack SDK for 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  );

View on GitHub

Ruby
Official Whalestack SDK for 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  )

View on GitHub

NodeJS
Official Whalestack SDK for NodeJS

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

View on GitHub

GET/networksprotected

Returns a list of blockchain and bank networks supported by the Whalestack platform.

Request

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/assetsprotected

Returns a list of assets supported by the Whalestack platform.

Request

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/currenciesprotected

Returns a list of currencies supported by the Whalestack platform.

Request

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST /checkout protected

Kickstart your self-hosted payment process by initializing a checkout. This endpoint lets you craft a checkout right on your server, allowing full autonomy over its UI or API. For an alternative that automates a checkout page on Whalestack's infrastructure, consider the POST /checkout/hosted. If you are new to initializing a checkout process, we recommend starting here.

To interact with this endpoint you'll need to provide a charge object, which encompasses line items, potential additions like shipping fees or discounts, and applicable taxes. For a more personalized touch and invoice generation, link the charge to a specific customer. You also get the leverage to dictate the settlement currency, which could diverge from the charge's denomination or the currency chosen by your customer. A successful interaction with this endpoint furnishes you with an array of payment methods and their respective amounts, all set to be presented to your clientele.

Your customers can then cherry-pick their favored payment modality (for instance, Bitcoin). After their selection, submit a fresh request infused with the chosen blockchain and its relevant checkout ID to POST /checkout/commit, which returns deposit instructions to be displayed to your customer. As soon as the checkout commitment is in place, Whalestack's system diligently scans the blockchain for incoming payments, keeping you in the loop about payment progressions via the WEBHOOK checkout-completed.

Do note, checkouts declare a payment intent and designed for one-time use. Always initiate a brand-new checkout for each transaction.

Example Request

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.

Example Payload (Full)

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

Request Params (POST)

Linking Customers

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

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

Success Response Attributes

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

Next Step

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/commitprotected

This endpoint serves as a vital continuation of the checkout process, which was initiated through POST /checkout. If you are new to initializing a checkout process, we recommend starting here.

When making a request to this endpoint, you'll need to provide a checkoutId and a network, as obtained from the POST /checkout request. If the selected network supports multiple assets, you'll also need to include an asset (if omitted, the network's default asset is used). Upon a successful request, you will receive deposit information, which should be presented to your customer to facilitate the payment process.

Once this endpoint is invoked, Whalestack initiates real-time monitoring of the relevant blockchain network. When the payment is completed, your server is automatically notified via the WEBHOOK checkout-completed. Alternatively, you can periodically check the payment status by using GET /checkout after displaying the deposit information to your customer.

In the preceding step, POST /checkout provided you with a list of available payment methods, as illustrated below:

Example Response (as given by `POST /checkout`)

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

As a prerequisite to invoke this endpoint you should have received a response as above from the POST /checkout endpoint. It contains a list of payment methods, which you display back to your customer to choose from. Upon selection, you invoke POST /checkout/commit (this endpoint) with the selected depositNetwork, relatedAssetId (if necessary), and checkoutId to receive deposit information for your customer to make the payment.

Request

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

Where payload.json is a JSON object.

Example Payload (Bitcoin)

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

Example Payload (EURC, Stellar)

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

Example Payload (XLM, Stellar)

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

Request Params

Key	Type	Description	Default	Mandatory
`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

Example Success Response (Bitcoin) application/json

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

Example Success Response (XLM) application/json

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

Provide your customer with the address as well as memo and memoType when the STELLAR network is selected for payment. This is important in order for Whalestack to map the payment to your merchant account.

Success Response Attributes

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

Next Steps

Display the deposit information back to your customer. Meanwhile, Whalestack starts monitoring the blockchain address given in the API response above and notifies you automatically via WEBHOOK checkout-completed when a payment completes. Alternatively you can periodically poll GET /checkout for payment updates.

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST /checkout/hosted protected

This endpoint generates and delivers a unique URL that points to a checkout page, fully managed on Whalestack servers. For a more hands-on approach where you oversee the UI and checkout flow, consider the POST /checkout endpoint instead. If you are new to initializing a checkout process, we recommend starting here.

By invoking this endpoint, your server provides parameters encompassing payment specifics, optional tax line items, customer data, and desired settlement currency. In exchange, your server obtains a checkout URL, ready to be showcased to your clientele.

On accessing this URL, customers meet a user-friendly checkout page housed on Whalestack's infrastructure. This interactive page lays out all essential information to facilitate the payment process. Once the transaction concludes, our system instantly informs your application through WEBHOOK checkout-completed. For those keen on proactiveness, the GET /checkout endpoint lets you continuously monitor the payment status.

Designed for adaptability, Whalestack's hosted checkouts seamlessly adjust to both mobile displays and expansive desktop screens. Fine-tune their look to resonate with your brand aesthetics using Brand Connect.

Remember, each hosted checkout URL is distinct and single-use. Ensure you generate a fresh URL for every new transaction.

Example Request

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.

Example Payload (Full)

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

Request Params (POST)

Linking Customers

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutprotected

Retrieves information about a given checkout.

The response of this endpoint contains information about blockchain payments associated with this checkout, its overall completion state, as well as additional context information.

This endpoint is suitable for polling payment events associated with the given checkout. A more efficient alternative is listening for payment events using WEBHOOK checkout-completed on your server.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /checkout` or `POST /checkout/hosted`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutsprotected

Retrieves a list of checkout objects (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of checkout objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletsprotected

Returns a list of wallet objects containing information about the associated asset, balance, available networks, and deposit addresses (if available).

Request

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletprotected

Returns a wallet object containing information about the associated asset, balance, available networks, and deposit addresses (if available).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`asset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`.	-	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/deposit-addressprotected

Creates your blockchain or bank deposit address for a given network and asset.

Example Request

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

Where payload.json is a JSON object.

Example Payloads

The payload depends on the source network you are depositing funds from. Select below.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

{
    "network": "BITCOIN"
}

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

{
    "network": "LITECOIN"
}

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

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

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

Request Params (POST)

The payload depends on the source network you are depositing funds from. Select below.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `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

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `LIGHTNING`	false	mandatory
`.amount`	string	Invoice amount in SAT.	false	mandatory
`.webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	false	optional

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `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

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `STELLAR`	false	mandatory
`.asset`	string	The deposit asset identifier on the Stellar network. Consists of asset code and issuer.	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

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SWIFT`	false	mandatory
`.asset`	string	Specifies the asset credited to your account when your deposit completes. References USDC or EURC. An asset identifier as given by `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

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SEPA`	false	mandatory
`.asset`	string	Specifies the asset credited to your account when your deposit completes. References USDC or EURC. An asset identifier as given by `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

Success Response application/json

The payload depends on the source network you are depositing funds from. Select below.

Bitcoin Lightning Litecoin Stellar SWIFT SEPA

{
    "depositAddress": {
        "network": "BITCOIN",
        "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)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "100.0000000"
    }
}

Success Response Attributes

Name	Type	Description	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.address`	string	The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH).	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "LIGHTNING",
        "fields": {
            "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9c...",
            "amount": "5000"
        },
        "fieldConfig": [
            {
                "key": "invoice",
                "label": "Lightning Invoice",
                "description": "A BOLT 11 Lightning invoice with encoded amount."
            },
            {
                "key": "amount",
                "label": "Invoice Amount",
                "description": "Invoice amount in SAT."
            }
        ],
        "minAmount": "4000.0000000",
        "maxAmount": "507059.0000000"
    }
}

Success Response Attributes

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

{
    "depositAddress": {
        "network": "LITECOIN",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdf"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Litecoin Address",
                "description": "The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
        ],
        "minAmount": "0.0000100",
        "maxAmount": "10000.0000000"
    }
}

Success Response Attributes

Name	Type	Description	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `LITECOIN`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.address`	string	The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH).	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "STELLAR",
        "fields": {
            "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU7",
            "memo": "sda3195ad7ed65",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "asset",
                "label": "Stellar Asset",
                "description": "The deposit asset identifier on the Stellar network. Consists of asset code and issuer."
            },
            {
                "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"
    }
}

Success Response Attributes

Name	Type	Description	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `STELLAR`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.asset`	string	The deposit asset identifier on the Stellar network. Consists of asset code and issuer.	false
`.account`	string	The deposit account on the Stellar network. Starting with G.	false
`.memo`	string	The mandatory memo to be included in the transaction. Do not omit this or your deposit will be delayed.	false
`.memoType`	string	The mandatory memo type to be included in the transaction.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "SWIFT",
        "fields": {
            "reference": "EUR-BD-USDC-1a2b3c4d5e6f",
            "beneficiary": "Whalestack Sp. z o.o.",
            "account": "LT293550020000047621",
            "swiftCode": "UAPELT22XXX",
            "bankName": "UAB Pervesk",
            "bankAddress": "Vilnius, Lithuania",
            "correspondentBankSwift": "INCOCHZZXXX",
            "correspondentBankName": "INCORE BANK AG",
            "correspondentBankAddress": "Schlieren, Switzerland"
        },
        "fieldConfig": [
            {
                "key": "reference",
                "label": "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. Provide this if your bank asks you for an intermediary or correspondent bank."
            }
        ],
        "minAmount": 250,
        "maxAmount": 500000
    }
}

Send Payment in EUR

Send payment denominated in EUR.

Success Response Attributes

Name	Type	Description	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `SWIFT`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.reference`	string	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.	false
`.beneficiary`	string	The beneficiary account name.	false
`.account`	string	The bank account number.	false
`.swiftCode`	string	The 8-11 character SWIFT or BIC code identifying your bank or financial institution.	false
`.bankName`	string	The beneficiary bank name.	false
`.bankAddress`	string	The beneficiary bank address.	false
`.correspondentBankSwift`	string	Provide this SWIFT/BIC code if your bank asks you for an intermediary or correspondent bank.	false
`.correspondentBankName`	string	The correspondent bank name. Provide this if your bank asks you for an intermediary or correspondent bank.	false
`.correspondentBankAddress`	string	The correspondent bank address. Provide this if your bank asks you for an intermediary or correspondent bank.	false
`.fieldConfig`	array	A list of objects describing the keys and values received in the `fields` attribute.	false
`.key`	string	A string indicating an attribute in the `fields` object.	false
`.label`	string	A label for the field associated with the key.	false
`.description`	string	A description of the field associated with the key.	false
`.minAmount`	string	The minimum deposit amount.	false
`.maxAmount`	string	The maximum deposit amount.	false

{
    "depositAddress": {
        "network": "SEPA",
        "fields": {
            "reference": "EUR-BD-USDC-1a2b3c4d5e6f",
            "beneficiary": "Whalestack Sp. z o.o.",
            "iban": "LT293550020000047621",
            "swiftCode": "UAPELT22XXX",
            "bankName": "UAB Pervesk",
            "bankAddress": "Vilnius, Lithuania"
        },
        "fieldConfig": [
            {
                "key": "reference",
                "label": "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": 50,
        "maxAmount": 500000
    }
}

Send Payment in EUR

Send payment denominated in EUR.

Success Response Attributes

Name	Type	Description	Nullable
`.depositAddress{}`	object	An object containing deposit information.	false
`.network`	string	A network identifier as given by `GET /networks`, e.g. `SEPA`.	false
`.fields`	object	A set of fields (all strings) specifying the deposit account.	false
`.reference`	string	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.	false
`.beneficiary`	string	The beneficiary account name.	false
`.iban`	string	The international bank account number (IBAN).	false
`.swiftCode`	string	The 8-11 character SWIFT or BIC code identifying your bank or financial institution.	false
`.bankName`	string	The beneficiary bank name.	false
`.bankAddress`	string	The beneficiary bank address.	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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositprotected

Retrieves details of a given deposit.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Blockchain transaction id of your deposit or unique identifier as given by `GET /deposits`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositsprotected

Retrieves a list of your deposits (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of deposit objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swapprotected

Initiates an asset exchange in your account and returns a swap object in a PENDING_API_COMMIT state. The object contains a quote with source and target amounts. To accept the quote, confirm the swap by invoking POST /swap/commit.

Request

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

Where payload.json is a JSON object.

Example: Swap 100 USDC into BTC

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

Example: Swap BTC into 100 XLM

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

Request Params (POST)

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swap/commitprotected

Commits and executes a swap in PENDING_API_COMMIT state previously initiated with POST /swap.

Returns a swap object in a non-final PROCESSING state. A final state of COMPLETED or FAILED is sent by webhook and can alternatively be polled using GET /swap.

Request

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

Where payload.json is a JSON object.

Example Payload

{
  "swapId":"12d72c3c8145"
}

Request Params

Key	Type	Description	Default	Mandatory
`swapId`	string(12)	Unique identifier as given by `POST /swap`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapprotected

Retrieves details of a given swap.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `GET /swaps` or `POST /swap`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapsprotected

Retrieves a list of your swaps (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of swap objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/target-accountprotected

Target accounts are a pre-requisite for fund transfers via the API or web app. This endpoint Links a blockchain or bank account with your account on the Whalestack platform. Reference it via your custom labels when using the POST /transfer endpoint.

Example Request

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

Where payload.json is a JSON object.

Example Payloads

The payload depends on the target network you are transferring funds to. Select below.

Bitcoin Ethereum Lightning Litecoin Stellar SWIFT SEPA Brazilian PIX

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

Use EUR Bank Accounts Only

Your bank account must be able to receive deposits denominated in EUR. Other currencies are not supported.

Request Params (POST)

The payload depends on the target network you are transferring funds to. Select below.

Bitcoin Ethereum Lightning Litecoin Stellar SWIFT SEPA Brazilian PIX

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `BITCOIN`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.address`	string(62)	The Bitcoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH).	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

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

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `LITECOIN`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.address`	string(62)	The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH).	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `STELLAR`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.account`	string(56)	An account on the Stellar network. Starting with G.	false	mandatory
`.memo`	string(64)	Identifies the recipient or payment purpose. A memo is often required by exchanges and wallets. Make sure to provide one if needed.	false	optional
`.memoType`	string(4)	An additional flag identifying the memo type. This is usually `text`. Available options: `texthashid`	false	optional
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SWIFT`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.account`	string(128)	The bank account number.	false	mandatory
`.bic`	string(128)	The 8-11 character SWIFT or BIC code identifying your bank or financial institution.	false	mandatory
`.bankName`	string(128)	The beneficiary bank name.	false	mandatory
`.bankAddress`	string(256)	The beneficiary bank address.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `SEPA`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.iban`	string(128)	The international bank account number (IBAN).	false	mandatory
`.bic`	string(128)	The 8-11 character SWIFT or BIC code identifying your bank or financial institution.	false	mandatory
`.bankName`	string(128)	The beneficiary bank name.	false	mandatory
`.bankAddress`	string(256)	The beneficiary bank address.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Key	Type	Description	Nullable	Mandatory
`.network`	string	A target network identifier as given by `GET /networks`, i.e. `PIX`	false	mandatory
`.label`	string(32)	A unique and arbitrary account name in plain text. This is your reference to this target account when invoking `POST /transfer` to send funds.	false	mandatory
`.fields`	object	A set of fields specifying the account on the target network.	false	mandatory
`.pixKey`	string(256)	The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key.	false	mandatory
`.taxId`	string(256)	The recipient tax id. CNPJ format (00.000.000/0000-00) for corporate identities or CPF format (000.000.000-00) for individuals.	false	mandatory
`.beneficiaryId`	string(12)	An identifier referencing the beneficiary you want to associate this target account with. As given by `POST /beneficiary` or other beneficiary related endpoints.	false	optional

Success Response application/json

The payload depends on the target network. Select below.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "targetAccount": {
        "network": "BITCOIN",
        "label": "Ledger Nano on Bitcoin",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
        },
        "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-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

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

{
    "targetAccount": {
        "network": "LITECOIN",
        "label": "Ledger Nano on Litecoin",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Litecoin Address",
                "description": "The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "STELLAR",
        "label": "Ledger Nano on Stellar",
        "fields": {
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo": "EXODUS",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Stellar Account",
                "description": "An account on the Stellar network. Starting with G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "Identifies the recipient or payment purpose. A memo is often required by exchanges and wallets. Make sure to provide one if needed."
            },
            {
                "key": "memoType",
                "label": "Memo Type",
                "description": "An additional flag identifying the memo type. This is usually `text`."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "SWIFT",
        "label": "My Bank Account on SWIFT",
        "fields": {
            "account": "DE12334567890",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Bank Account Number",
                "description": "The bank account number."
            },
            {
                "key": "bic",
                "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."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "SEPA",
        "label": "My Bank Account on SEPA",
        "fields": {
            "iban": "DE23100110012624331586",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "iban",
                "label": "IBAN",
                "description": "The international bank account number (IBAN)."
            },
            {
                "key": "bic",
                "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."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "PIX",
        "label": "My Bank Account on Brazilian PIX",
        "fields": {
            "pixKey": "34.773.171\/0001-75",
            "taxId": "34.773.171\/0001-75"
        },
        "fieldConfig": [
            {
                "key": "pixKey",
                "label": "PIX Key",
                "description": "The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key."
            },
            {
                "key": "taxId",
                "label": "Tax ID",
                "description": "The recipient tax id. CNPJ format (00.000.000\/0000-00) for corporate identities or CPF format (000.000.000-00) for individuals."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/target-accountprotected

Retrieves information about a given target account.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`label`	string	The unique label (account name) as given by you in `POST /post-target-account` or the web app UI.	null	mandatory

Success Response application/json

The payload depends on the target network. Select below.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "targetAccount": {
        "network": "BITCOIN",
        "label": "Ledger Nano on Bitcoin",
        "fields": {
            "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
        },
        "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-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

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

{
    "targetAccount": {
        "network": "LITECOIN",
        "label": "Ledger Nano on Litecoin",
        "fields": {
            "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
        },
        "fieldConfig": [
            {
                "key": "address",
                "label": "Litecoin Address",
                "description": "The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "STELLAR",
        "label": "Ledger Nano on Stellar",
        "fields": {
            "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo": "EXODUS",
            "memoType": "text"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Stellar Account",
                "description": "An account on the Stellar network. Starting with G."
            },
            {
                "key": "memo",
                "label": "Memo",
                "description": "Identifies the recipient or payment purpose. A memo is often required by exchanges and wallets. Make sure to provide one if needed."
            },
            {
                "key": "memoType",
                "label": "Memo Type",
                "description": "An additional flag identifying the memo type. This is usually `text`."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": "b5bcf27e5482"
    }
}

{
    "targetAccount": {
        "network": "SWIFT",
        "label": "My Bank Account on SWIFT",
        "fields": {
            "account": "DE12334567890",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "account",
                "label": "Bank Account Number",
                "description": "The bank account number."
            },
            {
                "key": "bic",
                "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."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "SEPA",
        "label": "My Bank Account on SEPA",
        "fields": {
            "iban": "DE23100110012624331586",
            "bic": "NTSBDEB1XXX",
            "bankName": "N26",
            "bankAddress": "Berlin, Germany"
        },
        "fieldConfig": [
            {
                "key": "iban",
                "label": "IBAN",
                "description": "The international bank account number (IBAN)."
            },
            {
                "key": "bic",
                "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."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

{
    "targetAccount": {
        "network": "PIX",
        "label": "My Bank Account on Brazilian PIX",
        "fields": {
            "pixKey": "34.773.171\/0001-75",
            "taxId": "34.773.171\/0001-75"
        },
        "fieldConfig": [
            {
                "key": "pixKey",
                "label": "PIX Key",
                "description": "The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key."
            },
            {
                "key": "taxId",
                "label": "Tax ID",
                "description": "The recipient tax id. CNPJ format (00.000.000\/0000-00) for corporate identities or CPF format (000.000.000-00) for individuals."
            }
        ],
        "state": "ACTIVE",
        "timestamp": "2023-04-16T21:34:28+00:00",
        "beneficiaryId": null
    }
}

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/target-accountsprotected

Returns a list of target account objects (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of target account objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

The payload of each object depends on its target network. Select below.

Bitcoin Ethereum Litecoin Stellar SWIFT SEPA Brazilian PIX

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "BITCOIN",
            "label": "Ledger Nano on Bitcoin",
            "fields": {
                "address": "bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "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-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

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

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "LITECOIN",
            "label": "Ledger Nano on Litecoin",
            "fields": {
                "address": "LgVQ2XamTCjBa3tnUpWQ1H4hgzMddWCPdn"
            },
            "fieldConfig": [
                {
                    "key": "address",
                    "label": "Litecoin Address",
                    "description": "The Litecoin address. Can be in any format, i.e. native SegWit (bech32), SegWit (P2SH), or legacy (P2PKH)."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "STELLAR",
            "label": "Ledger Nano on Stellar",
            "fields": {
                "account": "GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
                "memo": "EXODUS",
                "memoType": "text"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Stellar Account",
                    "description": "An account on the Stellar network. Starting with G."
                },
                {
                    "key": "memo",
                    "label": "Memo",
                    "description": "Identifies the recipient or payment purpose. A memo is often required by exchanges and wallets. Make sure to provide one if needed."
                },
                {
                    "key": "memoType",
                    "label": "Memo Type",
                    "description": "An additional flag identifying the memo type. This is usually `text`."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": "b5bcf27e5482"
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "SWIFT",
            "label": "My Bank Account on SWIFT",
            "fields": {
                "account": "DE12334567890",
                "bic": "NTSBDEB1XXX",
                "bankName": "N26",
                "bankAddress": "Berlin, Germany"
            },
            "fieldConfig": [
                {
                    "key": "account",
                    "label": "Bank Account Number",
                    "description": "The bank account number."
                },
                {
                    "key": "bic",
                    "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."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "SEPA",
            "label": "My Bank Account on SEPA",
            "fields": {
                "iban": "DE23100110012624331586",
                "bic": "NTSBDEB1XXX",
                "bankName": "N26",
                "bankAddress": "Berlin, Germany"
            },
            "fieldConfig": [
                {
                    "key": "iban",
                    "label": "IBAN",
                    "description": "The international bank account number (IBAN)."
                },
                {
                    "key": "bic",
                    "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."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

{
    "count": 1,
    "limit": 10,
    "offset": 0,
    "targetAccounts": [
        {
            "network": "PIX",
            "label": "My Bank Account on Brazilian PIX",
            "fields": {
                "pixKey": "34.773.171\/0001-75",
                "taxId": "34.773.171\/0001-75"
            },
            "fieldConfig": [
                {
                    "key": "pixKey",
                    "label": "PIX Key",
                    "description": "The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key."
                },
                {
                    "key": "taxId",
                    "label": "Tax ID",
                    "description": "The recipient tax id. CNPJ format (00.000.000\/0000-00) for corporate identities or CPF format (000.000.000-00) for individuals."
                }
            ],
            "state": "ACTIVE",
            "timestamp": "2023-04-16T21:34:28+00:00",
            "beneficiaryId": null
        }
    ]
}

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/target-accountprotected

Unlinks a target account from the Whalestack platform.

Example Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params

Key	Type	Description	Default	Mandatory
`label`	string	Unique label (account name) as given in `POST /target-account` or listed in other target account related endpoints.	null	mandatory

Success Response application/json

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/transferprotected

Initiates a fund transfer from your wallet to your external bank or blockchain account. Returns a transfer object in a PENDING_API_COMMIT state. The object contains a quote with source, target, and network fee amounts (if any). To accept the quote, confirm the transfer by invoking POST /transfer/commit.

Depends on prior calls to POST /target-account linking external accounts for transfers.

Request

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

Where payload.json is a JSON object.

Example: Transfer 5,000 USDC to your SEPA account (as EUR)

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

Example: Transfer BTC with a net target amount of 0.5 BTC

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

Example: Transfer towards a BOLT 11 Bitcoin Lightning Invoice

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

Example: Transfer 5,000 USDC to a Stellar account

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

Example: Transfer 5,000 USDC to an Ethereum account

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

Request Params (POST)

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/transfer/commitprotected

Commits and executes a fund transfer in PENDING_API_COMMIT state previously initiated with POST /transfer.

Returns a transfer object in a non-final PROCESSING state. A final state of COMPLETED or FAILED is sent by webhook and can alternatively be polled using GET /transfer.

Request

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

Where payload.json is a JSON object.

Example Payload

{
  "transferId":"12d72c3c8145"
}

Request Params

Key	Type	Description	Default	Mandatory
`transferId`	string(12)	Unique identifier as given by `POST /transfer`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/transferprotected

Retrieves details of a given transfer.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `GET /transfers` or `POST /transfer`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/transfersprotected

Retrieves a list of your transfers (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of transfer objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/pingpublic

Sends a ping request to the API. This endpoint is suitable for testing network connectivity to the Whalestack API.

Request

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

Success Response application/json

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates the request was processed successfully.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/address-validationprotected

Validates public keys (addresses or accounts) on supported blockchains. Can be used as a utility endpoint to validate user input in your application.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

{
    "valid":true
}

Success Response Attributes

Name	Type	Description	Nullable
`valid`	boolean	Indicates whether the given address or account public key is valid.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/exchange-rateprotected

This endpoint returns the current exchange rate between two assets at a given amount while taking the applicable liquidity and order book depth into account. This endpoint can be used to calculate the tentative exchange rate during checkouts or swaps on Whalestack.

To query the global average exchange rate between two arbitrary currencies, please use the GET /exchange-rate-global endpoint instead.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/exchange-rate-globalprotected

Returns the global average exchange rate between two arbitrary currencies. This endpoint is purely informative and does not reflect exchange rates available on Whalestack. To query exchange rates as used by the Whalestack platform, please use the GET /exchange-rate endpoint instead.

Request

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

Request Params

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/timepublic

Returns a Unix timestamp with the current Whalestack server time. Use this endpoint when generating the Digest-Auth signature for authentication if you feel time the between your server and the Whalestack server is askew.

Request

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

Success Response application/json

{
    "time":1525898643
}

Success Response Attributes

Name	Type	Description	Nullable
`time`	integer	Unix timestamp with Whalestack server time.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/auth-testprotected

A good starting place to test your Basic-Auth or Digest-Auth implementation for API authentication. The below example demonstrates a Digest-Auth request.

Request

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"

Request Headers

Key	Type	Description
`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`).

Success Response application/json

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates the request was processed successfully.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/languagesprotected

Returns a list of languages supported by POST /checkout/hosted and POST /checkout.

Request

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

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/customersprotected

Retrieves a list of customers (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of customer objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/customerprotected

Creates a customer object, which can be associated with checkouts, payments, and invoices. If a customer with the given email address already exists an update is performed.

Checkouts associated with a customer generate more transaction details, help with your accounting, and can automatically generate invoices for your customer and yourself.

Example Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params (POST)

Invoices

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

Key	Type	Description	Nullable	Mandatory
`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

Success Response application/json

{
    "customerId":"fd4f47a50c7f"
}

Success Response Attributes

Name	Type	Description	Nullable
`.customerId`	string(12)	Unique identifier of the new customer object. Store this persistently for later use.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/customerprotected

Retrieves details of a given customer.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /customer`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

PUT/customerprotected

Updates an existing customer object.

All attributes besides id and email are optional. You can submit a partial customer object including the fields you wish to update only. To unset an attribute set its value to null.

Example Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params (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.

Key	Type	Description	Nullable	Mandatory
`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

Success Response application/json

{
    "success": true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that the request was processed successfully	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/customerprotected

Deletes an existing customer object.

Example Request

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

Where payload.json is a JSON object.

Example Payload

{
    "id":"fd4f47a50c7f"
}

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /customer`.	null	mandatory

Success Response application/json

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/beneficiaryprotected

Creates a beneficiary object, which can be associated with checkouts, payments, and invoices. If a beneficiary with the given email address already exists an update is performed.

Example Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params (POST)

Key	Type	Description	Nullable	Mandatory
`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

Success Response application/json

{
    "beneficiaryId":"fd4f47a50c7f"
}

Success Response Attributes

Name	Type	Description	Nullable
`.beneficiaryId`	string(12)	Unique identifier of the new beneficiary object. Store this persistently for later use.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/beneficiaryprotected

Retrieves details of a given beneficiary.

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /beneficiary`.	null	mandatory

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

PUT/beneficiaryprotected

Updates an existing beneficiary object.

All attributes besides id and email are optional. You can submit a partial beneficiary object including the fields you wish to update only. To unset an attribute set its value to null.

Example Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params (PUT)

Key	Type	Description	Nullable	Mandatory
`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

Success Response application/json

{
    "success": true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that the request was processed successfully	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

DELETE/beneficiaryprotected

Deletes an existing beneficiary object.

Example Request

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

Where payload.json is a JSON object.

Example Payload

{
    "id":"fd4f47a50c7f"
}

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /beneficiary`.	null	mandatory

Success Response application/json

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that request was processed successfully.	false

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/beneficiariesprotected

Retrieves a list of beneficiaries (in descending order from newest to oldest).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of beneficiary objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

Webhook Concepts

Webhooks serve as a mechanism to relay information to your server in real-time when specific events occur, such as successful payments or discrepancies like underpayments during checkout.

For those looking to automate workflows within their application, webhooks are indispensable. They facilitate automatic procedures, allowing actions like confirming a customer checkout or kickstarting the delivery of goods and services.

Defining the Webhook URL

Your designated webhook URL is defined during your initial API call, be it through POST /checkout, POST /checkout/hosted, or POST /deposit-address. While you can set default webhook URLs in your API settings, any URL provided during API calls will take precedence. Upon specifying a webhook URL, our system promptly informs you through an HTTP POST for pertinent events.

Understanding Webhook Events

Webhook events are activated in scenarios such as a successful checkout completion (WEBHOOK checkout-completed) or anomalies like an underpayment (WEBHOOK checkout-underpaid). As we continually enhance our platform, stay tuned for more webhook events. You can explore a comprehensive list of webhook events in the left-hand menu.

Webhook Anatomy

Envision a webhook as a conventional HTTP POST request emanating from our end to your server. This request comprises HTTP headers, which can assist in authenticating its origin, along with an HTTP body that encapsulates the core data, detailing the webhook event type and relevant data.

Webhook Headers

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

Webhook Body

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

Webhook Payload Attributes

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

Parsing Webhook Payloads

Webhook payloads differ between event types. Your system should inspect the eventType and implement a parser for each event type you want to support.

Example: Parsing Based on Event Type (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;
}

Webhook Authentication

Add additional security to your endpoint and prevent spoofing by parsing the X-Webhook-Auth header and verifying its value.

Verify the request was sent by the Whalestack platform by creating a hash hash('sha256', YOUR_API_SECRET . WEBHOOK_REQUEST_BODY) (where . represents concatenation) and matching it against the X-Webhook-Auth header value.

Example: Authentication Check (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
}

Responding to Webhooks

Respond with HTTP 200 OK. Your server must respond with a status code of 200 in the HTTP response after it successfully parsed and persisted the webhook payload. Our system will keep sending webhook requests for up to 48 hours in increasing intervals until we detect a 200 status code. If we don't receive an HTTP status code of 200 for longer than that, the webhook expires and stops trying.

Inspecting Webhook History

Inspect webhooks sent by Whalestack along with your HTTP responses in the platform's webhook logs.

This can be extremely useful during implementation phase because it helps to debug issues in the HTTP requests and responses.

WEBHOOK EVENTcheckout-completed

This webhook event is triggered when a customer payment successfully completed, your Whalestack wallet was credited, and it is safe to ship any goods or services.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTcheckout-underpaid

This webhook event is triggered when a customer payment was captured but the payment amount was less than expected. In this situation funds have not been credited to your account and you should not ship any goods or services yet.

Unresolved payments are listed in your UI dashboard and contain action options, such as issuing a refund or accepting the underpaid checkout by issuing a custom discount.

If this is a checkout of type HOSTED and you associated a customer with this checkout, our system automatically notifies the customer with instructions on how to complete checkout and pay the remaining difference.

If this is a checkout of type SELF-HOSTED or you did not associate it with a customer, you should notify your user to send another payment covering the difference between sourceAmountRequired and sourceAmountReceived. The payment should be sent to the same deposit address originally associated with this checkout.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTunderpaid-accepted

This webhook event is triggered when you manually accept an underpaid checkout via the Whalestack platform UI or have automatic settlement of underpaid checkouts enabled in your account settings. In these events your account is credited a partial amount of the originally requested settlement amount.

The settlementAmountReceived attribute field provides the exact amount credited to your account. The sourceAmountRequired and sourceAmountReceived fields indicate by how much the checkout was underpaid.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTdeposit-pending

This webhook event is triggered when a deposit was detected on chain but is still unconfirmed and your account was not credited yet. It takes one to six blockchain confirmations for a deposit to reach finality.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTdeposit-completed

This webhook event is triggered when a deposit was successfully completed.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTswap-completed

This webhook event is triggered when a swap was successfully completed.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTswap-failed

This webhook event is triggered when a swap failed (and no balance affecting transaction occurred).

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTtransfer-completed

This webhook event is triggered when a transfer was successfully completed.

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

Webhook Payload Attributes

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

WEBHOOK EVENTtransfer-failed

This webhook event is triggered when a transfer failed (and no balance affecting transaction occurred).

Please read about webhook concepts to learn more about how to work with webhooks.

Webhook Body

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

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

Webhook Payload Attributes

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

Getting Started

Core Objects

Wallets

Checkouts

Deposits

Swaps

Transfers

Target Accounts

Customers

Beneficiaries

Helper Endpoints

Webhooks

Using the Whalestack API

Wallets and Deposits

Checkouts

Swaps and Transfers

Transparent Financial Reporting

Software Development Kits

PHP Official Whalestack SDK for PHP

Ruby Official Whalestack SDK for Ruby

NodeJS Official Whalestack SDK for NodeJS

E-Commerce Integrations

Magento Official Whalestack Extension for Magento

PrestaShop Official Whalestack Extension for PrestaShop

Shopify Official Whalestack Integration for Shopify

WooCommerce Official Whalestack Plugin for WooCommerce

WordPress Official Whalestack Plugin for WordPress

Adobe Commerce Official Whalestack Extension for Adobe Commerce

Building Checkouts

Option 1: Self-Hosted Checkouts

Option 2: Checkout Pages

Example Request

Example Charge (minimal)

Example Response (application/json)

Receiving Payments

Example Webhook (application/json)

Brand Connect by Whalestack

Branding Customization

Custom Web Domain Setup

Ensuring Secure Authentication

Securing Your API Credentials

Digest-Auth: Our Recommended Choice

Request

Request Headers

X-Digest-Signature Components

Code Example (PHP)

Code Example (Ruby)

Code Example (NodeJS)

Basic-Auth

Request

Request Headers

Code Example

IP Address Whitelisting

Software Development Kits (SDKs)

PHP Official Whalestack SDK for PHP

Ruby Official Whalestack SDK for Ruby

NodeJS Official Whalestack SDK for NodeJS

GET/networksprotected

Request

Success Response application/json

Success Response Attributes

Error Response application/json

Error Response Params

GET/assetsprotected

Request

Success Response application/json

Success Response Attributes

Error Response application/json

Error Response Params

GET/currenciesprotected

Request

Success Response application/json

Success Response Attributes

Error Response application/json

Error Response Params

POST /checkout protected

Example Request

Example Payload (Minimal)

Explanation of Above Payload Configuration

Example Payload (Full)

PHP
Official Whalestack SDK for PHP

Ruby
Official Whalestack SDK for Ruby

NodeJS
Official Whalestack SDK for NodeJS

Magento
Official Whalestack Extension for Magento

PrestaShop
Official Whalestack Extension for PrestaShop

Shopify
Official Whalestack Integration for Shopify

WooCommerce
Official Whalestack Plugin for WooCommerce

WordPress
Official Whalestack Plugin for WordPress

Adobe Commerce
Official Whalestack Extension for Adobe Commerce

PHP
Official Whalestack SDK for PHP

Ruby
Official Whalestack SDK for Ruby

NodeJS
Official Whalestack SDK for NodeJS

Example Response (as given by `POST /checkout`)