Search documentation

Search across BlockBee docs, API endpoints, webhooks and guides.

Create a Checkout Payment Link

View as Markdown

This method allows you to request a new Payment link.

Notes:

  • Supports partial payments and prompts the customer to complete the remaining balance if the full amount isn't paid.

Method: GET

Path: https://api.blockbee.io/checkout/request/

Parameters

Query Parameters

apikeystring•Required

API Key provided by BlockBee's Dashboard.

Unsure how to get yours? Check this tutorial.

Note: The API key can also be sent as a header named apikey.

redirect_urlstring•Required

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
  • Harden your redirect with a secret. Add an unguessable value unique to each payment (for example ?nonce=a1b2c3...) and store it on your side. BlockBee appends it to the redirect, so verify it matches before you treat the returning customer as legitimate.
Example:https://example.com/success/?order_id=12345

valuestring•Required

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

Example:10

currencystring

Set the FIAT currency used in the value parameter.

Note: Will override the FIAT currency set in your Payment Settings at BlockBee's Dashboard.

Supported FIAT currencies:

  • (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
  • (SGD) Singapore Dollar
  • (RUB) Russian Ruble
  • (ZAR) South African Rand
  • (TRY) Turkish Lira
  • (LKR) Sri Lankan Rupee
  • (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
  • (TWD) New Taiwan Dollar
  • (AUD) Australian Dollar
  • (NGN) Nigerian Naira
  • (SEK) Swedish Krona
  • (NOK) Norwegian Krone
  • (UAH) Ukrainian Hryvnia
  • (VND) Vietnamese Dong

Supported cryptocurrencies (for conversion):

  • (BTC) Bitcoin
  • (ETH) Ethereum
  • (USDT) Tether USDt
  • (USDC) USD Coin
  • (SOL) Solana

...and many more listed on our cryptocurrencies page (eg: currency=btc).

Example:eur

item_descriptionstring

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

Example:Order #1234

customer_namestring

Your customer's name. Will be returned in the payment notification (webhook).

Example:John Doe

customer_emailstring

Your customer's email. Will be returned in the payment notification (webhook).

Example:[email protected]

expire_atnumber

Epoch time in seconds at which the Checkout payment will expire.

Notes:

  • Minimum is 1h
  • If not set, the Payment link will never expire
  • Timestamp must be in seconds
Example:1673438907

notify_urlstring

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

Notes:

  • URL-encode the notify URL, otherwise query parameters may be dropped
  • 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, See the webhook documentation
  • To prevent repeated IPNs to your systems, the response to the IPN request should be *ok* in plain text
  • Harden your webhook with a secret. Add an unguessable value unique to each request (for example ?nonce=a1b2c3...) and store it on your side. BlockBee returns it unchanged in every notification, so verify it in your webhook and reject any notification whose value you don't recognize. Use this together with webhook signature verification.
Example:https://example.com/callback/?order_id=12345

postnumber

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:1

Returns

Returns the payment link response. Returns an error if there's there's a missing required parameter of if you didn't configure the payment settings correctly.

statusstring•Required

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

payment_idstring•Required

ID of the checkout payment. May be used with the logs endpoint.

success_tokenstring•Required

A unique token that is passed to your redirect_url to verify the payment's authenticity on your end.

payment_urlstring•Required

The URL for the hosted checkout page where the user can complete the payment.