logo

BlockBee.io - Payment API Documentation (v1.3.3)

Download OpenAPI specification:Download

E-mail: info@blockbee.io



Documentation for BlockBee:
Before you start using our API, you will need an API key. To obtain one, register at BlockBee's Dashboard.

Receive a Payment

These endpoints simplify the process of generating unique payment addresses for each transaction, allowing you to track and manage payments more efficiently.

Create New Address

This method is used to generate a new address to give your clients, where they can send payments.

Please keep in mind that before making any transaction, you should check the minimum transfer limit for the specific cryptocurrency or token you want to use. If you transfer an amount that's less than the minimum limit set by BlockBee, your transaction will be rejected.

To save time and energy, it's recommended to check the pre-existing libraries for the features or functions you need before delving into the documentation.

Notice: The length of this request should not exceed 8192 characters.

Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
callback
required
string

The URL where the callbacks will be sent to. Must be a valid URL.

Notes:

  • The callback URL should be unique. The same callback URL will return the same address_in, meaning it works similarly to an ID. You can make your callback URL unique by adding GET parameters, like: ?user_id=1234. These will also be returned in the callbacks.
  • You may reuse callback URLs if for example you wish to create a deposit address_in. Note though that, once an address_in is created, if for any reason you wish to change the address, either in the parameter or at BlockBee's Dashboard, BlockBee systems will not change the address_out, meaning you will need to change your callback URL to generate a new address_in.
  • We advise you to URL Encode the callback URL, otherwise the GET parameters you add may be lost.
  • GET parameters you add to the callback URL will be sent as GET, even if you enable the post parameter.
  • It's advised to store the callback URL when making creating a new payment address if you wish to use the logs endpoint later.
  • For the complete documentation on callbacks, please refer to our callback documentation.
Example: callback=https://example.com?user_id=1124
address
string

By default, addresses are set in BlockBee's Dashboard, and to be able to set them in this parameter you need to enable the option "Address Override" when creating the API Key. If you wish to use the addresses set in the Dashboard, you can ignore this parameter and leave it empty.

The address parameter is where you specify where BlockBee will forward your payment. You can enter a single address or multiple addresses if you want to split the payment to multiple addresses.

If you're using multiple addresses, you will need to format them like this: <percentage_1>@<address_1>|<percentage_2>@<address_2> and so on (you may add up to 20 addresses to split the payment). Percentages can range from 0.0001 (0.01%) to 1.0 (100%) and must add up to 1.00 (100%).

Addresses must be valid for the ticker you're using, otherwise the API will reject the payment. For example, if you try using a Bitcoin address while requesting a USDT TRC-20 address, API will throw an error.

Notes:

  • For multiple addresses, the minimum value per transaction (see cryptocurrencies page) is multiplied by the following formula: 1 + (N - 1) / 3, where N is the number of output addresses.
  • For more information about multi-address minimums, check our knowledge base.
Example: address=bc1qhfn0lw2kdu6umgf08x54y0ha7wclsj3g5sp6t3
pending
integer
Default: 0

Set to pending=1 to enable. If enabled you will be notified of pending transactions (transactions that were sent by the customer, but yet to be confirmed by the blockchain).

Notes:

  • To prevent repeated callbacks to your systems, the response to the callback request should be *ok* in plain text.
  • For a complete list of fields sent by our system, please refer to our pending callback documentation.
Example: pending=1
confirmations
integer
Default: 1

Number of blockchain confirmations you want before receiving the confirmed callback.
Min: 1
Example: confirmations=3
post
integer
Default: 0

Set this to post=1 to enable. If enabled callback will be sent as POST.

If disabled, will default to GET.

Notes:

  • GET parameters you added to the callback URL will still be sent as GET.
Example: post=1
priority
string
Default: "default"

Allows you to set the priority with which funds should be forwarded to the provided address. It reflects the amount of fees paid to the blockchain network and can affect the speed of transaction confirmation.

Notes:

  • Only supported when using Bitcoin, Ethereum/ERC-20 and Litecoin. Priorities are different per each supported blockchain.
  • You can find the priorities to use with this endpoint, per blockchain, in our knowledge base.
Example: priority=fast
multi_token
integer
Default: 0

Allows customers to pay with any token supported by BlockBee API, even if the token is different from what the user initially specified.

However, you should ensure that your Wallet supports the tokens you expect customers to pay with and that your system can handle price conversions. For example, if a customer wishes to receive 1000 USDT (or equivalent) and a client sends 1000 TRX, the system should be able to handle that scenario.

Notes:

  • Make sure the wallet you're using supports all the tokens supported by BlockBee before enabling this parameter.
  • If you are using your favorite exchange's deposit address to receive the funds, it's advised to leave this parameter disabled, since sometimes the deposit addresses may differ between blockchains and tokens.
  • Disabled by default, use multi_token=1 to enable it.
  • Available only for TRC-20, BEP-20, ERC-20 and POLYGON blockchains.
  • If disabled and the customer send a different token from the initially specified, BlockBee API will ignore these funds.
  • If enabled on unsupported blockchains, API won't throw an error. Instead it just ignores it.
  • For more information about this parameter, check our knowledge base.
Example: multi_token=1
multi_chain
integer
Default: 0

This parameter is only for Ethereum/ERC-20 and EVM-Compatible blockchains. Currently EVM-Compatible blockchains we support are BSC (BEP-20), and POLYGON.

This works since these blockchains have the same address type, e.g 0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d. Wallets (e.g Trust Wallet or Exodus Wallet) that support them usually provide the same address for each chain, which means if you receive the funds no matter which blockchain they were sent through, if Ethereum/ERC-20 or EVM-Compatible.

By enabling this parameter, BlockBee API will process the funds if received in the created address in any of those blockchains, provided we support the specified token on them (e.g USDT is supported on all, so if customer was supposed to send on ERC-20 and sent on Polygon, BlockBee API will still process the transaction).

If you wish for BlockBee API to process any token sent by the customer, you must enable multi_token.

Notes:

  • Make sure the wallet you're using supports all the tokens/blockchains supported by BlockBee before enabling this parameter.
  • If you are using your favorite exchange's deposit address to receive the funds, it's advised to leave this parameter disabled, since sometimes the deposit addresses may differ between blockchains and tokens.
  • Available only for BEP-20, Ethereum/ERC-20 and POLYGON blockchains.
  • Disabled by default, use multi_chain=1 to enable it.
  • If enabled on unsupported blockchains, API won't throw an error. Instead it just ignores it.
  • For more information about this parameter, check our knowledge base.
Example: multi_chain=1
convert
integer
Default: 0

If enabled, returns the converted value converted to FIAT in the callback, with the parameters value_coin_convert and value_forwared_coin_convert.

Notes:

  • Disabled by default, use convert=1 to enable it.
  • The value of the fields are json-encoded.
Example: convert=1
Responses
200

Address was created.

Response Schema: application/json
address_in
string

Address generated by our API. You must provide it to your customer in order to receive payments.
address_out
string

Your address(es), where the payment will be forwarded to, should be the same address(es) you provided.
callback_url
string

The callback URL you provided.
priority
string

The confirmation priority you requested.
status
string

Status of the request. Should be `success` if the request didn't fail.
400

Error creating address.

get/{ticker}/create/
Request samples 
Response samples 
application/json
{
  • "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu",
  • "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)\n\n{1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)\n",
  • "callback_url": "https://example.com/invoice/1234?payment_id=5678",
  • "priority": "default",
  • "status": "success"
}
Check Payment Logs


This method provides information and callbacks for addresses created through the create endpoint.


It returns a list of callbacks made at the specified callbacks parameter, and allows to track payment activity and troubleshoot any issues.


Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
callback
required
string


The URL of the callback. Must be the same URL provided when the payment was created.


Notes: 


    

  • It's advised to store the callback URL when creating a new payment address if you wish to use this endpoint later.
    • 

  • We advise URL Encoding the callback when making the request. If using one of our libraries there's no need for it.
    • 



 
 Example:  callback=https://example.com?user_id=1124
Responses 
200
List of payments sent to this callback.


Response Schema: application/json
address_in
string


Generated address for the callback URL provided.

 
address_out
string


Your address(es), where the payment will be forwarded to, should be the same address(es) you provided.


Notes:


    

  • Response will be {1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)
    • 



 
callback_url
string


The callback URL you provided.

 
status
string


Status of the request. Should be `success` if the request didn't fail.

 
notify_pending
boolean


Shows if you enabled the pending callback when creating the address.

 
notify_confirmations
integer


Number of confirmations required before sending the confirmed callback.

 
priority
string


The confirmation priority you requested.

 
Array of objects (log_items) 


List of payments made to this address, together with the logs of the callbacks to your system.

 
400
Your request couldn't be processed, please try again later.


404
No request or no payment callbacks found.


get/{ticker}/logs/
Request samples 
Response samples 
application/json
{}
Utils
Create custom and specially tailored UIs for your business with the help of these endpoints.

These endpoints provide you with essential features to make conversions, get estimates, retrieve information, and generate QR codes.


Service Information
Endpoint that provides information regarding BlockBee API Service (e.g supported blockchains, cryptocurrencies and tokens).


Request 
query Parameters
prices
integer
 Default:  0


If you want to receive also the coin prices, set to 1 to enable the prices.

 
 Example:  prices=1
Responses 
200
Info fetched successfully.


Response Schema: application/json
object
 
object
 
get/info/
Request samples 
Response samples 
application/json
{
  • "btc": {
    },
  • "trc20": {
    }
}
Check Coin Information
Use this endpoint to retrieve information about the cryptocurrency you intend to use. This endpoint provides detailed information about the cryptocurrency/token provided in the ticker parameter.


Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
prices
integer
 Default:  1


If you want to receive also the coin prices, set to 1 to enable the prices.

 
Responses 
200
Info fetched successfully.


Response Schema: application/json
status
string


Status of the request. Should be `success` if the request didn't fail.

 
coin
string


Human readable name of the currency.

 
ticker
string


Ticker of the currency.

 
minimum_transaction
integer
 Deprecated 


Minimum transaction value for this currency in integer (meant to help with precise calculations in some programming languages), values below this value are disregarded by BlockBee API.

 
minimum_transaction_coin
string


Minimum transaction value for this currency, values below this value are disregarded by BlockBee API.

 
minimum_fee
integer
 Deprecated 


BlockBee currently doesn't charge a minimum fee.

On Bitcoin and Bitcoin Cash there's a minimum transaction fee of 546 Satoshis due to dust threshold. For Litecoin it's 5460 Litoshis.


Notes:


    

  • Value in integer meant to help with precise calculations on some programming languages.
    • 



 
minimum_fee_coin
string


BlockBee currently doesn't charge a minimum fee.

On Bitcoin and Bitcoin Cash there's a minimum transaction fee of 546 Satoshis due to dust threshold. For Litecoin it's 5460 Litoshis.

 
fee_percent
number


Fee percentage for this currency.

 
network_fee_estimation
string


Estimation of the blockchain fee for this cryptocurrency/token.
**Notes:**
  * This value is informative. To obtain a blockchain fee estimation use the estimate endpoint instead.

 
prices
object


Object with the exchange rate of this currency in various FIAT currencies.



Keys are the names of the currencies, values are the exchange rates.


Updated every 5 minutes.


 
prices_updated
string


Datetime of the last price update.

 
400
Error fetching info.


get/{ticker}/info/
Request samples 
Response samples 
application/json
{
  • "status": "success",
  • "coin": "Bitcoin",
  • "ticker": "btc",
  • "minimum_transaction": 8000,
  • "minimum_transaction_coin": "0.00008000",
  • "minimum_fee": "200",
  • "minimum_fee_coin": "0.00000546",
  • "fee_percent": "1.00",
  • "network_fee_estimation": "0.006548837643539048",
  • "prices": "{'DKK': '56281.94', 'CAD': '10985.14', 'AED': '30517.01', 'BRL': '34243.36', 'USD': '8308.47', 'MXN': '160193.26', 'CNY': '58740.88', 'INR': '591471.72', 'JPY': '899719.16', 'HKD': '65173.93', 'GBP': '6616.08', 'EUR': '7535.35'}",
  • "prices_updated": "2019-10-14T13:00:09.585Z"
}
Generate QR Code
This method generates a base64-encoded QR Code image for payments.


Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
address
required
string


The payment address (address_in from our system).

 
value
integer


Value to request the user. Optional. 


Notes: 


    

  • If left empty the QR Code will only contain the address.
    • 

  • It is important to mention that the value parameter might not be compatible with many exchanges and wallets. While it works with Trust and Exodus wallets, some user wallets or exchanges may only read the address and ignore the value field (inserting both the address and the value in the address field). Hence, it is advised to use the value field cautiously and be aware that it may not be recognized by all wallets and exchanges, causing some confusion to the customer.
    • 



 
size
integer
 Default:  512


Size of the QR Code image in pixels.

Min: 64

Max: 1024

 
 Example:  size=300
Responses 
200
The QR Code.


Response Schema: application/json
status
string


Status of the request. Should be success if the request didn't fail.

 
qr_code
string


Base64-encoded image of the QR Code. 


Here is an example of how to use this:


<img src="data:image/png;base64,{qr_code}" alt="Payment QR Code"/>



You may use it in every situation where is supported, just don't forget to add data:image/png;base64, before the qr_code.


 
payment_uri
string


Payment URI useful if you want to make a clickable button.

 
get/{ticker}/qrcode/
Request samples 
Response samples 
application/json
{
  • "status": "success",
  • "qr_code": "...",
  • "payment_uri": "..."
}
Estimate Blockchain Fees


This method allows you to estimate blockchain fees to forward a transaction to your wallet address.


Notes:


    

  • This is an estimation only, and might change significantly when the transaction is processed by the blockchain. BlockBee is not responsible if blockchain fees differ from this estimation when forwarding the funds.
    • 

  • Does not include BlockBee's fees.
    • 



Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
addresses
integer
 Default:  1


The number of addresses to forward the funds to. Should be the same you set in the BlockBee's Dashboard or in the address parameter.


Notes:


    

  • The higher the number of addresses, the higher the blockchain fee will be.
    • 



 
 Example:  addresses=3
priority
string
 Default:  "default"


This parameter allows you to set the priority with which funds should be forwarded to the provided address. 
It reflects the amount of fees paid to the blockchain network and can affect the speed of transaction confirmation. 
It's different per currency/network.


Notes:


    

  • You can find the priorities to use with this endpoint, per blockchain, in our knowledge base.
    • 

  • Only supported when using Bitcoin, Ethereum/ERC-20 and Litecoin.
    • 



 
 Example:  priority=fast
Responses 
200
Estimated cost.


Response Schema: application/json
status
string


Status of the request. Should be `success` if the request didn't fail.

 
estimated_cost
integer


Estimated cost in the coin.

 
estimated_cost_currency
object


Object with the estimated cost in various FIAT currencies.


Keys are the names of the currencies, values are the estimated costs.


 
400
Your request couldn't be processed, please try again later


get/{ticker}/estimate/
Request samples 
Response samples 
application/json
{
  • "status": "success",
  • "estimated_cost": "0.00001",
  • "estimated_cost_currency": "{'USD': '0.09', 'EUR': '0.08', 'GBP': '0.07', 'CAD': '0.11', 'JPY': '10.21', 'AED': '0.33', 'DKK': '0.58', 'BRL': '0.46', 'CNY': '0.56', 'HKD': '0.69', 'INR': '6.67', 'MXN': '1.81', 'UGX': '310.74', 'PLN': '0.35', 'PHP': '4.56', 'CZK': '1.91', 'HUF': '27.95', 'BGN': '0.15', 'RON': '0.39', 'LKR': '18.02'}"
}
Convert Prices
With this method, you can effortlessly convert prices between FIATs and cryptocurrencies, or even between different cryptocurrencies.


Note:


    

  • Prices are fetched every 5 minutes from CoinMarketCap.
    • 



Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
value
required
number


Value you wish to convert in the cryptocurrency/token of the ticker you are using.

 
 Example:  value=10
from
required
string


Specify the currency you wish to convert from, whether it is FIAT or cryptocurrency.


Check our full list of supported cryptocurrencies.


FIAT currencies supported in this list are (if the FIAT currency you wish to use is not in this list, you may contact us in order to add it to our service):


    

  • (USD) United States Dollar
    • 

  • (EUR) Euro
    • 

  • (GBP) Great Britain Pound
    • 

  • (CAD) Canadian Dollar
    • 

  • (JPY) Japanese Yen
    • 

  • (AED) UAE Dollar 
    • 

  • (MYR) Malaysian Ringgit 
    • 

  • (IDR) Indonesian Rupiah
    • 

  • (THB) Thai Baht 
    • 

  • (CHF) Swiss Franc
    • 

  • (COP) Colombian Peso
    • 

  • (SGD) Singapore Dollar 
    • 

  • (RUB) Russian Ruble
    • 

  • (ZAR) South African Rand
    • 

  • (TRY) Turkish Lira
    • 

  • (LKR) Sri Lankan Rupee
    • 

  • (XAF) CFA Franc 
    • 

  • (RON) Romanian Leu
    • 

  • (BGN) Bulgarian Lev 
    • 

  • (HUF) Hungarian Forint 
    • 

  • (CZK) Czech Koruna 
    • 

  • (PHP) Philippine Peso
    • 

  • (PLN) Poland Zloti
    • 

  • (UGX) Uganda Shillings
    • 

  • (MXN) Mexican Peso
    • 

  • (INR) Indian Rupee
    • 

  • (HKD) Hong Kong Dollar
    • 

  • (CNY) Chinese Yuan
    • 

  • (BRL) Brazilian Real
    • 

  • (DKK) Danish Krone
    • 



 
 Example:  from=usd
Responses 
200
The converted value.


Response Schema: application/json
value_coin
number
Converted value for the selected currencies.


 
exchange_rate
number
The exchange rate between the 2 currencies.


 
status
string
Status of the request. Should be success if the request didn't fail.


 
400
Your request couldn't be processed, please try again later.


get/{ticker}/convert/
Request samples 
Response samples 
application/json
{
  • "value_coin": "0.01",
  • "exchange_rate": "47000",
  • "status": "success"
}
Callbacks
These callbacks are dispatched by our API to your platform when a user sends a payment to the address generated by our system. 
Your platform should be able to handle these callbacks, which are requests made to the URL provided in the callback parameter.



Each callback is sent with an additional header, x-ca-signature. 
This is a base64-encoded 1024-bit RSA-SHA256 signature of the callback. 
The specific data signed depends on the type of callback you're receiving. 
For callbacks sent via GET, the entire request URL to your system (including all GET parameters) is signed. 
If the callback is sent via POST, then the entire body of the request is signed. 
The Public Key for verification can be retrieved from this this endpoint.



Check our knowledge base to learn how to verify the callback with code samples.



BlockBee API will stop sending callbacks under one of these two circumstances:


    

  • Your system responds with an *ok* message or an HTTP 200 status code, indicating that the callback has been successfully received and processed.
    • 

  • In case your system fails to response successfully to the callback, BlockBee API will retry sending the callback in a specific timing. Regarding the timing of these callbacks, we employ an exponential backoff strategy. Initially, the system waits for 6 minutes before making the first retry attempt. With each subsequent attempt, this wait time doubles, hence increasing the time between attempts in an exponential manner until the transaction is older than 3 days.
    • 



Callbacks are sent everytime funds are received in a generated address. If you're having issues receiving our callbacks it might be due to these factors:


    

  • You sent the wrong token to the address, for example, created a USDt transaction and sent TRX to the address, leading to our system ignoring the transaction.
    • 

  • The callback URL you provided in the callback parameter is not reachable online.
    • 

  • You might have some security system in place (e.g Cloudflare protection) that's preventing our callbacks reaching your platform.
    • 



Note: We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47


Pending CallbackWebhook 
Callback issued when a client's transaction is pending confirmation.


Notes: 


    

  • Only issued if you have requested to be notified of pending transactions. Only sent when post parameter is set to 1, when creating a new address.
    • 

  • Sent via POST if post=1 parameter set, else sent via GET.
    • 



Request 
query Parameters
uuid
string


This is an unique identifier to each payment your clients have made, so you can easily track any duplicate callbacks sent, in the case our system doesn't mark the callback as successful.

 
 Example:  uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2
address_in
string


Address generated by BlockBee, where your customer sent the payment.

 
 Example:  address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
address_out
string


Address(es) where BlockBee forwarded the payment.

 
 Example:  address_out=1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)<br/>
{1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)

txid_in
string


Transaction hash of your customer's payment.

 
 Example:  txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
confirmations
integer


Number of confirmations of the current transaction.

 
 Example:  confirmations=1
value
integer
 Deprecated 


Value of the payment in integer.


Notes


    

  • For some stable coins (e.g USDT or BUSD), this field always come rounded to 'cents' (two decimals), meaning you must always divide it by 100. Example: If value=1054, 1054/100=10.54.
    • 

  • It's recommended to use the value_coin field instead.
    • 

  • Field meant to help with precise calculations on some programming languages.
    • 



 
 Example:  value=50000
value_coin
number


This is the payment amount sent by your customer before any fees are deducted.


Notes:



 
 Example:  value_coin=0.05
value_coin_convert
string


Converted value to various FIAT currencies of the value_coin.


Notes: 


    

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
    • 

  • Response is json-encoded.
    • 



 
 Example:  value_coin_convert={"USD": "3.20", "EUR": "3.05", "GBP": "2.62", "CAD": "4.16", "JPY": "431.90", "AED": "11.77", "DKK": "22.67", "BRL": "16.52", "CNY": "21.43", "HKD": "25.16", "INR": "249.97", "MXN": "64.95", "UGX": "11975.46", "PLN": "14.25", "PHP": "173.14", "CZK": "75.37", "HUF": "1220.10", "BGN": "5.94", "RON": "15.02", "LKR": "1153.30", "TRY": "55.54", "ZAR": "51.36", "RUB": "181.24"}
coin
string


Ticker of the coin used for the payment: ['btc', 'bch', 'ltc'', 'eth', 'trx']


For ERC-20 (ETH) Tokens, this parameter will be erc20_ + the ticker of the token, e.g erc20_usdt


For TRC-20 (Tron) Tokens, this parameter will be trc20_ + the ticker of the token, e.g trc20_usdt


For BEP-20 (BSC) Tokens, this parameter will be bep20_ + the ticker of the token, e.g bep20_usdt


For Polygon Tokens, this parameter will be polygon_ + the ticker of the token, e.g polygon_usdt


 
 Example:  coin=btc
price
number


Coin price in USD at the time of the callback.

 
 Example:  price=55.59
pending
integer


Being the pending callback, this value should be 1.

 
 Example:  pending=1
Responses 
200
Expected response from your server.


Response Schema: text/plain
string
 
Response samples 
text/plain
*ok*
Confirmed CallbackWebhook 
Callback issued when a client's transaction has been confirmed by the network.


Request 
query Parameters
uuid
string


This is an unique identifier to each payment your clients have made, so you can easily track any duplicate callbacks sent, in the case our system doesn't mark the callback as successful.

 
 Example:  uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2
address_in
string


Address generated by BlockBee, where your customer sent the payment.

 
 Example:  address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
address_out
string


Address(es) where BlockBee forwarded the payment.

 
 Example:  address_out=1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)<br/>
{1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)

txid_in
string


Transaction hash of your customer's payment.

 
 Example:  txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
txid_out
string


Transaction hash of the payment forwarded to your address(es) by BlockBee.

 
 Example:  txid_out=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
confirmations
integer


Number of blockchain confirmations of the current transaction.


Notes:


    

  • This parameter will only appear in the confirmed callback.
    • 



 
 Example:  confirmations=1
fee
integer
 Deprecated 
BlockBee fee in integer. Field meant to help with precise calculations on some platforms.


Notes:


    

  • Field meant to help with precise calculations on some programming languages.
    • 



 
 Example:  fee=500
value
integer
 Deprecated 
Value of the payment in integer.


Notes


    

  • Field meant to help with precise calculations on some programming languages.
    • 

  • It's recommended to use the value_coin field instead.
    • 



 
 Example:  value=50000
value_coin
number


This is the payment amount sent by your customer before any fees are deducted.


Notes:



 
 Example:  value_coin=0.05
value_coin_convert
string


Converted value to various FIAT currencies of the value_coin.


Notes: 


    

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
    • 

  • Response is json-encoded.
    • 



 
 Example:  value_coin_convert={"USD": "3.20", "EUR": "3.05", "GBP": "2.62", "CAD": "4.16", "JPY": "431.90", "AED": "11.77", "DKK": "22.67", "BRL": "16.52", "CNY": "21.43", "HKD": "25.16", "INR": "249.97", "MXN": "64.95", "UGX": "11975.46", "PLN": "14.25", "PHP": "173.14", "CZK": "75.37", "HUF": "1220.10", "BGN": "5.94", "RON": "15.02", "LKR": "1153.30", "TRY": "55.54", "ZAR": "51.36", "RUB": "181.24"}
value_forwarded
integer
 Deprecated 


Value forwarded to you, after fees in integer. Field meant to help with precise calculations on some programming languages.

 
 Example:  value_forwarded=50000
value_forwarded_coin
number


Value forwarded to you, after fees deducted.

 
 Example:  value_forwarded_coin=0.05
value_forwarded_coin_convert
string


Converted value to various FIAT currencies of the value_forwarded_coin.


Notes: 


    

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
    • 

  • Response is json-encoded.
    • 



 
 Example:  value_forwarded_coin_convert={"USD": "3.17", "EUR": "3.01", "GBP": "2.59", "CAD": "4.12", "JPY": "427.16", "AED": "11.64", "DKK": "22.41", "BRL": "16.33", "CNY": "21.20", "HKD": "24.88", "INR": "247.19", "MXN": "64.25", "UGX": "11855.29", "PLN": "14.08", "PHP": "171.25", "CZK": "74.50", "HUF": "1206.19", "BGN": "5.88", "RON": "14.86", "LKR": "1140.51", "TRY": "54.93", "ZAR": "50.82", "RUB": "179.22"}
fee_coin
number


Fee paid to BlockBee, deducted from value_coin amount.

 
 Example:  fee_coin=0.02
coin
string


Ticker of the coin used for the payment: ['btc', 'bch', 'ltc'', 'eth', 'trx']


For ERC-20 (ETH) Tokens, this parameter will be erc20_ + the ticker of the token, e.g erc20_usdt


For TRC-20 (Tron) Tokens, this parameter will be trc20_ + the ticker of the token, e.g trc20_usdt


For BEP-20 (BSC) Tokens, this parameter will be bep20_ + the ticker of the token, e.g bep20_usdt


For Polygon Tokens, this parameter will be polygon_ + the ticker of the token, e.g polygon_usdt


 
 Example:  coin=btc
price
number


Coin price in USD at the time of the callback.

 
 Example:  price=55.59
pending
integer


Being the confirmed callback, this value should be 0.


Payment was confirmed by the blockchain.


 
 Example:  pending=0
Responses 
200
Expected response from your server.


The callback will be marked as successful when it receives the following response from your server.


Response Schema: text/plain
string
 
Response samples 
text/plain
*ok*
Checkout - Payments
Documentation on how to use our ready-made Checkout page to receive cryptocurrency payments.


Check the demo!


Note:



Create a Checkout Payment
This method allows you to request a new Payment link.


Request 
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
redirect_url
required
string


URL where your customers will be redirected to after successfully completing the payment. 


The success_token token will be added as GET parameter to this URL, 
together with any GET parameter you might have provided in your redirect_url, which can be used to validate the payment.


Notes:


    

  • Even though it's possible to use this page to validate the payment, we recommend using the notify_url
    • 



 
 Example:  redirect_url=https://example.com/success/?order_id=12345
value
required
number


Value of the order in the FIAT currency set in your Payment Settings at BlockBee's Dashboard.

 
 Example:  value=10
item_description
string


Description of the product or service being paid. This information will appear on the Checkout page.

 
 Example:  item_description=Description of the product you are selling
expire_at
number
Epoch time in seconds at which the Checkout payment will expire.


Notes:


    

  • Minimum is 1h. 
    • 

  • If not set, the Payment link will never expire.
    • 



 
 Example:  expire_at=1673438907
notify_url
string


URL where our system will send a payment notification (IPN), when a deposit is made.


Notes: 


    

  • We advise you to URL Encode the notify URL, otherwise the GET parameters you add may be lost.
    • 

  • GET parameters you add to the notify URL will be sent as GET, even if you enable the post parameter.
    • 

  • For a complete list of fields sent by our system, please refer to our IPN for Deposits documentation.
    • 

  • To prevent repeated IPNs to your systems, the response to the IPN request should be *ok* in plain text.
    • 



 
post
number
 Default:  0


Set this to 1 if you wish to receive the IPN as a POST request.


If set to 0, API will default to GET.


Notes:


    

  • GET parameters you added to the notify_url URL will still be sent as GET.
    • 



 
 Example:  post=1
Responses 
200
Payment URL was created successfully.


Response Schema: application/json
status
string


Status of the request. Should be success if the request didn't fail.

 
success_token
string


Security token only known by your system and BlockBee so you can make sure the order was actually paid by your customer.

 
payment_url
string


Payment URL where you should redirect your customer.

 
400
Your request couldn't be processed, please try again later


get/checkout/request/
Request samples 
Response samples 
application/json
{}
IPN for PaymentsWebhook 


IPN issued when the payment has been confirmed by the
network. Will be sent to the URL provided in notify_url.
 


Notes:


    

  • Sent via POST if post=1 parameter set, else sent via GET
    • 

  • We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47
    • 

  • To prevent repeated IPNs sent to your systems, please respond with *ok* to our IPNs.
    • 



Request 
query Parameters
payment_url
string


Payment link where the payment came from.

 
 Example:  payment_url=https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
redirect_url
string


Redirect URL provided when requesting a new payment link.

 
 Example:  redirect_url=https://example.com/success/?order_id=12345
value
number


Amount in FIAT you requested when creating the payment link.

 
 Example:  value=20000
success_token
string


Security token only known to your systems so you can make sure the order was actually paid by your customer.

 
 Example:  success_token=fG78jtx96ugjtu0eIbeLmFB9z0feJf9NfG78jtx96ugjtu0eIbeLmFB9z0feJf9N
currency
string


FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.

 
 Example:  currency=usd
is_paid
string
 Default:  1


Should always be 1.

 
 Example:  is_paid=1
paid_amount
string


Amount paid in cryptocurrency.


Notes:


    

  • The cryptocurrency/token used to make the payment is described in the parameter paid_coin.
    • 



 
 Example:  paid_amount=1.23
paid_coin
string


Cryptocurrency/token used to make the payment.


Notes:


    

  • The amount paid will be available in the parameter paid_amount.
    • 



 
 Example:  paid_coin=btc
exchange_rate
number


Exchange rate at the time of the payment.

 
 Example:  exchange_rate=20000
txid
string


Transaction hash(es) of your client's payment(s).


Notes:


    

  • If multiple means your customer had to make multiple transactions to fulfill the payment, since the Checkout page supports partial payments.
    • 



 
 Example:  txid=0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32,0x6e8b278e3db1948d2c694b7f709dd4e864ae80d516970ebfd05a98629b6efe15,0x387c6250b3e86f7372b9c49d00497f1b26b373d40801c9e60a97ef5124b6b75c
address
string


Address generated by BlockBee where your client's payment was received.

 
 Example:  address=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
status
string


Status of the transaction.

 
 Example:  status=done
Responses 
200
Expected response from your server.


The callback will be marked as successful when it receives the following response from your server.


Response Schema: text/plain
string
 
Response samples 
text/plain
*ok*
Checkout - Deposits
Documentation on how to use our ready-made Checkout page to receive cryptocurrency deposits.


Check the demo!


Note:



Create a Checkout Deposit
This method allows you to create a new Deposit link.


Request 
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
notify_url
required
string


URL where our system will send a payment notification (IPN), when a deposit is made.


Notes: 


    

  • We advise you to URL Encode the notify URL, otherwise the GET parameters you add may be lost.
    • 

  • GET parameters you add to the notify URL will be sent as GET, even if you enable the post parameter.
    • 

  • For a complete list of fields sent by our system, please refer to our IPN for Deposits documentation.
    • 

  • To prevent repeated IPNs to your systems, the response to the IPN request should be *ok* in plain text.
    • 



 
 Example:  notify_url=https://example.com?user_id=1124
item_description
string


Description of the product or service being paid. This information will appear on the Checkout page.

 
post
number
 Default:  0


Set this to 1 if you wish to receive the IPN as a POST request.


If set to 0, API will default to GET.


Notes:


    

  • GET parameters you added to the notify_url URL will still be sent as GET.
    • 



 
 Example:  post=1
Responses 
200
Deposit URL was created successfully.


Response Schema: application/json
status
string


Status of the request. Should be success if the request didn't fail.

 
payment_url
string


Payment URL where you should redirect your customer.

 
400
Your request couldn't be processed, please try again later


get/deposit/request/
Request samples 
Response samples 
application/json
{}
IPN for DepositsWebhook 
IPN issued when the deposit has been confirmed by the
network. Will be sent to the URL provided in notify_url.


Notes:


    

  • Sent via POST if post=1 parameter set, else sent via GET
    • 

  • We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47
    • 

  • To prevent repeated IPNs sent to your systems, please respond with *ok* to our IPNs.
    • 



Request 
query Parameters
uuid
string


This is an unique identifier to each payment your clients have made, so you can easily track any duplicate IPNs sent, in the case our system doesn't mark the IPN as successful.


Notes:


    

  • Our system will mark the IPN as successful as long your system replies with a plain text page containing only a *ok.
    • 



 
 Example:  uuid=afe11bea-768b-47ae-ba0f-907379fbe5ef
txid
string


Transaction hash of your client's deposit.

 
 Example:  txid=7.568663445102688e+76
address
string


Address generated by BlockBee where your client's payment was received.

 
 Example:  address=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
payment_url
string


Deposit link where the deposit came from.

 
 Example:  payment_url=https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
currency
string


FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.

 
 Example:  currency=usd
paid_amount
string


Amount paid in cryptocurrency.


Notes:


    

  • The cryptocurrency/token used to make the payment is described in the parameter paid_coin.
    • 



 
 Example:  paid_amount=1.23
paid_amount_fiat
string


Amount paid in the FIAT currency described in the parameter currency.

 
 Example:  paid_amount_fiat=21234.32
paid_coin
string


Cryptocurrency/token used to make the payment.


Notes:


    

  • The amount paid will be available in the parameter paid_amount.
    • 



 
 Example:  paid_coin=btc
status
string


Status of the transaction.

 
 Example:  status=done
Responses 
200
Expected response from your server

The callback will be marked as successful when it receives the following response from your server


Response Schema: text/plain
string
 
Response samples 
text/plain
*ok*
Payouts
Our Payouts function allows you to send funds to up 25 different addresses with a single transaction. You can use the API to create Payout Requests and then visit BlockBee Dashboard to select the Payout Requests you wish to fulfill and to create a Payout.

Check our knowledge base to learn to create a Payout.


In the video tutorial below you can see how to proceed to fulfill a Payout:




Note:
  Currently this feature is only available for Ethereum (ERC-20), BSC (BEP-20), Polygon and Tron (TRC-20).


Create a Payout Request
Use this method to create a new Payout Request, which is a request for a payment you wish to send to your customer. Once you have created the Payout Request, you can fulfill it using BlockBee's Dashboard by sending multiple payments to all your customers.


This process streamlines the payment process, allowing you to handle multiple transactions efficiently and accurately.


Request 
path Parameters
ticker
required
string


The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. 
It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.


For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.


Notes: 



 
 Example:  btc
query Parameters
apikey
required
string


API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

 
address
required
string


Provide the destination address where you want the Payout to be sent.

 
 Example:  address=TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF
value
required
number


Amount you wish to send to the provided destination address.

 
 Example:  value=1.34
Responses 
200
Payout Request created successfully


Response Schema: application/json
status
string
Status of the request. Should be success if the request didn't fail.


 
400
Your request couldn't be processed, please try again later


get/{ticker}/payout/
Request samples 
Response samples 
application/json
{
  • "status": "success"
}