# BlockBee Documentation — Full Corpus Source: https://docs.blockbee.io Index: https://docs.blockbee.io/llms.txt Generated: 2026-06-06T16:12:34.692Z This file concatenates every documentation page as LLM-friendly markdown. Each section begins with a `# ` heading and a `> Source: <url>` line. --- # Quickstart > Source: https://docs.blockbee.io/get-started > Description: Get from zero to a working crypto payment in about 10 minutes. Create an API key, generate a payment address, set up a webhook, and verify it with a small Litecoin test. # Quickstart Get from zero to a working crypto payment in about 10 minutes. You'll create a real BlockBee payment address, point it at a test webhook, and verify the integration end-to-end with a small Litecoin payment. > **INFO: What you'll need** >- A free BlockBee account ([register here](https://dash.blockbee.io/register)). > - About $1 of Litecoin (LTC) in any wallet — used in step 4 to verify the webhook fires. > - 10 minutes. Already know which integration you want? Skip to [Choose your integration](/get-started/integrations). ## 1. Get an API key 1. [Sign up for a free BlockBee account](https://dash.blockbee.io/register). 2. Configure a Litecoin receiving address on the [Addresses page](https://dash.blockbee.io/profile/addresses). BlockBee forwards confirmed payments to this wallet. 3. Generate a key on the [API Keys page](https://dash.blockbee.io/profile/api-keys) and copy it. ![The BlockBee dashboard API Keys page](/assets/images/quickstart/api-keys-page.jpg) *Generate and copy your API key from the dashboard* ```bash export BLOCKBEE_KEY="your_api_key_here" ``` > **INFO** >A V1 key is sufficient for this Quickstart. [V2 keys](/get-started/authentication) unlock the self-custodial wallet and payouts, covered later. ## 2. Create a payment address Call the [Create payment address](/api/create-payment-address) endpoint to generate a fresh Litecoin address. Use a placeholder callback for now; you'll update it in step 3. ```bash curl "https://api.blockbee.io/ltc/create/?callback=https://example.com/placeholder&apikey=$BLOCKBEE_KEY" ``` ```javascript const apikey = process.env.BLOCKBEE_KEY; const url = `https://api.blockbee.io/ltc/create/?callback=https://example.com/placeholder&apikey=${apikey}`; const res = await fetch(url); const data = await res.json(); console.log(data); ``` ```python import os, requests apikey = os.environ["BLOCKBEE_KEY"] res = requests.get("https://api.blockbee.io/ltc/create/", params={ "callback": "https://example.com/placeholder", "apikey": apikey, }) print(res.json()) ``` ```php <?php $apikey = getenv('BLOCKBEE_KEY'); $query = http_build_query([ 'callback' => 'https://example.com/placeholder', 'apikey' => $apikey, ]); $res = file_get_contents("https://api.blockbee.io/ltc/create/?$query"); print_r(json_decode($res, true)); ``` The response looks like this: ```json { "status": "success", "address_in": "LWHJgvkXuNcJ7pCxQ8Pj2oYjGZxKxcz...", "address_out": "LZj9QTqMR8K5y4rCtV1cLrLwZP9Q...", "callback_url": "https://example.com/placeholder", "priority": "default" } ``` `address_in` is the address your customer pays. `address_out` is the wallet you configured in step 1, where BlockBee forwards confirmed funds. Save `address_in` — you'll use it in step 4. ## 3. Set up a webhook receiver When a payment arrives at `address_in`, BlockBee POSTs to your `callback` URL. For testing, use [webhook.site](https://webhook.site) — a free tool that provides a public URL and displays incoming requests in real time. No signup required, no server to run. 1. Open [webhook.site](https://webhook.site). Copy the unique URL it generates (e.g. `https://webhook.site/abc123...`). 2. Re-run the request from step 2 with that URL as your `callback`. You'll receive a new `address_in`. 3. Keep the webhook.site tab open — the callback will appear there in step 4. ![webhook.site landing with a unique URL](/assets/images/quickstart/webhook-site-url.png) *webhook.site gives you a public URL the moment the page loads — no signup needed* > **INFO** >In production, your webhook endpoint must be publicly accessible over HTTPS, respond with `200` and the body `*ok*`, and verify the request signature. See the [Webhooks guide](/webhooks) for the full contract. ## 4. Send a test payment Send a small amount of Litecoin (around $1, or about 0.005 LTC at recent prices) from any wallet to the `address_in` you generated in step 3. > **WARNING: Stay above the minimum** >Every cryptocurrency has a minimum transaction amount. Transactions below this minimum are **ignored, and the funds are lost**. Check the current LTC minimum on the [cryptocurrencies page](https://blockbee.io/cryptocurrencies) or via the [Service info endpoint](/api/get-service-info) before sending. Litecoin blocks confirm every ~2.5 minutes, so the webhook will fire shortly after you send the payment. The payload looks like this: ```json { "address_in": "LWHJgvkXuNcJ7pCxQ8Pj2oYjGZxKxcz...", "address_out": "LZj9QTqMR8K5y4rCtV1cLrLwZP9Q...", "txid_in": "f8e1d2...", "txid_out": "a3b9c4...", "confirmations": "1", "value": "500000", "value_coin": "0.005", "coin": "ltc", "result": "sent" } ``` ![webhook.site showing the incoming BlockBee callback](/assets/images/quickstart/webhook-received.png) *The webhook lands on webhook.site with the full payment details* BlockBee has confirmed the payment and forwarded it to your wallet. The integration is complete. ## What's next Pick the integration that fits your product: - **[Checkout Payments](/get-started/checkout-payments)** — hosted checkout page; BlockBee handles the UI. - **[Custom Payment Flow](/get-started/custom-payment-flow)** — your UI on top of the BlockBee API. - **[Subscriptions](/get-started/subscriptions)** — recurring billing with automatic retries on missed payments. - **[Browse all integrations](/get-started/integrations)** — no-code plugins, hosted storefront, payment links, POS. Then harden the integration: - [Verify webhook signatures](/webhooks) before going to production. - [Upgrade to API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2) to unlock the self-custodial wallet and payouts. - Read the full [API reference](/api). Stuck? Join us on [Discord](https://discord.gg/pQaJ32SGrR) or [contact support](https://blockbee.io/contacts/). --- # API Reference > Source: https://docs.blockbee.io/api > Description: Complete reference for the BlockBee API. Endpoints for payments, checkouts, deposits, subscriptions, and self-custodial payouts. # API Reference The BlockBee API is a REST-style HTTP API for accepting and sending crypto. Every endpoint returns JSON and accepts `GET` or `POST` requests over HTTPS. ## Conventions The same rules apply to every endpoint, so we don't repeat them on each one. > **INFO: API Basics** >- **Base URL:** `https://api.blockbee.io` > - **Authentication:** pass your API key as the `apikey` query parameter on every request. > - **Dates:** Unix epoch time in **seconds** (e.g. `1673438907`), UTC. > - **Amounts:** decimal strings, never floats (e.g. `"0.01"`, not `0.01`). This avoids float precision loss. > - **Tickers:** lowercase ISO-style symbols including the chain where ambiguous (e.g. `btc`, `eth`, `bep20_usdt`, `polygon_usdc`). Fetch the full list from [`/info`](/api/get-service-info). > - **Errors:** non-200 responses return `{ "status": "error", "error": "<message>" }`. See the [Error Handling guide](/get-started/error-handling) for the full list of error messages and what they mean. Need a key? [Generate one in the dashboard](https://dash.blockbee.io/) — V2 keys unlock the self-custodial wallet and payout endpoints. ## Tickers A **ticker** is a cryptocurrency on a specific chain. Most integrations start here: create a payment address for a customer, then watch for confirmations via webhook. - `GET` [Create New Payment Address](/api/create-payment-address) — Generate a fresh address for a customer. The webhook fires when they pay. - `GET` [Check Payment Address Logs](/api/get-payment-logs) — Inspect every callback BlockBee has fired for a given address. - `GET` [List API Transactions](/api/list-transactions) — Page through every payment received via API in a date range. - `GET` [Get Ticker Information](/api/get-ticker-info) — Minimum amounts, fees, and confirmations for a single coin. - `GET` [Estimate Blockchain Fees](/api/estimate-fees) — Forecast the network fee for a forwarding transaction. - `GET` [Convert Prices Using Ticker](/api/convert-price-by-ticker) — Convert between fiat and a specific cryptocurrency. - `GET` [Payment QR Code Generator](/api/generate-qr-code) — Render a QR for a payment address with an optional amount. ## Checkout Hosted checkout pages — send the customer to a BlockBee URL and we handle currency selection, the address, and the receipt. - `GET` [Create a Checkout Payment Link](/api/create-checkout) — Generate a checkout URL for one-time payments. - `GET` [List Checkout Payments](/api/list-checkouts) — Page through past checkouts. - `GET` [Get Checkout Logs](/api/get-checkout-logs) — Inspect callbacks for a single checkout. ## Deposits Long-lived deposit pages for wallets, exchanges, and account funding. One link per user, one address forever. - `GET` [Create Deposit Request](/api/create-deposit) — Generate a hosted deposit page tied to a user. - `GET` [List Deposit Requests](/api/list-deposits) — Page through your deposit pages. - `GET` [Get Deposit Logs](/api/get-deposit-logs) — Inspect callbacks for a deposit. ## Subscriptions Recurring crypto billing with automated reminders. - `GET` [Create Subscription](/api/create-subscription) — Start a new subscription for a customer. - `GET` [Fetch Subscription](/api/get-subscription) — Read the current state of one subscription. - `GET` [List Subscriptions](/api/list-subscriptions) — Page through subscriptions in a date range. ## Self-Custodial Wallet & Payouts Send crypto from your BlockBee wallet to one address or thousands. Requires an [API Key V2](/get-started/authentication). **Wallet & balance** - `GET` [Get Address](/api/get-wallet-address) — Your wallet address for a given ticker. - `GET` [Get Self-Custodial Wallet Balance](/api/get-wallet-balance) — Current balance and pending amounts. **Single payouts** - `POST` [Create Payout](/api/create-payout) — Send to one or more addresses in a single call. - `POST` [Get Payout Status](/api/get-payout-status) — Check whether a payout has confirmed. - `POST` [Process Payout by ID](/api/process-payout-by-id) — Trigger processing of a queued payout. **Payout requests (queue + process pattern)** - `GET` [Create a Payout Request](/api/create-payout-request) — Queue a payout to be processed later. - `POST` [Bulk Create Payout Requests](/api/create-payout-requests-bulk) — Queue many payouts in one call. - `POST` [Process Bulk Payout Requests](/api/process-payout-requests-bulk) — Run the queue. - `GET` [List Payout Requests](/api/list-payout-requests) — Page through queued requests. - `GET` [List Payouts](/api/list-payouts) — Page through processed payouts. ## Utilities - `GET` [BlockBee Service Information](/api/get-service-info) — Supported coins, minimums, and fees in one response. - `GET` [Convert Price](/api/convert-price) — Convert between fiat and any supported crypto. --- New to the API? Start with the [Custom Payment Flow guide](/get-started/custom-payment-flow) — it walks you through your first request end-to-end. --- # How Webhooks Work > Source: https://docs.blockbee.io/webhooks > Description: Learn how BlockBee uses webhooks to send real-time notifications to your application for events like payments, deposits, and more. # How Webhooks Work Webhooks (also called callbacks or IPNs) are how BlockBee notifies your application of events in real time — payment received, payment confirmed, subscription due, and others. Your application registers a URL; BlockBee POSTs to it as events occur. No polling required. ## How Webhooks Work ```mermaid sequenceDiagram participant App as "Your App" participant BlockBee as "BlockBee" participant Customer App->>BlockBee: Request payment with webhook URL BlockBee-->>App: Return payment address Customer->>BlockBee: Makes payment BlockBee->>App: Send webhook notification App-->>BlockBee: Respond "*ok*" ``` ## 1. Create a Webhook Endpoint Create an endpoint in your application to receive BlockBee's notifications. The endpoint must: - Be publicly accessible over HTTPS. - Accept `POST` requests. - Respond with `200` and the body `*ok*`. Any other response is treated as a failure, and we retry. ## 2. Provide the Endpoint URL to BlockBee Pass your endpoint URL when creating a payment, deposit, or subscription. The parameter is `callback` for Custom Payment Flow, `notify_url` for Checkout. ```bash # Custom Payment Flow curl "https://api.blockbee.io/btc/create/?apikey=YOUR_API_KEY&callback=https://yoursite.com/webhook" ``` > **TIP** >**URL-encode your webhook URL** if it contains its own query parameters. For example, `https://yoursite.com/webhook?order_id=123` becomes `https%3A//yoursite.com/webhook%3Forder_id%3D123`. ```javascript const originalUrl = 'https://yoursite.com/webhook?order_id=123'; const encodedUrl = encodeURIComponent(originalUrl); // encodedUrl: "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```php <?php $originalUrl = 'https://yoursite.com/webhook?order_id=123'; $encodedUrl = urlencode($originalUrl); // $encodedUrl is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ?> ``` ```python import urllib.parse original_url = 'https://yoursite.com/webhook?order_id=123' encoded_url = urllib.parse.quote(original_url, safe='') # encoded_url is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```ruby require 'uri' original_url = 'https://yoursite.com/webhook?order_id=123' encoded_url = URI.encode_www_form_component(original_url) # encoded_url is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```cs using System.Net; string originalUrl = "https://yoursite.com/webhook?order_id=123"; string encodedUrl = WebUtility.UrlEncode(originalUrl); // encodedUrl is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```java import java.net.URLEncoder; import java.nio.charset.StandardCharsets; String originalUrl = "https://yoursite.com/webhook?order_id=123"; String encodedUrl = URLEncoder.encode(originalUrl, StandardCharsets.UTF_8.toString()); // encodedUrl is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```go import "net/url" originalUrl := "https://yoursite.com/webhook?order_id=123" encodedUrl := url.QueryEscape(originalUrl) // encodedUrl is "https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ```curl # The final API call with the URL-encoded callback parameter curl "https://api.blockbee.io/btc/create/?apikey=YOUR_API_KEY&callback=https%3A%2F%2Fyoursite.com%2Fwebhook%3Forder_id%3D123" ``` ## 3. Secure Your Endpoint > **WARNING** >**Verify webhook signatures.** Signature verification confirms the request came from BlockBee and was not modified in transit. Skipping this step exposes your integration to spoofed events. > > **[Read the Verify Webhook Signatures guide](/webhooks/verify-webhook-signature) →** ## Webhook Payloads Webhook payloads vary by service and event type. A new deposit webhook contains different fields than a completed checkout payment. See the relevant guide for the full payload schema: - **[Custom Payment Flow Webhooks](/webhooks/custom-payment-flow-webhooks)** - **[Checkout Webhooks](/webhooks/checkout-payments-webhook)** - **[Deposit Webhooks](/webhooks/checkout-deposits-webhook)** - **[Subscription Webhooks](/webhooks/subscriptions-webhook)** ## Best Practices & Troubleshooting - **Respond within 30 seconds.** Your endpoint must acknowledge with `200` and `*ok*` within 30 seconds, or the connection times out. For any processing longer than that, queue it asynchronously after responding. - **Make your handler idempotent.** BlockBee retries failed deliveries, so your endpoint will receive the same webhook more than once. Track the `uuid` of each processed webhook and skip duplicates. - **Allowlist BlockBee's IPs.** If your firewall blocks unknown sources, allow `51.77.105.132` and `135.125.112.47`. - **Use `ngrok` for local testing.** Expose your local development server to the public internet so you can test webhooks without deploying. ### Retry schedule If your endpoint doesn't respond with `*ok*`, BlockBee retries with exponential backoff: - **1st retry:** 6 minutes - **2nd retry:** 12 minutes - **3rd retry:** 24 minutes - …doubling each time until the transaction is 3 days old, after which retries stop. ### Troubleshooting - **Webhooks not received.** Check that your endpoint is publicly accessible, that your firewall or CDN (e.g. Cloudflare) doesn't block BlockBee's IPs, and that the customer sent the same coin and chain the address was generated for. - **Duplicate processing.** Your handler is not idempotent. Track the `uuid` of each webhook and skip duplicates. --- # Libraries > Source: https://docs.blockbee.io/libraries > Description: Official BlockBee SDKs for NodeJS, Python, Django, PHP, and Ruby. Install, authenticate, and create your first payment in minutes. # Libraries The fastest way to integrate BlockBee. Each official library wraps the [REST API](/api) so you can create payment addresses, fetch transactions, and process payouts in a few lines of code. ## Available libraries - **[NodeJS](/libraries/nodejs)** — `npm install @blockbee/api` · [GitHub](https://github.com/blockbee-io/nodejs-api) - **[Python](/libraries/python)** — `pip install python-blockbee` · [GitHub](https://github.com/blockbee-io/python-blockbee) - **[Django](/libraries/django)** — `pip install django-blockbee` · [GitHub](https://github.com/blockbee-io/django-blockbee) - **[PHP](/libraries/php)** — `composer require blockbee/php-blockbee` · [GitHub](https://github.com/blockbee-io/php-blockbee) - **[Ruby](/libraries/ruby)** — `gem install blockbee` · [GitHub](https://github.com/blockbee-io/ruby-blockbee) ## What the libraries do Every official library covers the same surface: - Create payment addresses for any supported ticker - Fetch payment logs and transaction history - Generate QR codes for payments - Estimate blockchain fees - Convert between fiat and crypto - Manage payouts (V2 API key required) For specifics — initialization, method signatures, and full examples — open the page for your language above. ## No library for your stack? Use the [REST API](/api) directly. Every endpoint accepts standard HTTP requests and returns JSON — any HTTP client will do. The [API conventions](/api#conventions) section covers auth, dates, amounts, and error handling once for every endpoint. If you build an unofficial library and would like it listed here, [contact us](https://blockbee.io/contacts/). --- # Knowledge Base > Source: https://docs.blockbee.io/kb > Description: Answers to common questions about BlockBee — accounts, payments, fees, API keys, and step-by-step dashboard tutorials. # Knowledge Base Short, focused answers to the questions BlockBee users ask most. If you can't find what you need, [join our Discord](https://discord.gg/pQaJ32SGrR) or contact support. ## Getting Started - [Do I need to register?](/kb/get-started/do-i-need-to-register) - [Do I need an API key?](/kb/get-started/do-i-need-an-api-key) - [How does the BlockBee service work?](/kb/get-started/how-does-blockbee-service-work) - [How to integrate BlockBee](/kb/get-started/how-to-integrate-blockbee) - [Is KYC verification required?](/kb/get-started/is-kyc-verification-required) ## Payments - [What are the statuses of a transaction?](/kb/payments/what-are-the-statuses-of-a-transaction) - [Considerations before paying with an exchange](/kb/payments/considerations-to-take-before-paying-with-an-exchange) - [How to calculate the minimum when using multiple addresses](/kb/payments/how-to-calculate-the-minimum-when-using-multiple-addresses) - [I think I got billed more than needed — why?](/kb/payments/i-think-i-got-billed-more-than-needed-why) ## Fees - [How much are your transaction fees?](/kb/fees/how-much-are-your-transaction-fees) - [How to reduce blockchain fees](/kb/fees/how-to-reduce-blockchain-fees) - [How to save on blockchain fees with prepaid fees](/kb/tutorials/dashboard/how-to-save-on-blockchain-fees-with-prepaid-fees) ## Account & API Keys - [What is the difference between API Key V1 and V2?](/kb/account-settings/what-is-the-difference-between-api-key-v1-and-v2) - [How to generate a new API key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to upgrade to API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2) - [How to create a profile](/kb/tutorials/dashboard/how-to-create-a-profile) - [How to set the payment settings of your profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) ## Developer Notes - [What is the multi-token parameter?](/kb/developers/api/what-is-the-multi-token-parameter) - [What is the priority parameter?](/kb/developers/api/what-is-the-priority-parameter) ## Dashboard Tutorials - [How to set up the addresses](/kb/tutorials/dashboard/how-to-set-up-the-addresses) - [How to set up your exchange address automatically](/kb/tutorials/dashboard/how-to-set-up-your-exchange-address-automatically) - [How to enable exchanging your funds with SwapBee](/kb/tutorials/dashboard/setting-up-exchange-automation-rules) - [How to check my Self-Custodial Wallet](/kb/tutorials/dashboard/how-to-check-my-self-custodial-wallet) - [How to create a Payout](/kb/tutorials/dashboard/how-to-create-a-payout) - [How to create a POS user](/kb/tutorials/dashboard/how-to-create-a-pos-user) ## Plugin Setup - [WooCommerce](/kb/tutorials/plugins/how-to-set-up-woocommerce-plugin) - [Magento](/kb/tutorials/plugins/how-to-set-up-magento-extension) - [OpenCart](/kb/tutorials/plugins/how-to-set-up-opencart-extension) - [PrestaShop](/kb/tutorials/plugins/how-to-set-up-prestashop-module) ## Telegram Bot - [How to handle subscriptions using BlockBee Telegram Bot](/kb/tutorials/telegram-bot/how-to-handle-subscriptions-using-blockbee-telegram-bot) ## POS - [Which platforms is the POS app available on?](/kb/pos/which-platforms-is-the-pos-app-available) --- # guides > Source: https://docs.blockbee.io/guides --- # Changelog > Source: https://docs.blockbee.io/changelog > Description: API changes, new supported tokens, and deprecations. Latest first. # Changelog API changes, new supported cryptocurrencies, and deprecations. Dates are UTC. Breaking changes are marked **Breaking**. ## 2026-05-25 — Prestashop 2.0.0 New Prestashop plugin update. Changelog: - Full rewrite on top of BlockBee Checkout Payments — customers are now redirected to pay.blockbee.io to complete their payment - Webhook signature verification for improved security - PrestaShop 8 and 9 compatibility - Cronjob no longer needed ## 2026-05-21 — New token: TRX on Ethereum (ERC20) and BEP20 (Smart Chain) **New Cryptocurrency** TRX is now available on two additional networks: - **Ethereum (ERC20)** - **BNB Smart Chain (BEP20)** Both are live across all CryptAPI endpoints. ## 2026-05-20 — BlockBee OpenCart plugin v1.0.0 **Plugin Release** - OpenCart 4.x compatibility fixes. - Improved webhook security with signature verification. - New admin warning for unsupported store currencies. - Various bugfixes and improvements. - Added translations. ## 2026-05-14 — BlockBee WooCommerce plugin v1.5.11 **Plugin Release** - Show minimum transaction amount on the payment page. - Translation fixes. - Minor bugfixes. --- # Authentication > Source: https://docs.blockbee.io/get-started/authentication > Description: How to authenticate requests to the BlockBee API. API key types, where to use each, and security best practices. # Authentication BlockBee uses API key authentication. Pass your key as a query parameter or header on every request. ## API key types BlockBee issues two types of keys. ### V1 — Receiving payments - **Use:** Receiving crypto payments through BlockBee. - **Custody:** BlockBee receives funds and forwards them to the wallet you've configured in the dashboard. - **Recovery:** Safe to reset; resetting the key does not affect your funds. ### V2 — Self-Custodial Wallet - **Use:** Receiving payments and sending payouts. Required for the Self-Custodial Wallet and all payout endpoints. - **Custody:** You hold your funds directly. BlockBee never touches them. - **Recovery:** A separate **Recovery Key** is generated when you create the V2 key. The Recovery Key is required to regenerate the API key if you lose it. > **WARNING** >**Store both your API Key V2 and Recovery Key in a safe location.** If you lose both, your Self-Custodial Wallet funds become permanently inaccessible — BlockBee cannot recover them. ## When to use each **Upgrade to V2 if:** - You need to send payouts (single or bulk). - You want self-custody of funds — BlockBee never holds them. **Stay on V1 if:** - You only need to receive payments. - You're fine with BlockBee receiving funds before forwarding them. For migration steps, see [How to upgrade to API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2). ## Generate a key Generate keys on the [API Keys page](https://dash.blockbee.io/profile/api-keys) in the dashboard. ## Pass your key on every request Either method works. Pick one and stick with it. ### Query parameter Pass your key as the `apikey` query parameter: ```bash curl "https://api.blockbee.io/btc/create/?apikey=YOUR_API_KEY&callback=https://yoursite.com/webhook" ``` ### Header Pass your key in the `apikey` header: ```bash curl "https://api.blockbee.io/btc/create/?callback=https://yoursite.com/webhook" \ -H "apikey: YOUR_API_KEY" ``` ## Security - **Never expose your key in client-side code or public repositories.** Treat it like a password. - **Always use HTTPS.** All BlockBee API endpoints are served over HTTPS. - **Rotate keys periodically** to limit exposure if a key is compromised. If a key is compromised, revoke it from the [API Keys page](https://dash.blockbee.io/profile/api-keys) and generate a new one. --- # Checkout Deposits > Source: https://docs.blockbee.io/get-started/checkout-deposits > Description: Create deposit links that allow customers to make multiple payments. Perfect for accepting recurring deposits, donations, or building up account balances. ## Overview Checkout Deposits allow you to create reusable deposit links where customers can make multiple payments over time. Unlike one-time payments, deposit links remain active and can receive multiple transactions from different users or the same user making recurring deposits. This makes it perfect for: - **Account funding** - Let users add funds to their account balance - **Donations** - Accept multiple donations from supporters - **Recurring payments** - Allow customers to make regular deposits - **Static payment links** - Create permanent payment addresses for your business > **INFO** >**Estimated time:** 5-10 minutes for a basic implementation ## Setup Before you can start accepting deposits, you need to configure your BlockBee account and get your API credentials. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive deposits at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Payment Settings 1. **Set Default Currency:** Go to [Payment Settings](https://dash.blockbee.io/profile/checkout) and configure your default FIAT currency (USD, EUR, GBP, etc.) 2. **Customize Deposit Page:** Optionally customize the appearance and branding of your deposit pages ### 4. Generate API Key 1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard 2. Click "Generate New API Key" 3. Copy the generated API key - you'll need this for all API requests > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to generate an API Key. > **WARNING** >**Keep your API key secure:** Never expose your API key in client-side code or public repositories. Store it securely in environment variables or server-side configuration. ## Step 1: Create Deposit Link First, make a request to our Deposit API. This will generate a unique deposit link that can receive multiple payments. ### API Endpoint **Method:** `GET` **URL:** `https://api.blockbee.io/deposit/request/` > **INFO: Tracking Deposits with Custom Parameters** >You can add your own query parameters to `notify_url` to track deposits. For example, adding `?user_id=123` will ensure that `user_id=123` is included in the webhook payload for each deposit. This is the recommended way to link deposits to specific users or accounts in your system. > > **Important:** Always include a unique identifier (like `user_id`, `account_id`, or `deposit_id`) in your `notify_url` to properly track which user/account the deposit belongs to. This identifier will be returned in the webhook payload, allowing you to credit the correct user account in your database. > **TIP** >**API Reference:** For complete parameter documentation, see our [Deposit Request API Reference](/api/create-deposit). ### Code Examples ```javascript // Create a deposit link const createDepositLink = async (userId) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', notify_url: `https://yoursite.com/webhook/?user_id=${userId}`, currency: 'usd', item_description: 'Account Deposit', post: '1' }); const response = await fetch(`https://api.blockbee.io/deposit/request/?${params}`); const result = await response.json(); if (result.status === 'success') { return { paymentId: result.payment_id, paymentUrl: result.payment_url }; } else { throw new Error('Failed to create deposit link: ' + result.message); } }; ``` ```php <?php function createDepositLink($userId) { $params = [ 'apikey' => 'YOUR_API_KEY', 'notify_url' => 'https://yoursite.com/webhook/?user_id=' . $userId, 'currency' => 'usd', 'item_description' => 'Account Deposit', 'post' => '1' ]; $url = 'https://api.blockbee.io/deposit/request/?' . http_build_query($params); $response = file_get_contents($url); $result = json_decode($response, true); if ($result['status'] === 'success') { return [ 'paymentId' => $result['payment_id'], 'paymentUrl' => $result['payment_url'] ]; } else { throw new Exception('Failed to create deposit link: ' . $result['message']); } } ?> ``` ```python import requests def create_deposit_link(user_id): params = { 'apikey': 'YOUR_API_KEY', 'notify_url': f'https://yoursite.com/webhook/?user_id={user_id}', 'currency': 'usd', 'item_description': 'Account Deposit', 'notify_url': f'https://yoursite.com/webhook/?user_id={user_id}', 'post': '1' } response = requests.get('https://api.blockbee.io/deposit/request/', params=params) result = response.json() if result['status'] == 'success': return { 'paymentId': result['payment_id'], 'paymentUrl': result['payment_url'] } else: raise Exception(f'Failed to create deposit link: {result.get("message", "Unknown error")}') ``` ```ruby require 'net/http' require 'json' require 'uri' def create_deposit_link(user_id) params = { 'apikey' => 'YOUR_API_KEY', 'notify_url' => "https://yoursite.com/webhook/?user_id=#{user_id}", 'currency' => 'usd', 'item_description' => 'Account Deposit', 'post' => '1' } uri = URI('https://api.blockbee.io/deposit/request/') uri.query = URI.encode_www_form(params) response = Net::HTTP.get_response(uri) result = JSON.parse(response.body) if result['status'] == 'success' { paymentId: result['payment_id'], paymentUrl: result['payment_url'] } else raise "Failed to create deposit link: #{result['message']}" end end ``` ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; public class DepositService { private static readonly HttpClient client = new HttpClient(); public async Task<DepositResult> CreateDepositLink(string userId) { var parameters = new Dictionary<string, string> { ["apikey"] = "YOUR_API_KEY", ["notify_url"] = $"https://yoursite.com/webhook/?user_id={userId}", ["currency"] = "usd", ["item_description"] = "Account Deposit", ["post"] = "1" }; var queryString = string.Join("&", parameters.Select(p => $"{p.Key}={Uri.EscapeDataString(p.Value)}")); var url = $"https://api.blockbee.io/deposit/request/?{queryString}"; var response = await client.GetStringAsync(url); var result = JsonConvert.DeserializeObject<Dictionary<string, object>>(response); if (result["status"].ToString() == "success") { return new DepositResult { PaymentId = result["payment_id"].ToString(), PaymentUrl = result["payment_url"].ToString() }; } else { throw new Exception($"Failed to create deposit link: {result.GetValueOrDefault("message", "Unknown error")}"); } } } public class DepositResult { public string PaymentId { get; set; } public string PaymentUrl { get; set; } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.Map; import com.fasterxml.jackson.databind.ObjectMapper; public class DepositLink { private static final HttpClient client = HttpClient.newHttpClient(); private static final ObjectMapper mapper = new ObjectMapper(); public DepositResult createDepositLink(String userId) throws Exception { String baseUrl = "https://api.blockbee.io/deposit/request/"; String queryParams = String.format( "apikey=%s¬ify_url=%s¤cy=usd&item_description=%s&post=1", "YOUR_API_KEY", URLEncoder.encode("https://yoursite.com/webhook/?user_id=" + userId, StandardCharsets.UTF_8), URLEncoder.encode("Account Deposit", StandardCharsets.UTF_8) ); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "?" + queryParams)) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); Map<String, Object> result = mapper.readValue(response.body(), Map.class); if ("success".equals(result.get("status"))) { return new DepositResult( (String) result.get("payment_id"), (String) result.get("payment_url") ); } else { throw new Exception("Failed to create deposit link: " + result.getOrDefault("message", "Unknown error")); } } } class DepositResult { private String paymentId; private String paymentUrl; public DepositResult(String paymentId, String paymentUrl) { this.paymentId = paymentId; this.paymentUrl = paymentUrl; } // Getters public String getPaymentId() { return paymentId; } public String getPaymentUrl() { return paymentUrl; } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" ) type DepositResult struct { PaymentID string `json:"payment_id"` PaymentURL string `json:"payment_url"` } func createDepositLink(userID string) (*DepositResult, error) { baseURL := "https://api.blockbee.io/deposit/request/" params := url.Values{} params.Add("apikey", "YOUR_API_KEY") params.Add("notify_url", fmt.Sprintf("https://yoursite.com/webhook/?user_id=%s", userID)) params.Add("currency", "usd") params.Add("item_description", "Account Deposit") params.Add("post", "1") resp, err := http.Get(baseURL + "?" + params.Encode()) if err != nil { return nil, err } defer resp.Body.Close() var result map[string]interface{} if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return nil, err } if result["status"] == "success" { return &DepositResult{ PaymentID: result["payment_id"].(string), PaymentURL: result["payment_url"].(string), }, nil } message := "Unknown error" if msg, ok := result["message"].(string); ok { message = msg } return nil, fmt.Errorf("failed to create deposit link: %s", message) } ``` ```bash # Create deposit link curl -G "https://api.blockbee.io/deposit/request/" \ --data-urlencode "apikey=YOUR_API_KEY" \ --data-urlencode "notify_url=https://yoursite.com/webhook/?user_id=12345" \ --data-urlencode "currency=usd" \ --data-urlencode "item_description=Account Deposit" \ --data-urlencode "post=1" ``` > **INFO: Using Our Official Libraries** >For a simpler integration, you can also use our official libraries. Here's how you would create a deposit link: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const params = { > user_id: userId, > }; > > const blockbeeParams = { > currency: 'usd', > item_description: 'Account Deposit', > post: '1' > }; > > const deposit = await BlockBee.depositRequest( > 'https://yoursite.com/webhook/', > 'YOUR_API_KEY', > params, > blockbeeParams > ); > // deposit.payment_url and deposit.payment_id > ``` > > ```php > // Using the official PHP library > $params = ['user_id' => $userId]; > $blockbeeParams = [ > 'currency' => 'usd', > 'item_description' => 'Account Deposit', > 'post' => '1' > ]; > > $bb = new BlockBee\Checkout('YOUR_API_KEY', $params, $blockbeeParams); > $deposit = $bb->deposit_request('https://yoursite.com/webhook/'); > // $deposit->payment_url and $deposit->payment_id > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeCheckoutHelper > > params = {'user_id': userId} > bb_params = { > 'currency': 'usd', > 'item_description': 'Account Deposit', > 'post': '1' > } > > bb = BlockBeeCheckoutHelper('YOUR_API_KEY', params, bb_params); > deposit = bb.deposit_request('https://yoursite.com/webhook/'); > # deposit.payment_url and deposit.payment_id > ``` > > You can find the full documentation for our libraries here: > - [Node.js Library](/libraries/nodejs) > - [PHP Library](/libraries/php) > - [Python Library](/libraries/python) ### Required Parameters - **`apikey`** - Your BlockBee API key from the [Dashboard](https://dash.blockbee.io/) - **`notify_url`** - Webhook URL where BlockBee sends payment notifications for each deposit. ### Optional Parameters - **`currency`** - Override the default FIAT currency set in your [Payment Settings](https://dash.blockbee.io/profile/checkout) (USD, EUR, GBP, etc.). - **`item_description`** - Description that appears on the deposit page. - **`post`** - Set to `1` to receive webhooks as POST requests. - **`suggested_value`** - Suggested amount for deposits (optional, users can still send any amount). ### Response The API returns a JSON response containing the `payment_url` and `payment_id`. ```json { "status": "success", "payment_url": "https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N/", "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N" } ``` > **TIP** >**API Reference:** For complete response field documentation, see our [Deposit Request API Reference](/api/create-deposit). ## Step 2: Share the Deposit Link After creating the deposit link in Step 1, you will receive a `payment_url` in the API response. You can share this URL with your customers in multiple ways: - **Direct link** - Send the URL directly to customers - **QR code** - Generate a QR code for the deposit URL - **Embed in your app** - Display the deposit link in your application - **Static page** - Create a permanent deposit page using this URL ```javascript // Share deposit link with customer const shareDepositLink = (depositResult) => { // Option 1: Direct link console.log(`Share this link: ${depositResult.paymentUrl}`); // Option 2: Generate QR code (using a QR library) // const qrCode = generateQRCode(depositResult.paymentUrl); // Option 3: Embed in your app // document.getElementById('deposit-link').href = depositResult.paymentUrl; }; ``` ```php // Share deposit link with customer function shareDepositLink($depositResult) { // Option 1: Direct link echo "Share this link: " . $depositResult['paymentUrl']; // Option 2: Generate QR code // $qrCode = generateQRCode($depositResult['paymentUrl']); // Option 3: Embed in your app // echo '<a href="' . $depositResult['paymentUrl'] . '">Make a Deposit</a>'; } ``` ```python # Share deposit link with customer def share_deposit_link(deposit_result): # Option 1: Direct link print(f"Share this link: {deposit_result['paymentUrl']}") # Option 2: Generate QR code # qr_code = generate_qr_code(deposit_result['paymentUrl']) # Option 3: Embed in your app # return f'<a href="{deposit_result["paymentUrl"]}">Make a Deposit</a>' ``` > **TIP** >**Pre-select cryptocurrency:** You can append `?coin=btc` to the deposit URL to pre-select Bitcoin (or any other supported cryptocurrency) on the checkout page. ## Step 3: Handle the Webhooks This is the most important step. When a deposit is made, BlockBee will send a notification (webhook) to the `notify_url` you provided. Your application needs to listen for these webhooks to process each deposit. ### Webhook Endpoint Create an endpoint in your application to receive the webhook. The payload will contain all the details of the transaction. ```javascript // Express.js webhook handler app.post('/webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } // 2. Extract data from the payload const { is_paid, uuid, paid_amount, paid_coin, txid, status, user_id } = req.body; // Note: user_id comes from the custom parameter you added to notify_url when creating the deposit link // 3. Check for duplicates using UUID if (isWebhookAlreadyProcessed(uuid)) { return res.status(200).send('*ok*'); } // 4. Check if the payment is complete and the status is 'done' if (is_paid === 1 && status === 'done') { // 5. Find the user in your database using the user_id console.log(`User ${user_id} has made a deposit: ${paid_amount} ${paid_coin}`); // 6. Update the user's account balance // e.g., db.users.update({ id: user_id }, { // $inc: { balance: paid_amount }, // $push: { transactions: { amount: paid_amount, coin: paid_coin, txid: txid } } // }); // 7. Send confirmation to the user console.log(`Crediting ${paid_amount} ${paid_coin} to user ${user_id}...`); } // 8. Mark this webhook as processed using its unique UUID markWebhookAsProcessed(uuid); // Respond with *ok* to let BlockBee know you've received the webhook res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $is_paid = $data['is_paid']; $uuid = $data['uuid']; $user_id = $data['user_id']; // This comes from the custom parameter you added to notify_url $paid_amount = $data['paid_amount']; $paid_coin = $data['paid_coin']; $txid = $data['txid']; $status = $data['status']; // 3. Use the uuid to prevent processing the same webhook twice if (isWebhookAlreadyProcessed($uuid)) { http_response_code(200); echo '*ok*'; exit; } // 4. Check if the payment is complete and the status is 'done' if ($is_paid == 1 && $status === 'done') { // 5. Find the user in your database error_log("User {$user_id} has made a deposit: {$paid_amount} {$paid_coin}"); // 6. Update the user's account balance // e.g., $db->query("UPDATE users SET balance = balance + '{$paid_amount}' WHERE id = '{$user_id}'"); // 7. Send confirmation to the user error_log("Crediting {$paid_amount} {$paid_coin} to user {$user_id}..."); } // 8. Mark this webhook as processed using its unique uuid markWebhookAsProcessed($uuid); // Respond with *ok* to let BlockBee know you've received the webhook http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/webhook', methods=['POST']) def webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() is_paid = data.get('is_paid') uuid = data.get('uuid') user_id = data.get('user_id') # This comes from the custom parameter you added to notify_url paid_amount = data.get('paid_amount') paid_coin = data.get('paid_coin') txid = data.get('txid') status = data.get('status') # 3. Use the uuid to prevent processing the same webhook twice if is_webhook_already_processed(uuid): return '*ok*', 200 # 4. Check if the payment is complete and status is 'done' if is_paid == 1 and status == 'done': # 5. Find the user in your database print(f"User {user_id} has made a deposit: {paid_amount} {paid_coin}") # 6. Update the user's account balance # e.g., User.objects.filter(id=user_id).update( # balance=F('balance') + paid_amount # ) # 7. Send confirmation to the user print(f"Crediting {paid_amount} {paid_coin} to user {user_id}...") # 8. Mark this webhook as processed using its unique uuid mark_webhook_as_processed(uuid) # Respond with *ok* to let BlockBee know you've received the webhook return '*ok*', 200 ``` > **TIP** >**Full Webhook Fields:** For a complete list of all fields provided in the webhook payload, see our [Checkout Deposits Webhook reference](/webhooks/checkout-deposits-webhook). ### Best Practices - **Verify Signatures:** Always verify the webhook signature to ensure the request is from BlockBee. - **Idempotency:** Use the `uuid` from the webhook payload to ensure you only process each transaction once. - **Respond Quickly:** Always respond with a `*ok*` and a `200` status code to prevent BlockBee from resending the webhook. - **Asynchronous Processing:** For long-running tasks (like calling other APIs), process them in a background job after responding to the webhook. > **TIP** >**Implementation Guide:** For detailed instructions and code examples on how to verify webhook signatures, see our [Verify Webhook Signature guide](/webhooks/verify-webhook-signature). ### Alternative: Checking Logs Manually While webhooks are recommended, you can also check the deposit status by polling our [Deposit Logs API endpoint](/api/get-deposit-logs). This can be useful for reconciliation or as a backup if your webhook endpoint fails. You will need the `payment_id` returned in Step 1. > **INFO: Using Our Official Libraries** >You can also check deposit logs using our official libraries: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const logs = await BlockBee.depositLogs(paymentId, 'YOUR_API_KEY'); > // logs.notifications contains the deposit history > ``` > > ```php > // Using the official PHP library > $logs = BlockBee\Checkout::deposit_logs($paymentId, 'YOUR_API_KEY'); > // $logs->notifications contains the deposit history > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeCheckoutHelper > > logs = BlockBeeCheckoutHelper.deposit_logs(payment_id, 'YOUR_API_KEY') > # logs['notifications'] contains the deposit history > ``` ## Testing Your Integration Test your deposit flow using real cryptocurrency with minimal cost. ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Real blockchain testing without high costs ### 2. Test with a Small Amount - Create a deposit link - Make a small deposit (e.g., $2.00) using Litecoin - This covers all fees with minimal cost (typically under $0.10) - Test multiple deposits to the same link ### 3. Testing Checklist - ✅ Deposit link creation works as expected - ✅ Webhooks are received for each deposit - ✅ User account balance is updated correctly - ✅ Duplicate webhooks are properly handled - ✅ Multiple deposits to the same link work ### 4. Local Webhook Testing To test webhooks on your local machine, you need to expose your server to the internet. `ngrok` is a great tool for this. ```bash # Use ngrok for local webhook testing ngrok http 3000 # Your test webhook URL: https://abc12345.ngrok.io/webhook # Use this as the notify_url when creating the deposit link. ``` > **SUCCESS** >**Ready for production?** Once testing is complete, switch to your production API Key and ensure your `notify_url` points to your live production server. --- # Checkout Payments > Source: https://docs.blockbee.io/get-started/checkout-payments > Description: Process one-time payments with our hosted checkout solution. Perfect for e-commerce, invoicing, and product sales. ## Overview Checkout Payments is the easiest way to start accepting cryptocurrency. With this method, BlockBee handles the entire payment interface, multi-currency selection, and real-time status updates on a secure, hosted page. Your only responsibility is to handle the final payment notification (webhook) to confirm and process the order on your end. This makes it the perfect solution if you want a fast, secure, and simple integration without building a custom UI. > **INFO** >**Estimated time:** 5-10 minutes for a basic implementation ## Setup Before you can start accepting payments, you need to configure your BlockBee account and get your API credentials. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Payment Settings 1. **Set Default Currency:** Go to [Payment Settings](https://dash.blockbee.io/profile/checkout) and configure your default FIAT currency (USD, EUR, GBP, etc.) 2. **Customize Checkout Page:** Optionally customize the appearance and branding of your checkout pages ### 4. Generate API Key 1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard 2. Click "Generate New API Key" 3. Copy the generated API key - you'll need this for all API requests > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to generate an API Key. > **WARNING** >**Keep your API key secure:** Never expose your API key in client-side code or public repositories. Store it securely in environment variables or server-side configuration. ## Step 1: Create Payment Request First, make a request to our Checkout API. This will generate a unique payment URL for your customer. ### API Endpoint **Method:** `GET` **URL:** `https://api.blockbee.io/checkout/request/` > **INFO: Tracking Orders with Custom Parameters** >You can add your own query parameters to `notify_url` and `redirect_url` to track orders. For example, adding `?order_id=123` will ensure that `order_id=123` is included in the webhook payload and the final redirect URL. This is the recommended way to link a BlockBee payment to a specific order in your system. > > **Important:** Always include a unique identifier (like `order_id`, `user_id`, or `transaction_id`) in your `notify_url` to properly track which order the webhook belongs to. This identifier will be returned in the webhook payload as GET parameters, allowing you to match the payment to the correct order in your database. > > **Note:** The `payment_id` returned in the API response can also be used as a unique identifier for tracking payments, in addition to any custom parameters you add to the URLs. > **TIP** >**API Reference:** For complete parameter documentation, see our [Checkout Request API Reference](/api/create-checkout). ### Code Examples ```javascript // Create a checkout payment const createCheckoutPayment = async (orderId, amount) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', redirect_url: `https://yoursite.com/success/?order_id=${orderId}`, value: amount.toString(), currency: 'usd', item_description: `Order #${orderId}`, notify_url: `https://yoursite.com/webhook/?order_id=${orderId}`, post: '1' }); const response = await fetch(`https://api.blockbee.io/checkout/request/?${params}`); const result = await response.json(); if (result.status === 'success') { return { paymentId: result.payment_id, paymentUrl: result.payment_url, successToken: result.success_token }; } else { throw new Error('Failed to create payment: ' + result.message); } }; ``` ```php <?php function createCheckoutPayment($orderId, $amount) { $params = [ 'apikey' => 'YOUR_API_KEY', 'redirect_url' => 'https://yoursite.com/success/?order_id=' . $orderId, 'value' => $amount, 'currency' => 'usd', 'item_description' => 'Order #' . $orderId, 'notify_url' => 'https://yoursite.com/webhook/?order_id=' . $orderId, 'post' => '1' ]; $url = 'https://api.blockbee.io/checkout/request/?' . http_build_query($params); $response = file_get_contents($url); $result = json_decode($response, true); if ($result['status'] === 'success') { return [ 'paymentId' => $result['payment_id'], 'paymentUrl' => $result['payment_url'], 'successToken' => $result['success_token'] ]; } else { throw new Exception('Failed to create payment: ' . $result['message']); } } ?> ``` ```python import requests def create_checkout_payment(order_id, amount): params = { 'apikey': 'YOUR_API_KEY', 'redirect_url': f'https://yoursite.com/success/?order_id={order_id}', 'value': str(amount), 'currency': 'usd', 'item_description': f'Order #{order_id}', 'notify_url': f'https://yoursite.com/webhook/?order_id={order_id}', 'post': '1' } response = requests.get('https://api.blockbee.io/checkout/request/', params=params) result = response.json() if result['status'] == 'success': return { 'paymentId': result['payment_id'], 'paymentUrl': result['payment_url'], 'successToken': result['success_token'] } else: raise Exception(f'Failed to create payment: {result.get("message", "Unknown error")}') ``` ```ruby require 'net/http' require 'json' require 'uri' def create_checkout_payment(order_id, amount) params = { 'apikey' => 'YOUR_API_KEY', 'redirect_url' => "https://yoursite.com/success/?order_id=#{order_id}", 'value' => amount.to_s, 'currency' => 'usd', 'item_description' => "Order ##{order_id}", 'notify_url' => "https://yoursite.com/webhook/?order_id=#{order_id}", 'post' => '1' } uri = URI('https://api.blockbee.io/checkout/request/') uri.query = URI.encode_www_form(params) response = Net::HTTP.get_response(uri) result = JSON.parse(response.body) if result['status'] == 'success' { paymentId: result['payment_id'], paymentUrl: result['payment_url'], successToken: result['success_token'] } else raise "Failed to create payment: #{result['message']}" end end ``` ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; public class PaymentService { private static readonly HttpClient client = new HttpClient(); public async Task<PaymentResult> CreateCheckoutPayment(string orderId, decimal amount) { var parameters = new Dictionary<string, string> { ["apikey"] = "YOUR_API_KEY", ["redirect_url"] = $"https://yoursite.com/success/?order_id={orderId}", ["value"] = amount.ToString(), ["currency"] = "usd", ["item_description"] = $"Order #{orderId}", ["notify_url"] = $"https://yoursite.com/webhook/?order_id={orderId}", ["post"] = "1" }; var queryString = string.Join("&", parameters.Select(p => $"{p.Key}={Uri.EscapeDataString(p.Value)}")); var url = $"https://api.blockbee.io/checkout/request/?{queryString}"; var response = await client.GetStringAsync(url); var result = JsonConvert.DeserializeObject<Dictionary<string, object>>(response); if (result["status"].ToString() == "success") { return new PaymentResult { PaymentId = result["payment_id"].ToString(), PaymentUrl = result["payment_url"].ToString(), SuccessToken = result["success_token"].ToString() }; } else { throw new Exception($"Failed to create payment: {result.GetValueOrDefault("message", "Unknown error")}"); } } } public class PaymentResult { public string PaymentId { get; set; } public string PaymentUrl { get; set; } public string SuccessToken { get; set; } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.util.Map; import com.fasterxml.jackson.databind.ObjectMapper; public class CheckoutPayment { private static final HttpClient client = HttpClient.newHttpClient(); private static final ObjectMapper mapper = new ObjectMapper(); public PaymentResult createCheckoutPayment(String orderId, double amount) throws Exception { String baseUrl = "https://api.blockbee.io/checkout/request/"; String queryParams = String.format( "apikey=%s&redirect_url=%s&value=%s¤cy=usd&item_description=%s¬ify_url=%s&post=1", "YOUR_API_KEY", URLEncoder.encode("https://yoursite.com/success/?order_id=" + orderId, StandardCharsets.UTF_8), amount, URLEncoder.encode("Order #" + orderId, StandardCharsets.UTF_8), URLEncoder.encode("https://yoursite.com/webhook/?order_id=" + orderId, StandardCharsets.UTF_8) ); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "?" + queryParams)) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); Map<String, Object> result = mapper.readValue(response.body(), Map.class); if ("success".equals(result.get("status"))) { return new PaymentResult( (String) result.get("payment_id"), (String) result.get("payment_url"), (String) result.get("success_token") ); } else { throw new Exception("Failed to create payment: " + result.getOrDefault("message", "Unknown error")); } } } class PaymentResult { private String paymentId; private String paymentUrl; private String successToken; public PaymentResult(String paymentId, String paymentUrl, String successToken) { this.paymentId = paymentId; this.paymentUrl = paymentUrl; this.successToken = successToken; } // Getters public String getPaymentId() { return paymentId; } public String getPaymentUrl() { return paymentUrl; } public String getSuccessToken() { return successToken; } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" ) type PaymentResult struct { PaymentID string `json:"payment_id"` PaymentURL string `json:"payment_url"` SuccessToken string `json:"success_token"` } func createCheckoutPayment(orderID string, amount float64) (*PaymentResult, error) { baseURL := "https://api.blockbee.io/checkout/request/" params := url.Values{} params.Add("apikey", "YOUR_API_KEY") params.Add("redirect_url", fmt.Sprintf("https://yoursite.com/success/?order_id=%s", orderID)) params.Add("value", fmt.Sprintf("%.2f", amount)) params.Add("currency", "usd") params.Add("item_description", fmt.Sprintf("Order #%s", orderID)) params.Add("notify_url", fmt.Sprintf("https://yoursite.com/webhook/?order_id=%s", orderID)) params.Add("post", "1") resp, err := http.Get(baseURL + "?" + params.Encode()) if err != nil { return nil, err } defer resp.Body.Close() var result map[string]interface{} if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return nil, err } if result["status"] == "success" { return &PaymentResult{ PaymentID: result["payment_id"].(string), PaymentURL: result["payment_url"].(string), SuccessToken: result["success_token"].(string), }, nil } message := "Unknown error" if msg, ok := result["message"].(string); ok { message = msg } return nil, fmt.Errorf("failed to create payment: %s", message) } ``` ```bash # Create checkout payment curl -G "https://api.blockbee.io/checkout/request/" \ --data-urlencode "apikey=YOUR_API_KEY" \ --data-urlencode "redirect_url=https://yoursite.com/success/?order_id=12345" \ --data-urlencode "value=10" \ --data-urlencode "currency=usd" \ --data-urlencode "item_description=Order #12345" \ --data-urlencode "notify_url=https://yoursite.com/webhook/?order_id=12345" \ --data-urlencode "post=1" ``` > **INFO: Using Our Official Libraries** >For a simpler integration, you can also use our official libraries. Here's how you would create a checkout payment: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const params = { > order_id: orderId, > }; > > const blockbeeParams = { > currency: 'usd', > item_description: `Order #${orderId}`, > post: '1' > }; > > const payment = await BlockBee.paymentRequest( > 'https://yoursite.com/success/', > 'https://yoursite.com/webhook/', > amount.toString(), > params, > blockbeeParams, > 'YOUR_API_KEY' > ); > // payment.payment_url > ``` > > ```php > // Using the official PHP library > $params = ['order_id' => $orderId]; > $blockbeeParams = [ > 'currency' => 'usd', > 'item_description' => 'Order #' . $orderId, > 'post' => '1' > ]; > > $payment = BlockBee\Checkout::payment_request( > 'https://yoursite.com/success/', > 'https://yoursite.com/webhook/', > $amount, > $params, > $blockbeeParams, > 'YOUR_API_KEY' > ); > // $payment->payment_url > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeCheckoutHelper > > params = {'order_id': order_id} > bb_params = { > 'currency': 'usd', > 'item_description': f'Order #{order_id}', > 'post': '1' > } > > payment = BlockBeeCheckoutHelper.payment_request( > 'https://yoursite.com/success/', > 'https://yoursite.com/webhook/', > str(amount), > params, > bb_params, > 'YOUR_API_KEY' > ) > # payment.payment_url > ``` > > You can find the full documentation for our libraries here: > - [Node.js Library](/libraries/nodejs) > - [PHP Library](/libraries/php) > - [Python Library](/libraries/python) ### Required Parameters - **`apikey`** - Your BlockBee API key from the [Dashboard](https://dash.blockbee.io/) - **`redirect_url`** - URL where customers are redirected after payment completion. - **`notify_url`** - Webhook URL where BlockBee sends payment notifications. - **`value`** - Payment amount in your configured FIAT currency. ### Optional Parameters - **`currency`** - Override the default FIAT currency set in your [Payment Settings](https://dash.blockbee.io/profile/checkout) (USD, EUR, GBP, etc.). - **`item_description`** - Description that appears on the checkout page. - **`expire_at`** - Payment expiration time (Unix timestamp, minimum 1 hour). - **`post`** - Set to `1` to receive webhooks as POST requests. ### Response The API returns a JSON response containing the `payment_url`. ```json { "status": "success", "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "success_token": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9NfG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "payment_url": "https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N" } ``` > **TIP** >**API Reference:** For complete response field documentation, see our [Checkout Request API Reference](/api/create-checkout). ## Step 2: Redirect Customer to Payment After creating the payment request in Step 1, you will receive a `payment_url` in the API response. Simply redirect your customer to this URL. BlockBee's hosted page takes over from here, handling everything from coin selection to payment confirmation. ```javascript // Redirect customer to payment page window.location.href = paymentResult.paymentUrl; ``` ```php // Redirect customer to payment page header('Location: ' . $paymentResult['paymentUrl']); exit(); ``` ```python # Flask example from flask import redirect @app.route('/create-payment') def create_payment(): # Assume create_checkout_payment is defined as in Step 1 payment_result = create_checkout_payment(order_id='123', amount=10.50) return redirect(payment_result['paymentUrl']) ``` ```ruby # Ruby on Rails example def create # Assume create_checkout_payment is defined as in Step 1 payment_result = create_checkout_payment(order_id: '123', amount: 10.50) redirect_to payment_result[:paymentUrl], allow_other_host: true end ``` ## Step 3: Handle the Webhook This is the final and most important step. When a payment is made, BlockBee will send a notification (webhook) to the `notify_url` you provided. Your application needs to listen for this webhook to mark the order as paid. ### Webhook Endpoint Create an endpoint in your application to receive the webhook. The payload will contain all the details of the transaction. ```javascript // Express.js webhook handler app.post('/webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } // 2. Extract data from the payload const { is_paid, payment_id, order_id, paid_amount, paid_coin, txid, status } = req.body; // Note: order_id comes from the custom parameter you added to notify_url when creating the payment // Use the payment_id to prevent processing the same webhook twice if (isWebhookAlreadyProcessed(payment_id)) { return res.status(200).send('*ok*'); } // Check if the payment is complete and the status is 'done' if (is_paid === 1 && status === 'done') { // 1. Find the order in your database using the order_id // 2. Update the order status to "paid" and store payment details // e.g., db.orders.update({ id: order_id }, { // status: 'paid', // paid_amount: paid_amount, // paid_coin: paid_coin, // txid: txid // }); // 3. Fulfill the order (e.g., ship product, grant access) } // Mark this webhook as processed using its unique payment_id markWebhookAsProcessed(payment_id); // Respond with *ok* to let BlockBee know you've received the webhook res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $is_paid = $data['is_paid']; $payment_id = $data['payment_id']; $orderId = $data['order_id']; // This comes from the custom parameter you added to notify_url $paid_amount = $data['paid_amount']; $paid_coin = $data['paid_coin']; $txid = $data['txid']; $status = $data['status']; // Use the payment_id to prevent processing the same webhook twice if (isWebhookAlreadyProcessed($payment_id)) { http_response_code(200); echo '*ok*'; exit; } // Check if the payment is complete and the status is 'done' if ($is_paid == 1 && $status === 'done') { // 1. Find the order in your database // 2. Update the order status to "paid" and store payment details // e.g., $db->query("UPDATE orders SET status = 'paid', paid_amount = '{$paid_amount}', paid_coin = '{$paid_coin}', txid = '{$txid}' WHERE id = '{$orderId}'"); // 3. Fulfill the order (e.g., ship product, grant access) } // Mark this webhook as processed using its unique payment_id markWebhookAsProcessed($payment_id); // Respond with *ok* to let BlockBee know you've received the webhook http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/webhook', methods=['POST']) def webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() is_paid = data.get('is_paid') payment_id = data.get('payment_id') order_id = data.get('order_id') # This comes from the custom parameter you added to notify_url paid_amount = data.get('paid_amount') paid_coin = data.get('paid_coin') txid = data.get('txid') status = data.get('status') # Use the payment_id to prevent processing the same webhook twice if is_webhook_already_processed(payment_id): return '*ok*', 200 # Check if the payment is complete and status is 'done' if is_paid == 1 and status == 'done': # 1. Find the order in your database # 2. Update the order status to "paid" and store payment details # e.g., Order.objects.filter(id=order_id).update( # status='paid', # paid_amount=paid_amount, # paid_coin=paid_coin, # txid=txid # ) # 3. Fulfill the order (e.g., ship product, grant access) # Mark this webhook as processed using its unique payment_id mark_webhook_as_processed(payment_id) # Respond with *ok* to let BlockBee know you've received the webhook return '*ok*', 200 ``` ```ruby # Ruby on Rails webhook handler class WebhooksController < ApplicationController skip_before_action :verify_authenticity_token def payment # 1. Verify the webhook signature unless verify_webhook_signature(request) render plain: 'Unauthorized', status: :unauthorized return end # 2. Extract data from the payload is_paid = params[:is_paid] payment_id = params[:payment_id] order_id = params[:order_id] # This comes from the custom parameter you added to notify_url paid_amount = params[:paid_amount] paid_coin = params[:paid_coin] txid = params[:txid] status = params[:status] # 3. Use the payment_id to prevent processing the same webhook twice if webhook_already_processed?(payment_id) render plain: '*ok*', status: :ok return end # 4. Check if the payment is complete and the status is 'done' if is_paid == '1' && status == 'done' # 1. Find the order in your database # 2. Update the order status to "paid" and store payment details # e.g., Order.where(id: order_id).update_all( # status: 'paid', # paid_amount: paid_amount, # paid_coin: paid_coin, # txid: txid # ) # 3. Fulfill the order (e.g., ship product, grant access) end # 5. Mark this webhook as processed using the payment_id mark_webhook_as_processed(payment_id) # Always respond to stop retries render plain: '*ok*', status: :ok end end ``` ```csharp // ASP.NET Core webhook handler [ApiController] [Route("webhook")] public class WebhookController : ControllerBase { [HttpPost("payment")] public async Task<IActionResult> PaymentWebhook([FromBody] PaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!VerifyWebhookSignature(Request)) { return Unauthorized("Unauthorized"); } // 2. Extract data from the payload var isPaid = payload.IsPaid; var paymentId = payload.PaymentId; var orderId = payload.OrderId; // This comes from the custom parameter you added to notify_url var paidAmount = payload.PaidAmount; var paidCoin = payload.PaidCoin; var txid = payload.Txid; var status = payload.Status; // 3. Use the payment_id to prevent processing the same webhook twice if (IsWebhookAlreadyProcessed(paymentId)) { return Ok("*ok*"); } // 4. Check if the payment is complete and the status is 'done' if (isPaid == "1" && status == "done") { // 1. Find the order in your database // 2. Update the order status to "paid" and store payment details // e.g., await _dbContext.Orders.Where(o => o.Id == orderId) // .ExecuteUpdateAsync(o => o // .SetProperty(p => p.Status, "paid") // .SetProperty(p => p.PaidAmount, paidAmount) // .SetProperty(p => p.PaidCoin, paidCoin) // .SetProperty(p => p.Txid, txid)); // 3. Fulfill the order (e.g., ship product, grant access) } // 5. Mark this webhook as processed using the payment_id MarkWebhookAsProcessed(paymentId); // Always respond to stop retries return Ok("*ok*"); } } public class PaymentWebhookPayload { [JsonProperty("is_paid")] public string IsPaid { get; set; } [JsonProperty("payment_id")] public string PaymentId { get; set; } [JsonProperty("order_id")] public string OrderId { get; set; } [JsonProperty("paid_amount")] public string PaidAmount { get; set; } [JsonProperty("paid_coin")] public string PaidCoin { get; set; } [JsonProperty("txid")] public string Txid { get; set; } [JsonProperty("status")] public string Status { get; set; } } ``` ```java // Spring Boot webhook handler @RestController @RequestMapping("/webhook") public class WebhookController { @PostMapping("/payment") public ResponseEntity<String> paymentWebhook(@RequestBody PaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!verifyWebhookSignature(request)) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized"); } // 2. Extract data from the payload String isPaid = payload.getIsPaid(); String paymentId = payload.getPaymentId(); String orderId = payload.getOrderId(); // This comes from the custom parameter you added to notify_url String paidAmount = payload.getPaidAmount(); String paidCoin = payload.getPaidCoin(); String txid = payload.getTxid(); String status = payload.getStatus(); // 3. Use the payment_id to prevent processing the same webhook twice if (isWebhookAlreadyProcessed(paymentId)) { return ResponseEntity.ok("*ok*"); } // 4. Check if the payment is complete and the status is 'done' if ("1".equals(isPaid) && "done".equals(status)) { // 1. Find the order in your database // 2. Update the order status to "paid" and store payment details // e.g., orderRepository.updateOrderStatus(orderId, "paid", paidAmount, paidCoin, txid); // 3. Fulfill the order (e.g., ship product, grant access) } // 5. Mark this webhook as processed using the payment_id markWebhookAsProcessed(paymentId); // Always respond to stop retries return ResponseEntity.ok("*ok*"); } } public class PaymentWebhookPayload { private String isPaid; private String paymentId; private String orderId; private String paidAmount; private String paidCoin; private String txid; private String status; // Getters and setters public String getIsPaid() { return isPaid; } public void setIsPaid(String isPaid) { this.isPaid = isPaid; } public String getPaymentId() { return paymentId; } public void setPaymentId(String paymentId) { this.paymentId = paymentId; } public String getOrderId() { return orderId; } public void setOrderId(String orderId) { this.orderId = orderId; } public String getPaidAmount() { return paidAmount; } public void setPaidAmount(String paidAmount) { this.paidAmount = paidAmount; } public String getPaidCoin() { return paidCoin; } public void setPaidCoin(String paidCoin) { this.paidCoin = paidCoin; } public String getTxid() { return txid; } public void setTxid(String txid) { this.txid = txid; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } } ``` ```go // Go webhook handler package main import ( "encoding/json" "log" "net/http" ) type PaymentWebhookPayload struct { IsPaid string `json:"is_paid"` PaymentID string `json:"payment_id"` OrderID string `json:"order_id"` PaidAmount string `json:"paid_amount"` PaidCoin string `json:"paid_coin"` Txid string `json:"txid"` Status string `json:"status"` } func paymentWebhookHandler(w http.ResponseWriter, r *http.Request) { // 1. Verify the webhook signature if !verifyWebhookSignature(r) { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // 2. Extract data from the payload var payload PaymentWebhookPayload if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3. Use the payment_id to prevent processing the same webhook twice if isWebhookAlreadyProcessed(payload.PaymentID) { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 4. Check if the payment is complete and the status is 'done' if payload.IsPaid == "1" && payload.Status == "done" { // 1. Find the order in your database // 2. Update the order status to "paid" and store payment details // e.g., updateOrderStatus(payload.OrderID, "paid", payload.PaidAmount, payload.PaidCoin, payload.Txid) // 3. Fulfill the order (e.g., ship product, grant access) } // 5. Mark this webhook as processed using the payment_id markWebhookAsProcessed(payload.PaymentID) // Always respond to stop retries w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) } ``` ```bash # Test webhook with curl (for development/testing) curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -d '{ "is_paid": "1", "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "order_id": "12345", "paid_amount": "1.23", "paid_coin": "btc", "txid": "0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32", "status": "done" }' # Expected response: *ok* ``` > **TIP** >**Full Webhook Fields:** For a complete list of all fields provided in the webhook payload, see our [Checkout Payments Webhook reference](/webhooks/checkout-payments-webhook). ### Best Practices - **Verify Signatures:** Always verify the webhook signature to ensure the request is from BlockBee. - **Idempotency:** Use the `payment_id` from the webhook payload to ensure you only process each transaction once. - **Respond Quickly:** Always respond with a `*ok*` and a `200` status code to prevent BlockBee from resending the webhook. - **Asynchronous Processing:** For long-running tasks (like calling other APIs), process them in a background job after responding to the webhook. > **TIP** >**Implementation Guide:** For detailed instructions and code examples on how to verify webhook signatures, see our [Verify Webhook Signature guide](/webhooks/verify-webhook-signature). ### Alternative: Checking Logs Manually While webhooks are recommended, you can also check the payment status by polling our [Checkout Logs API endpoint](/api/get-checkout-logs). This can be useful for reconciliation or as a backup if your webhook endpoint fails. You will need the `payment_id` returned in Step 1. > **INFO: Using Our Official Libraries** >You can also check payment logs using our official libraries: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const logs = await BlockBee.paymentLogs(paymentId, 'YOUR_API_KEY'); > // logs.notifications contains the payment history > ``` > > ```php > // Using the official PHP library > $logs = BlockBee\Checkout::payment_logs($paymentId, 'YOUR_API_KEY'); > // $logs->notifications contains the payment history > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeCheckoutHelper > > logs = BlockBeeCheckoutHelper.payment_logs(payment_id, 'YOUR_API_KEY') > # logs['notifications'] contains the payment history > ``` ## Testing Your Integration Test your checkout flow using real cryptocurrency with minimal cost. ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Real blockchain testing without high costs ### 2. Test with a Small Amount - Create a checkout payment for a small value (e.g., $2.00) - Complete the payment on the hosted page using Litecoin - This covers all fees with minimal cost (typically under $0.10) - Allows you to test both pending and confirmed webhook states ### 3. Testing Checklist - ✅ Payment creation works as expected - ✅ Redirect to hosted checkout page is successful - ✅ Webhooks are received for pending and confirmed states - ✅ Order status is updated correctly in your system - ✅ Customer is notified of successful payment ### 4. Local Webhook Testing To test webhooks on your local machine, you need to expose your server to the internet. `ngrok` is a great tool for this. ```bash # Use ngrok for local webhook testing ngrok http 3000 # Your test webhook URL: https://abc12345.ngrok.io/webhook # Use this as the notify_url when creating the payment. ``` > **SUCCESS** >**Ready for production?** Once testing is complete, switch to your production API Key and ensure your `notify_url` and `redirect_url` point to your live production server. --- # Connect to MCP > Source: https://docs.blockbee.io/get-started/connect-to-mcp > Description: Integrate with BlockBee using the Model Context Protocol (MCP) for AI-assisted development and seamless API integration. # Connect to MCP Integrate with BlockBee using the **Model Context Protocol (MCP)** for AI-assisted development and seamless documentation access. MCP allows AI assistants like Cursor to directly consult BlockBee's documentation, making development faster and more intuitive. ## What is MCP? The **Model Context Protocol (MCP)** is an open standard that enables AI assistants to connect to external tools and APIs. With BlockBee's MCP integration, you can: - **AI-Assisted Development**: Get real-time help from AI assistants when building BlockBee integrations - **Direct API Access**: AI tools can fetch documentation, consult API references, and help debug issues - **Seamless Workflow**: Integrate BlockBee development directly into your AI-powered development environment > **INFO** >**MCP Support**: BlockBee provides full MCP support for all API endpoints, webhooks, and documentation. The MCP integration is fully functional and provides real-time access to our complete documentation ecosystem. ## Use Cases MCP integration is particularly useful for: - **API Development**: AI assistants can help you understand endpoints, parameters, and responses - **Integration Development**: Get AI assistance when building and implementing API integrations - **Documentation**: Get instant access to BlockBee's complete API reference - **Error Debugging**: AI assistants can help troubleshoot integration issues - **Code Generation**: Generate code snippets and integration examples ## Setup To connect your AI assistant to BlockBee via MCP: 1. **Install MCP Support**: Ensure your AI assistant supports MCP (Cursor, Claude Desktop, etc.) 2. **Configure MCP Server**: Add BlockBee's MCP server to your configuration 3. **Test Connection**: Verify the connection with a simple documentation query ## Configuration ### MCP Server URL ``` https://mcp.blockbee.io/ ``` **Note**: This is the official BlockBee MCP server that provides access to our complete documentation and API reference. ### Required Parameters - **Server URL**: The MCP endpoint URL above - **No API Key Required**: The MCP tool provides read-only access to documentation ### Example Configuration ```json { "mcpServers": { "blockbee-docs": { "url": "https://mcp.blockbee.io/" } } } ``` > **INFO** >**No API Key Required**: The MCP integration provides read-only access to BlockBee documentation and doesn't require authentication. For actual API calls, you'll still need to use your BlockBee API key with the API endpoints. ### What You Can Access Through the MCP integration, AI assistants can: - Search across all BlockBee documentation with fuzzy matching - Access complete API reference pages and endpoint documentation - Retrieve get-started guides, tutorials, and integration examples - Find specific information about authentication, error handling, and webhooks - Get real-time documentation updates and access to the latest content - Navigate through the complete documentation structure programmatically ## Example Request Here's how an AI assistant would use MCP to interact with BlockBee: ```typescript // AI Assistant can now: // 1. Search and fetch API documentation // 2. Access complete guides and tutorials // 3. Help debug integration issues using documentation // 4. Provide real-time documentation assistance // Example: Searching for authentication information const authResults = await mcp.blockbee.search_docs("authentication"); // Example: Getting specific documentation const paymentFlowDoc = await mcp.blockbee.get_doc("doc://remote/api/raw/get-started/custom-payment-flow"); ``` ### Available MCP Functions The BlockBee MCP integration provides direct access to: - **`ping(name?)`**: Health check for the MCP connection - **`docs_status()`**: Check if documentation is loaded and get basic stats - **`refresh_docs(maxPages?, timeout?)`**: Fetch and cache documentation pages from the sitemap - **`list_pages(prefix?, limit?)`**: List available documentation pages with optional filtering - **`search_docs(query, limit?)`**: Search across all documentation with fuzzy matching - **`get_doc(uri)`**: Retrieve complete documentation pages by URI - **`get_section(uri, heading)`**: Get specific sections from documentation by heading text These functions give you programmatic access to BlockBee's complete documentation ecosystem. ### Practical Examples Here are some ways you can use the MCP integration: ```typescript // Search for specific documentation const authResults = await mcp.blockbee.search_docs("auth", 5); // Returns: authentication, checkout-payments, webhooks, etc. // Get specific documentation pages const authDoc = await mcp.blockbee.get_doc("doc://remote/api/raw/get-started/authentication"); // Returns: Complete authentication guide with API key types, security practices // Access API endpoint documentation const endpointDoc = await mcp.blockbee.get_doc("doc://remote/api/raw/api/create-checkout"); // Returns: Complete checkout request API documentation // Find error handling information const errorDocs = await mcp.blockbee.search_docs("error handling", 3); // Returns: Error handling guides and related documentation // Get specific sections from documents const apiKeySection = await mcp.blockbee.get_section("doc://remote/api/raw/get-started/authentication", "API Key Types"); // Returns: Specific section about API key types and use cases // List available pages const allPages = await mcp.blockbee.list_pages(null, 20); // Returns: List of all available documentation pages // Health check const status = await mcp.blockbee.ping("BlockBee MCP"); // Returns: Connection status confirmation ``` ## API Reference Once connected via MCP, you'll have access to: - **Complete API Reference**: All endpoints, parameters, and responses - **Webhook Documentation**: Webhook setup and verification guides - **Integration Examples**: Code samples in multiple programming languages - **Error Codes**: Comprehensive error handling documentation > **SUCCESS** >**Ready to Connect?** Set up MCP integration and start building with AI assistance! 🚀 ### Choose Your BlockBee Product Select the BlockBee product you want to use for your integration: - **Payment Processing**: [Checkout Payments](/get-started/checkout-payments) - Hosted checkout solution for one-time crypto payments - **Deposit Management**: [Checkout Deposits](/get-started/checkout-deposits) - Reusable deposit links for multiple payments over time - **Custom Integration**: [Custom Payment Flow](/get-started/custom-payment-flow) - Build fully customized payment experiences - **Wallet Management**: [Tickers](/get-started/tickers) - Specify cryptocurrencies and tokens in API requests - **Self-Custodial**: [Self-Custodial Wallet](/get-started/self-custodial-wallet) - Full control over funds with automated payouts - **Payouts**: [Payouts](/get-started/payouts) - Send crypto payments to multiple addresses automatically - **Recurring Payments**: [Subscriptions](/get-started/subscriptions) - Automated recurring crypto payments for services - **E-commerce**: [E-commerce Platforms](/get-started/ecommerce) - Plug-and-play integrations for popular platforms - **Storefront**: [Storefront](/get-started/storefront) - Complete hosted online store with crypto payments **Need help getting started?** Check out our [Authentication](/get-started/authentication) guide and [API Reference](/api/). --- # Custom Payment Flow > Source: https://docs.blockbee.io/get-started/custom-payment-flow > Description: Build a fully customized cryptocurrency payment experience with complete control over the user interface and flow. # Custom Payment Flow Build a fully customized cryptocurrency payment experience with complete control over the user interface and payment flow. This guide will walk you through creating a payment from scratch using BlockBee's API. ![Example of BlockBee's Custom Payment Flow taken from WooCommerce Plugin](/assets/images/custom-flow-integration.jpg) *Example of BlockBee's Custom Payment Flow taken from WooCommerce Plugin* ## Overview The custom payment flow gives you maximum flexibility to create the exact payment experience you want. You'll handle: - **Payment creation** - Generate payment addresses and amounts - **User interface** - Build your own payment screens - **Webhook handling** - Process the webhooks with the payment confirmations > **INFO** >**Estimated time:** 30-45 minutes for a basic implementation ## Setup Before you can start building custom payment flows, you need to configure your BlockBee account and get your API credentials. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Generate API Key 1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard 2. Click "Generate New API Key" 3. Copy the generated API key - you'll need this for all API requests > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to generate an API Key. > **WARNING** >**Keep your API key secure:** Never expose your API key in client-side code or public repositories. Store it securely in environment variables or server-side configuration. > **WARNING** >**Minimum Transaction Amounts:** Every cryptocurrency has minimum transaction amounts on different blockchains. Transactions below these minimums will be **ignored by BlockBee systems and funds will be lost**. Always check the minimum amounts for your chosen cryptocurrencies before accepting payments. You can find the complete list at [blockbee.io/cryptocurrencies](https://blockbee.io/cryptocurrencies) or fetch them using the [info endpoint](/api/get-ticker-info). ## Step 1: Create Payment First, create a new payment by calling the BlockBee API. You'll need your API key and the payment details. ```javascript // Create a new payment const createPayment = async (orderId) => { const callbackUrl = encodeURIComponent('https://yoursite.com/webhook?order_id=' + orderId); const params = new URLSearchParams({ callback: callbackUrl, apikey: 'YOUR_API_KEY', address: 'YOUR_WALLET_ADDRESS', post: 0, json: 0, pending: 1, multi_token: 0, convert: 1 }); const response = await fetch(`https://api.blockbee.io/btc/create/?${params}`); const data = await response.json(); return data; }; ``` ```php <?php function createPayment($orderId) { $callbackUrl = urlencode('https://yoursite.com/webhook?order_id=' . $orderId); $params = http_build_query([ 'callback' => $callbackUrl, 'apikey' => 'YOUR_API_KEY', 'address' => 'YOUR_WALLET_ADDRESS', 'post' => 0, 'json' => 0, 'pending' => 1, 'multi_token' => 0, 'convert' => 1 ]); $url = 'https://api.blockbee.io/btc/create/?' . $params; $result = file_get_contents($url); return json_decode($result, true); } ?> ``` ```python import requests from urllib.parse import quote def create_payment(order_id): callback_url = quote(f'https://yoursite.com/webhook?order_id={order_id}') params = { 'callback': callback_url, 'apikey': 'YOUR_API_KEY', 'address': 'YOUR_WALLET_ADDRESS', 'post': 0, 'json': 0, 'pending': 1, 'multi_token': 0, 'convert': 1 } response = requests.get('https://api.blockbee.io/btc/create/', params=params) return response.json() ``` ```ruby require 'net/http' require 'json' require 'uri' def create_payment(order_id) callback_url = URI.encode_www_form_component("https://yoursite.com/webhook?order_id=#{order_id}") params = { callback: callback_url, apikey: 'YOUR_API_KEY', address: 'YOUR_WALLET_ADDRESS', post: 0, json: 0, pending: 1, multi_token: 0, convert: 1 } query_string = URI.encode_www_form(params) uri = URI("https://api.blockbee.io/btc/create/?#{query_string}") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Get.new(uri) response = http.request(request) JSON.parse(response.body) end ``` ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using System.Web; using Newtonsoft.Json; public class PaymentService { private static readonly HttpClient client = new HttpClient(); public async Task<dynamic> CreatePayment(string orderId) { var callbackUrl = HttpUtility.UrlEncode($"https://yoursite.com/webhook?order_id={orderId}"); var queryParams = HttpUtility.ParseQueryString(string.Empty); queryParams["callback"] = callbackUrl; queryParams["apikey"] = "YOUR_API_KEY"; queryParams["address"] = "YOUR_WALLET_ADDRESS"; queryParams["post"] = "0"; queryParams["json"] = "0"; queryParams["pending"] = "1"; queryParams["multi_token"] = "0"; queryParams["convert"] = "1"; var url = $"https://api.blockbee.io/btc/create/?{queryParams}"; var response = await client.GetAsync(url); var result = await response.Content.ReadAsStringAsync(); return JsonConvert.DeserializeObject(result); } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import com.google.gson.Gson; import java.util.Map; public class PaymentService { private static final HttpClient client = HttpClient.newHttpClient(); private static final Gson gson = new Gson(); public Map<String, Object> createPayment(String orderId) { try { String callbackUrl = URLEncoder.encode( "https://yoursite.com/webhook?order_id=" + orderId, StandardCharsets.UTF_8 ); String url = "https://api.blockbee.io/btc/create/" + "?callback=" + callbackUrl + "&apikey=YOUR_API_KEY" + "&address=YOUR_WALLET_ADDRESS" + "&post=0" + "&json=0" + "&pending=1" + "&multi_token=0" + "&convert=1"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); return gson.fromJson(response.body(), Map.class); } catch (Exception e) { throw new RuntimeException("Payment creation failed", e); } } } ``` ```go package main import ( "encoding/json" "net/http" "net/url" "io/ioutil" "fmt" ) func createPayment(orderID string) (map[string]interface{}, error) { callbackURL := url.QueryEscape(fmt.Sprintf("https://yoursite.com/webhook?order_id=%s", orderID)) params := url.Values{} params.Add("callback", callbackURL) params.Add("apikey", "YOUR_API_KEY") params.Add("address", "YOUR_WALLET_ADDRESS") params.Add("post", "0") params.Add("json", "0") params.Add("pending", "1") params.Add("multi_token", "0") params.Add("convert", "1") apiURL := fmt.Sprintf("https://api.blockbee.io/btc/create/?%s", params.Encode()) resp, err := http.Get(apiURL) if err != nil { return nil, err } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { return nil, err } var result map[string]interface{} json.Unmarshal(body, &result) return result, nil } ``` ```bash # URL encode the callback parameter CALLBACK_URL=$(echo "https://yoursite.com/webhook?order_id=12345" | jq -rR @uri) curl -G "https://api.blockbee.io/btc/create/" \ --data-urlencode "callback=${CALLBACK_URL}" \ --data-urlencode "apikey=YOUR_API_KEY" \ --data-urlencode "address=YOUR_WALLET_ADDRESS" \ --data-urlencode "post=0" \ --data-urlencode "json=0" \ --data-urlencode "pending=1" \ --data-urlencode "multi_token=0" \ --data-urlencode "convert=1" ``` > **INFO: Using Our Official Libraries** >For a simpler integration, you can also use our official libraries. Here's how you would create a custom payment: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const callbackUrl = 'https://yoursite.com/webhook'; > const params = { > order_id: orderId, > }; > const blockbeeParams = { > post: 0, > json: 0, > pending: 1, > multi_token: 0, > convert: 1 > }; > > const bb = new BlockBee('btc', 'YOUR_WALLET_ADDRESS', callbackUrl, params, blockbeeParams, 'YOUR_API_KEY'); > const address = await bb.getAddress(); > // address.address_in > ``` > > ```php > // Using the official PHP library > $params = ['order_id' => $orderId]; > $blockbeeParams = [ > 'post' => 0, > 'json' => 0, > 'pending' => 1, > 'multi_token' => 0, > 'convert' => 1 > ]; > > $bb = new BlockBee\BlockBee('btc', 'YOUR_WALLET_ADDRESS', 'https://yoursite.com/webhook', $params, $blockbeeParams, 'YOUR_API_KEY'); > $address = $bb->get_address(); > // $address->address_in > ``` > > ```python > # Using the official Python library > from blockbee import BlockBeeHelper > > params = {'order_id': orderId} > bb_params = { > 'post': 0, > 'json': 0, > 'pending': 1, > 'multi_token': 0, > 'convert': 1 > } > > bb = BlockBeeHelper('btc', 'YOUR_WALLET_ADDRESS', 'https://yoursite.com/webhook', params, bb_params, 'YOUR_API_KEY') > address = bb.get_address() > # address['address_in'] > ``` > > You can find the full documentation for our libraries here: > - [Node.js Library](/libraries/nodejs) > - [PHP Library](/libraries/php) > - [Python Library](/libraries/python) Check the API Reference to understand all the parameters you can use with this endpoint. - [GET /{ticker}/create/](../api/create-payment-address): Create New Payment Address **Parameter Notes:** * **`callback`** - Add query parameters to help track payments when receiving webhooks (e.g., `?order_id=123&user_id=456`) * **`address`** (optional) - Your wallet address where payments will be forwarded. By default, addresses are set in [Dashboard](https://dash.blockbee.io/profile/addresses), 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](https://dash.blockbee.io/profile/addresses), you can ignore this parameter and leave it empty. * **`pending`** - Set to `1` to receive webhooks for unconfirmed transactions (recommended for better UX) * **`convert`** - Set to `1` to automatically convert received payments to your preferred currency * **`post`** - Set to `1` to receive webhooks via POST instead of GET requests (default is GET) * **`json`** - Set to `1` to receive webhook data in JSON format instead of URL-encoded parameters (works with both GET and POST) * **`multi_token`** - Only relevant for blockchains with tokens (Ethereum, Solana, Tron). Set to `1` to accept multiple token types **Payment Splitting:** To split payments between multiple addresses, use: `percentage_1@address_1|percentage_2@address_2` Example: `0.5@ADDRESS_1|0.5@ADDRESS_2` splits 50/50 between two addresses. **Response:** ```json { "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu", "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP", "callback_url": "https://yoursite.com/webhook?order_id=12345", "priority": "default", "minimum_transaction_coin": 0.008, "status": "success" } ``` > **WARNING** >**Important:** Store both the `address_in` and `callback_url` values from the response: > - **`address_in`** - The unique payment address your customer will send cryptocurrency to > - **`callback_url`** - Acts as a permanent identifier that links to this specific payment setup > > **Address Persistence:** The `callback_url` works as an "ID" that permanently associates with the `address_out` (your destination address). Once set, the `address_out` cannot be changed for that callback URL, even if you provide a different address in future API calls. This ensures payment consistency and prevents accidental address changes. > > **Logs Integration:** The exact `callback_url` returned from this response can be used with the logs endpoint to track payments and transaction history without relying on webhooks. > > **To change the destination address:** You must use a different `callback` (e.g., add a version parameter like `?order_id=123&v=2`) to create a new payment setup with a different `address_out`. ## Step 2: Display Payment Information Create a payment interface that shows the customer how to complete their payment. You have two main scenarios depending on your use case: ### Scenario A: Exchange Deposits (Any Amount) For exchanges or services accepting any amount above the minimum, fetch the minimum transaction requirements and display them to users. ### Scenario B: Ecommerce Payments (Specific Amount) For stores with fixed prices, convert your fiat amount to cryptocurrency using real-time exchange rates. Let's implement both scenarios: > **INFO: Using Our Official Libraries** >You can also use our official libraries for these API calls. Here's how you would get ticker info, convert currencies, and generate QR codes: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > // Get ticker information and minimums > const tickerInfo = await BlockBee.getInfo('btc', 'YOUR_API_KEY'); > // tickerInfo.minimum_transaction_coin > > // Convert USD to BTC for ecommerce payments > const conversion = await BlockBee.getConvert('btc', usdAmount, 'USD', 'YOUR_API_KEY'); > // conversion.value_coin > > // Get QR code for payment address > const qrCode = await BlockBee.getQrcode('btc', address, amount, size, 'YOUR_API_KEY'); > // qrCode.qr_code (base64 image) > ``` > > ```php > // Using the official PHP library > // Get ticker information and minimums > $tickerInfo = BlockBee\BlockBee::get_info('btc', 'YOUR_API_KEY'); > // $tickerInfo->minimum_transaction_coin > > // Convert USD to BTC for ecommerce payments > $conversion = BlockBee\BlockBee::get_convert('btc', $usdAmount, 'USD', 'YOUR_API_KEY'); > // $conversion->value_coin > > // Get QR code for payment address > $qrCode = BlockBee\BlockBee::get_qrcode('btc', $address, $amount, $size, 'YOUR_API_KEY'); > // $qrCode->qr_code (base64 image) > ``` > > ```python > # Using the official Python library > from blockbee import BlockBeeHelper > > # Get ticker information and minimums > ticker_info = BlockBeeHelper.get_info('btc', 'YOUR_API_KEY') > # ticker_info['minimum_transaction_coin'] > > # Convert USD to BTC for ecommerce payments > conversion = BlockBeeHelper.get_convert('btc', usd_amount, 'USD', 'YOUR_API_KEY') > # conversion['value_coin'] > > # Get QR code for payment address > qr_code = BlockBeeHelper.get_qrcode('btc', address, amount, size, 'YOUR_API_KEY') > # qr_code['qr_code'] (base64 image) > ``` ```javascript // Get ticker information and minimums const getTickerInfo = async () => { const response = await fetch('https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY'); const data = await response.json(); return data; }; // Convert USD to BTC for ecommerce payments const convertAmount = async (usdAmount) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', value: usdAmount, from: 'USD' }); const response = await fetch(`https://api.blockbee.io/btc/convert/?${params}`); const data = await response.json(); return data.value_coin; // BTC amount }; // Get QR code for payment address const getQRCode = async (address, amount = null) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', address: address, size: 200 }); if (amount) { params.append('value', amount); } const response = await fetch(`https://api.blockbee.io/btc/qrcode/?${params}`); const data = await response.json(); return data.qr_code; // Base64 image }; // Display payment information - Exchange Deposits const displayExchangeDeposit = async (paymentData) => { const tickerInfo = await getTickerInfo(); const qrCode = await getQRCode(paymentData.address_in); const paymentContainer = document.getElementById('payment-container'); paymentContainer.innerHTML = ` <div class="payment-info"> <h3>Deposit Bitcoin</h3> <div class="payment-details"> <p><strong>Minimum Deposit:</strong> ${tickerInfo.minimum_transaction_coin} BTC</p> <p><strong>Send Bitcoin to:</strong></p> <div class="address-container"> <code>${paymentData.address_in}</code> <button onclick="copyAddress('${paymentData.address_in}')">Copy</button> </div> <div class="qr-code"> <img src="data:image/png;base64,${qrCode}" alt="Payment QR Code" /> </div> <p class="warning">⚠️ Send only amounts above ${tickerInfo.minimum_transaction_coin} BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for deposit...</p> </div> </div> `; }; // Display payment information - Ecommerce Payment const displayEcommercePayment = async (paymentData, usdAmount) => { const btcAmount = await convertAmount(usdAmount); const tickerInfo = await getTickerInfo(); const minimumAmount = tickerInfo.minimum_transaction_coin; // Validate minimum amount if (btcAmount < minimumAmount) { const paymentContainer = document.getElementById('payment-container'); paymentContainer.innerHTML = ` <div class="payment-error"> <h3>❌ Payment Amount Too Low</h3> <div class="error-details"> <p><strong>Your payment amount:</strong> ${btcAmount} BTC</p> <p><strong>Minimum required:</strong> ${minimumAmount} BTC</p> <p class="warning">⚠️ Payments below the minimum will be lost. Please increase your order amount.</p> </div> </div> `; return; } const qrCode = await getQRCode(paymentData.address_in, btcAmount); const paymentContainer = document.getElementById('payment-container'); paymentContainer.innerHTML = ` <div class="payment-info"> <h3>Complete Your Payment</h3> <div class="payment-details"> <p><strong>Amount:</strong> $${usdAmount} USD (${btcAmount} BTC)</p> <p><strong>Send exactly:</strong></p> <div class="amount-container"> <code>${btcAmount} BTC</code> <button onclick="copyAmount('${btcAmount}')">Copy Amount</button> </div> <p><strong>To address:</strong></p> <div class="address-container"> <code>${paymentData.address_in}</code> <button onclick="copyAddress('${paymentData.address_in}')">Copy Address</button> </div> <div class="qr-code"> <img src="data:image/png;base64,${qrCode}" alt="Payment QR Code" /> <p><small>QR code includes amount and address</small></p> </div> <p class="minimum-warning">⚠️ Minimum transaction amount: ${minimumAmount} BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for payment...</p> </div> </div> `; }; const copyAddress = (address) => { navigator.clipboard.writeText(address); alert('Address copied to clipboard!'); }; const copyAmount = (amount) => { navigator.clipboard.writeText(amount); alert('Amount copied to clipboard!'); }; ``` ```php <?php // Get ticker information and minimums function getTickerInfo() { $url = 'https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY'; $result = file_get_contents($url); return json_decode($result, true); } // Convert USD to BTC for ecommerce payments function convertAmount($usdAmount) { $params = http_build_query([ 'apikey' => 'YOUR_API_KEY', 'value' => $usdAmount, 'from' => 'USD' ]); $url = 'https://api.blockbee.io/btc/convert/?' . $params; $result = file_get_contents($url); $data = json_decode($result, true); return $data['value_coin']; // BTC amount } // Get QR code for payment address function getQRCode($address, $amount = null) { $params = [ 'apikey' => 'YOUR_API_KEY', 'address' => $address, 'size' => 200 ]; if ($amount) { $params['value'] = $amount; } $url = 'https://api.blockbee.io/btc/qrcode/?' . http_build_query($params); $result = file_get_contents($url); $data = json_decode($result, true); return $data['qr_code']; // Base64 image } // Display payment information - Exchange Deposits function displayExchangeDeposit($paymentData) { $tickerInfo = getTickerInfo(); $qrCode = getQRCode($paymentData['address_in']); $address = htmlspecialchars($paymentData['address_in']); $minimum = $tickerInfo['minimum_transaction_coin']; echo " <div class='payment-info'> <h3>Deposit Bitcoin</h3> <div class='payment-details'> <p><strong>Minimum Deposit:</strong> $minimum BTC</p> <p><strong>Send Bitcoin to:</strong></p> <div class='address-container'> <code>$address</code> <button onclick='copyAddress(\"$address\")'>Copy</button> </div> <div class='qr-code'> <img src='data:image/png;base64,$qrCode' alt='Payment QR Code' /> </div> <p class='warning'>⚠️ Send only amounts above $minimum BTC</p> </div> <div class='payment-status'> <p id='status'>⏳ Waiting for deposit...</p> </div> </div> "; } // Display payment information - Ecommerce Payment function displayEcommercePayment($paymentData, $usdAmount) { $btcAmount = convertAmount($usdAmount); $tickerInfo = getTickerInfo(); $minimumAmount = $tickerInfo['minimum_transaction_coin']; // Validate minimum amount if ($btcAmount < $minimumAmount) { echo " <div class='payment-error'> <h3>❌ Payment Amount Too Low</h3> <div class='error-details'> <p><strong>Your payment amount:</strong> $btcAmount BTC</p> <p><strong>Minimum required:</strong> $minimumAmount BTC</p> <p class='warning'>⚠️ Payments below the minimum will be lost. Please increase your order amount.</p> </div> </div> "; return; } $qrCode = getQRCode($paymentData['address_in'], $btcAmount); $address = htmlspecialchars($paymentData['address_in']); echo " <div class='payment-info'> <h3>Complete Your Payment</h3> <div class='payment-details'> <p><strong>Amount:</strong> $$usdAmount USD ($btcAmount BTC)</p> <p><strong>Send exactly:</strong></p> <div class='amount-container'> <code>$btcAmount BTC</code> <button onclick='copyAmount(\"$btcAmount\")'>Copy Amount</button> </div> <p><strong>To address:</strong></p> <div class='address-container'> <code>$address</code> <button onclick='copyAddress(\"$address\")'>Copy Address</button> </div> <div class='qr-code'> <img src='data:image/png;base64,$qrCode' alt='Payment QR Code' /> <p><small>QR code includes amount and address</small></p> </div> <p class='minimum-warning'>⚠️ Minimum transaction amount: $minimumAmount BTC</p> </div> <div class='payment-status'> <p id='status'>⏳ Waiting for payment...</p> </div> </div> "; } ?> ``` ```python import requests # Get ticker information and minimums def get_ticker_info(): response = requests.get('https://api.blockbee.io/btc/info/', params={'apikey': 'YOUR_API_KEY'}) return response.json() # Convert USD to BTC for ecommerce payments def convert_amount(usd_amount): params = { 'apikey': 'YOUR_API_KEY', 'value': usd_amount, 'from': 'USD' } response = requests.get('https://api.blockbee.io/btc/convert/', params=params) data = response.json() return data['value_coin'] # BTC amount # Get QR code for payment address def get_qr_code(address, amount=None): params = { 'apikey': 'YOUR_API_KEY', 'address': address, 'size': 200 } if amount: params['value'] = amount response = requests.get('https://api.blockbee.io/btc/qrcode/', params=params) data = response.json() return data['qr_code'] # Base64 image # Display payment information - Exchange Deposits def display_exchange_deposit(payment_data): ticker_info = get_ticker_info() qr_code = get_qr_code(payment_data['address_in']) context = { 'address': payment_data['address_in'], 'minimum': ticker_info['minimum_transaction_coin'], 'qr_code': qr_code } return render_template('exchange_deposit.html', **context) # Display payment information - Ecommerce Payment def display_ecommerce_payment(payment_data, usd_amount): btc_amount = convert_amount(usd_amount) ticker_info = get_ticker_info() minimum_amount = ticker_info['minimum_transaction_coin'] # Validate minimum amount if btc_amount < minimum_amount: context = { 'error': True, 'payment_amount': btc_amount, 'minimum_amount': minimum_amount } return render_template('payment_error.html', **context) qr_code = get_qr_code(payment_data['address_in'], btc_amount) context = { 'address': payment_data['address_in'], 'usd_amount': usd_amount, 'btc_amount': btc_amount, 'qr_code': qr_code, 'minimum_amount': minimum_amount } return render_template('ecommerce_payment.html', **context) # exchange_deposit.html template """ <div class="payment-info"> <h3>Deposit Bitcoin</h3> <div class="payment-details"> <p><strong>Minimum Deposit:</strong> {{ minimum }} BTC</p> <p><strong>Send Bitcoin to:</strong></p> <div class="address-container"> <code>{{ address }}</code> <button onclick="copyAddress('{{ address }}')">Copy</button> </div> <div class="qr-code"> <img src="data:image/png;base64,{{ qr_code }}" alt="Payment QR Code" /> </div> <p class="warning">⚠️ Send only amounts above {{ minimum }} BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for deposit...</p> </div> </div> """ # payment_error.html template """ <div class="payment-error"> <h3>❌ Payment Amount Too Low</h3> <div class="error-details"> <p><strong>Your payment amount:</strong> {{ payment_amount }} BTC</p> <p><strong>Minimum required:</strong> {{ minimum_amount }} BTC</p> <p class="warning">⚠️ Payments below the minimum will be lost. Please increase your order amount.</p> </div> </div> """ # ecommerce_payment.html template """ <div class="payment-info"> <h3>Complete Your Payment</h3> <div class="payment-details"> <p><strong>Amount:</strong> ${{ usd_amount }} USD ({{ btc_amount }} BTC)</p> <p><strong>Send exactly:</strong></p> <div class="amount-container"> <code>{{ btc_amount }} BTC</code> <button onclick="copyAmount('{{ btc_amount }}')">Copy Amount</button> </div> <p><strong>To address:</strong></p> <div class="address-container"> <code>{{ address }}</code> <button onclick="copyAddress('{{ address }}')">Copy Address</button> </div> <div class="qr-code"> <img src="data:image/png;base64,{{ qr_code }}" alt="Payment QR Code" /> <p><small>QR code includes amount and address</small></p> </div> <p class="minimum-warning">⚠️ Minimum transaction amount: {{ minimum_amount }} BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for payment...</p> </div> </div> """ ``` ```ruby # Using Rails/Sinatra def display_payment(payment_data, amount) @address = payment_data['address_in'] @amount = amount # Get minimum transaction amount require 'net/http' require 'json' uri = URI("https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY") response = Net::HTTP.get(uri) ticker_info = JSON.parse(response) @minimum_amount = ticker_info['minimum_transaction_coin'] @qr_url = "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=#{@address}" erb :payment end # payment.erb template """ <div class="payment-info"> <h3>Complete Your Payment</h3> <div class="payment-details"> <p><strong>Amount:</strong> <%= @amount %> USD</p> <p><strong>Send Bitcoin to:</strong></p> <div class="address-container"> <code><%= @address %></code> <button onclick="copyAddress('<%= @address %>')">Copy</button> </div> <div class="qr-code"> <img src="<%= @qr_url %>" alt="Payment QR Code" /> </div> <p class="minimum-warning">⚠️ Minimum transaction amount: <%= @minimum_amount %> BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for payment...</p> </div> </div> """ ``` ```csharp // Using ASP.NET Core public class PaymentViewModel { public string Address { get; set; } public decimal Amount { get; set; } public string QrUrl { get; set; } public decimal MinimumAmount { get; set; } } public async Task<IActionResult> DisplayPayment(dynamic paymentData, decimal amount) { // Get minimum transaction amount using var client = new HttpClient(); var response = await client.GetAsync("https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY"); var result = await response.Content.ReadAsStringAsync(); var tickerInfo = JsonConvert.DeserializeObject<dynamic>(result); var minimumAmount = tickerInfo.minimum_transaction_coin; var model = new PaymentViewModel { Address = paymentData.address_in, Amount = amount, QrUrl = $"https://api.qrserver.com/v1/create-qr-code/?size=200x200&data={paymentData.address_in}", MinimumAmount = minimumAmount }; return View(model); } ``` ```java // Using Spring Boot @GetMapping("/payment") public String displayPayment(Model model, @RequestParam String address, @RequestParam double amount) { // Get minimum transaction amount RestTemplate restTemplate = new RestTemplate(); String url = "https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY"; ResponseEntity<Map> response = restTemplate.getForEntity(url, Map.class); Map<String, Object> tickerInfo = response.getBody(); double minimumAmount = (Double) tickerInfo.get("minimum_transaction_coin"); model.addAttribute("address", address); model.addAttribute("amount", amount); model.addAttribute("minimumAmount", minimumAmount); model.addAttribute("qrUrl", "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=" + address); return "payment"; } ``` ```go // Using Go templates type PaymentData struct { Address string Amount float64 QrUrl string MinimumAmount float64 } func displayPayment(w http.ResponseWriter, address string, amount float64) { // Get minimum transaction amount resp, err := http.Get("https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY") if err != nil { http.Error(w, "Failed to get minimum amount", http.StatusInternalServerError) return } defer resp.Body.Close() var tickerInfo map[string]interface{} json.NewDecoder(resp.Body).Decode(&tickerInfo) minimumAmount := tickerInfo["minimum_transaction_coin"].(float64) data := PaymentData{ Address: address, Amount: amount, QrUrl: fmt.Sprintf("https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=%s", address), MinimumAmount: minimumAmount, } tmpl := template.Must(template.ParseFiles("payment.html")) tmpl.Execute(w, data) } ``` ```bash # Get minimum transaction amount first MINIMUM_AMOUNT=$(curl -s "https://api.blockbee.io/btc/info/?apikey=YOUR_API_KEY" | jq -r '.minimum_transaction_coin') # Static HTML example with minimum amount echo '<div class="payment-info"> <h3>Complete Your Payment</h3> <div class="payment-details"> <p><strong>Amount:</strong> $AMOUNT USD</p> <p><strong>Send Bitcoin to:</strong></p> <div class="address-container"> <code>$ADDRESS</code> <button onclick="copyAddress('"'"'$ADDRESS'"'"')">Copy</button> </div> <div class="qr-code"> <img src="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=$ADDRESS" alt="Payment QR Code" /> </div> <p class="minimum-warning">⚠️ Minimum transaction amount: '"'"'$MINIMUM_AMOUNT'"'"' BTC</p> </div> <div class="payment-status"> <p id="status">⏳ Waiting for payment...</p> </div> </div>' > payment.html ``` ### Key API Endpoints Used The examples above integrate with these BlockBee API endpoints: 1. **[GET /{ticker}/info/](../api/get-ticker-info)** - Get minimum transaction amounts and ticker information 2. **[GET /{ticker}/convert/](../api/convert-price-by-ticker)** - Convert fiat amounts to cryptocurrency 3. **[GET /{ticker}/qrcode/](../api/generate-qr-code)** - Generate QR codes with optional amount embedding ### Implementation Notes **For Exchange Deposits:** - Fetch minimum transaction requirements using the info endpoint - Display address-only QR codes (no fixed amount) - **Always display minimum deposit requirements prominently** - this is critical to prevent fund loss - Accept any amount above the minimum - **Warn users that amounts below minimum will be lost** **For Ecommerce Payments:** - Convert fiat prices to cryptocurrency using current exchange rates - Generate QR codes that include both address and exact amount - Display both fiat and crypto amounts for clarity - Provide separate copy buttons for address and amount - **Verify the converted amount is above the minimum transaction threshold** - **Always display minimum transaction amount prominently** - even for fixed amounts, users need to know the minimum **Minimum Transaction Amount Handling:** - **Always fetch and display minimum amounts** from the info endpoint for your chosen cryptocurrency - **Always show minimum requirements in your UI** - this is not optional, it prevents fund loss - **Validate amounts before accepting payments** - if a user's payment would be below minimum, show an error - **Display clear warnings** about minimum requirements in your UI - **For ecommerce payments**, ensure your fiat price converts to an amount above the minimum > **WARNING** >**Critical: Minimum Transaction Amounts** > > **Why this matters:** Every cryptocurrency has minimum transaction amounts that vary by blockchain. Transactions below these minimums are **ignored by BlockBee systems and funds will be permanently lost**. > > **What you must do:** > 1. **Always fetch minimum amounts** using the info endpoint for your chosen cryptocurrency > 2. **Display minimum requirements prominently** in your payment UI > 3. **Validate amounts before accepting payments** - show errors for amounts below minimum > > **Example validation:** > ```javascript > // Check if amount meets minimum requirements > const tickerInfo = await getTickerInfo(); > const minimumAmount = tickerInfo.minimum_transaction_coin; > > if (paymentAmount < minimumAmount) { > showError(`Amount too low. Minimum required: ${minimumAmount} ${ticker.toUpperCase()}`); > return; > } > ``` > > **For ecommerce:** Ensure your fiat prices convert to amounts above the minimum. Consider adjusting prices or adding minimum order amounts if necessary. > **INFO** >**QR Code Value Parameter:** The `value` parameter in QR codes may not be compatible with all wallets and exchanges. Some may ignore the amount field, so always display the amount separately as well. > **INFO** >**Template Updates Required:** For the Ruby, C#, Java, Go, and Bash examples above, you'll need to update your payment templates to include the minimum amount display. Add this line to your templates: > > ```html > <p class="minimum-warning">⚠️ Minimum transaction amount: [MINIMUM_AMOUNT] [CURRENCY]</p> > ``` > > Replace `[MINIMUM_AMOUNT]` and `[CURRENCY]` with the appropriate template variables for your framework. > **WARNING** >**Real-time User Notifications:** You should implement an automated way to notify users when their payment/deposit has been received. When BlockBee sends a webhook notification, update your UI immediately to show the payment status change. Consider using: > > - **WebSockets** - For real-time browser updates > - **Server-Sent Events (SSE)** - For live status updates > - **Email notifications** - For payment confirmations > - **Push notifications** - For mobile apps > - **Database polling** - As a fallback method > > Users expect immediate feedback when they send a payment, so don't rely on manual page refreshes! ## Step 3: Track Payments You can track payments using two methods: **Webhooks** (recommended) or **Logs Endpoint** (polling). Most applications use webhooks for real-time updates, but the logs endpoint is useful for troubleshooting or as a backup method. ### Method 1: Webhooks (Recommended) Set up webhook endpoints to receive real-time notifications when payments are received. BlockBee sends two types of webhooks: #### Webhook Types: - **Pending** - Payment detected in mempool but not yet confirmed (particularly useful for slower blockchains like Bitcoin, Litecoin, and Bitcoin Cash) - **Confirmed** - Payment has received the number of confirmations specified in the `confirmations` parameter when creating the payment address For complete webhook field documentation, see **[Custom Payment Flow Webhooks](/webhooks/custom-payment-flow-webhooks)** - includes all fields, examples, and implementation details. > **INFO: Tracking Payments with Custom Parameters** >When creating custom payment flow payments, always add your own query parameters to the `callback` URL to track which order or user the payment belongs to. For example, adding `?order_id=123` or `?user_id=456` will ensure that these parameters are included in the webhook payload as GET parameters. > > This is the recommended way to link a BlockBee payment to a specific order or user in your system. > **INFO** >**Webhook Method & Format:** You control how webhooks are delivered when creating the payment: > > - **Default:** GET requests with URL-encoded parameters > - **`post=1`:** POST requests with data in request body > - **`json=1`:** JSON format (works with both GET and POST) > - **`post=1&json=1`:** POST requests with JSON data in body > > Your webhook endpoint should handle the format you choose during payment creation. #### Webhook Implementation: ```javascript // Express.js webhook handler - handles both GET and POST app.all('/webhook', express.json(), (req, res) => { // Handle both GET (default) and POST (if post=1 was set) const webhookData = req.method === 'GET' ? req.query : req.body; const { uuid, address_in, address_out, txid_in, txid_out, confirmations, value_coin, value_coin_convert, value_forwarded_coin, value_forwarded_coin_convert, fee_coin, coin, price, pending, order_id, user_id } = webhookData; // Note: order_id and user_id come from custom parameters you added to callback URL // Check if we've already processed this transaction const alreadyProcessed = checkTransactionInDatabase(uuid); if (!alreadyProcessed) { if (pending === 1) { // Payment detected but not confirmed console.log(`Pending payment for ${order_id || user_id}: ${value_coin} ${coin.toUpperCase()} to ${address_in}`); console.log(`UUID: ${uuid}, Price: $${price}`); // Store transaction in database with UUID storeTransaction({ uuid: uuid, address_in: address_in, address_out: address_out, txid_in: txid_in, amount: value_coin, coin: coin, price: price, status: 'pending', value_coin_convert: value_coin_convert, processed_at: new Date() }); // Notify user (WebSocket, email, etc.) notifyUser(address_in, 'pending', { uuid: uuid, amount: value_coin, coin: coin, usd_value: value_coin_convert ? JSON.parse(value_coin_convert).USD : null }); } else if (pending === 0) { // Payment confirmed console.log(`Confirmed payment for ${order_id || user_id}: ${value_coin} ${coin.toUpperCase()} to ${address_in}`); console.log(`UUID: ${uuid}, Forwarded: ${value_forwarded_coin}, Fee: ${fee_coin}`); // Update database updateTransaction(uuid, { txid_out: txid_out, confirmations: confirmations, value_forwarded_coin: value_forwarded_coin, value_forwarded_coin_convert: value_forwarded_coin_convert, fee_coin: fee_coin, status: 'confirmed', confirmed_at: new Date() }); // Process order, send confirmation email, etc. processSuccessfulPayment(uuid, { orderId: order_id, userId: user_id, amount: value_coin, forwarded_amount: value_forwarded_coin, fee: fee_coin, coin: coin, confirmations: confirmations }); // Notify user notifyUser(address_in, 'confirmed', { uuid: uuid, amount: value_coin, forwarded_amount: value_forwarded_coin, coin: coin, confirmations: confirmations }); } } else { console.log(`Duplicate webhook received for UUID: ${uuid}`); } // Always respond with *ok* or HTTP 200 to stop retries res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php - handles both GET and POST if ($_SERVER['REQUEST_METHOD'] === 'GET') { // GET request (default) - data in query parameters $data = $_GET; } else { // POST request (if post=1 was set) - data in body $input = file_get_contents('php://input'); if ($_GET['json'] ?? false) { // JSON format (if json=1 was set) $data = json_decode($input, true); } else { // URL-encoded format (default) parse_str($input, $data); } } $address_in = $data['address_in']; $address_out = $data['address_out']; $txid_in = $data['txid_in']; $txid_out = $data['txid_out']; $confirmations = $data['confirmations']; $value = $data['value']; $value_coin = $data['value_coin']; $pending = $data['pending']; $order_id = $data['order_id'] ?? null; // This comes from custom parameter you added to callback URL $user_id = $data['user_id'] ?? null; // This comes from custom parameter you added to callback URL if ($pending === 1) { // Payment detected but not confirmed $identifier = $order_id ?? $user_id ?? 'unknown'; error_log("Pending payment for {$identifier}: {$value_coin} BTC to {$address_in}"); // Update database updatePaymentStatus($address_in, 'pending', [ 'txid' => $txid_in, 'amount' => $value_coin, 'confirmations' => $confirmations ]); // Notify user notifyUser($address_in, 'pending'); } elseif ($confirmations >= 1) { // Payment confirmed $identifier = $order_id ?? $user_id ?? 'unknown'; error_log("Confirmed payment for {$identifier}: {$value_coin} BTC to {$address_in}"); // Update database updatePaymentStatus($address_in, 'confirmed', [ 'txid' => $txid_in, 'amount' => $value_coin, 'confirmations' => $confirmations ]); // Process order processSuccessfulPayment($address_in); // Notify user notifyUser($address_in, 'confirmed'); } http_response_code(200); echo 'OK'; function updatePaymentStatus($address, $status, $data) { // Update your database here // Example: UPDATE payments SET status = ?, data = ? WHERE address = ? } function processSuccessfulPayment($address) { // Process the successful payment // Send confirmation email, fulfill order, etc. } function notifyUser($address, $status) { // Notify user via WebSocket, email, etc. } ?> ``` ```python # Flask webhook handler from flask import Flask, request, jsonify import json @app.route('/webhook', methods=['POST']) def webhook(): data = request.get_json() address_in = data['address_in'] address_out = data['address_out'] txid_in = data['txid_in'] txid_out = data['txid_out'] confirmations = data['confirmations'] value = data['value'] value_coin = data['value_coin'] pending = data['pending'] order_id = data.get('order_id') # This comes from custom parameter you added to callback URL user_id = data.get('user_id') # This comes from custom parameter you added to callback URL if pending == 1: # Payment detected but not confirmed identifier = order_id or user_id or 'unknown' print(f"Pending payment for {identifier}: {value_coin} BTC to {address_in}") // Update database update_payment_status(address_in, 'pending', { 'txid': txid_in, 'amount': value_coin, 'confirmations': confirmations }) // Notify user notify_user(address_in, 'pending') elif confirmations >= 1: # Payment confirmed identifier = order_id or user_id or 'unknown' print(f"Confirmed payment for {identifier}: {value_coin} BTC to {address_in}") // Update database update_payment_status(address_in, 'confirmed', { 'txid': txid_in, 'amount': value_coin, 'confirmations': confirmations }) // Process order process_successful_payment(address_in) // Notify user notify_user(address_in, 'confirmed') return jsonify({'status': 'ok'}), 200 def update_payment_status(address, status, data): // Update your database here pass def process_successful_payment(address): // Process the successful payment pass def notify_user(address, status): // Notify user via WebSocket, email, etc. pass ``` ```ruby # Sinatra webhook handler post '/webhook' do data = JSON.parse(request.body.read) address_in = data['address_in'] address_out = data['address_out'] txid_in = data['txid_in'] txid_out = data['txid_out'] confirmations = data['confirmations'] value = data['value'] value_coin = data['value_coin'] pending = data['pending'] if pending == 1 // Payment detected but not confirmed puts "Pending payment: #{value_coin} BTC to #{address_in}" // Update database update_payment_status(address_in, 'pending', { txid: txid_in, amount: value_coin, confirmations: confirmations }) // Notify user notify_user(address_in, 'pending') elsif confirmations >= 1 // Payment confirmed puts "Confirmed payment: #{value_coin} BTC to #{address_in}" // Update database update_payment_status(address_in, 'confirmed', { txid: txid_in, amount: value_coin, confirmations: confirmations }) // Process order process_successful_payment(address_in) // Notify user notify_user(address_in, 'confirmed') end status 200 'OK' end ``` ```csharp // ASP.NET Core webhook handler [HttpPost("webhook")] public IActionResult Webhook([FromBody] WebhookData data) { if (data.Pending == 1) { // Payment detected but not confirmed _logger.LogInformation($"Pending payment: {data.ValueCoin} BTC to {data.AddressIn}"); // Update database UpdatePaymentStatus(data.AddressIn, "pending", new { Txid = data.TxidIn, Amount = data.ValueCoin, Confirmations = data.Confirmations }); // Notify user NotifyUser(data.AddressIn, "pending"); } else if (data.Confirmations >= 1) { // Payment confirmed _logger.LogInformation($"Confirmed payment: {data.ValueCoin} BTC to {data.AddressIn}"); // Update database UpdatePaymentStatus(data.AddressIn, "confirmed", new { Txid = data.TxidIn, Amount = data.ValueCoin, Confirmations = data.Confirmations }); // Process order ProcessSuccessfulPayment(data.AddressIn); // Notify user NotifyUser(data.AddressIn, "confirmed"); } return Ok("OK"); } public class WebhookData { public string AddressIn { get; set; } public string AddressOut { get; set; } public string TxidIn { get; set; } public string TxidOut { get; set; } public int Confirmations { get; set; } public decimal Value { get; set; } public decimal ValueCoin { get; set; } public int Pending { get; set; } } ``` ```java // Spring Boot webhook handler @PostMapping("/webhook") public ResponseEntity<String> webhook(@RequestBody WebhookData data) { if (data.getPending() == 1) { // Payment detected but not confirmed logger.info("Pending payment: {} BTC to {}", data.getValueCoin(), data.getAddressIn()); // Update database updatePaymentStatus(data.getAddressIn(), "pending", Map.of("txid", data.getTxidIn(), "amount", data.getValueCoin(), "confirmations", data.getConfirmations())); // Notify user notifyUser(data.getAddressIn(), "pending"); } else if (data.getConfirmations() >= 1) { // Payment confirmed logger.info("Confirmed payment: {} BTC to {}", data.getValueCoin(), data.getAddressIn()); // Update database updatePaymentStatus(data.getAddressIn(), "confirmed", Map.of("txid", data.getTxidIn(), "amount", data.getValueCoin(), "confirmations", data.getConfirmations())); // Process order processSuccessfulPayment(data.getAddressIn()); // Notify user notifyUser(data.getAddressIn(), "confirmed"); } return ResponseEntity.ok("OK"); } ``` ```go // Go webhook handler func webhookHandler(w http.ResponseWriter, r *http.Request) { var data WebhookData body, err := ioutil.ReadAll(r.Body) if err != nil { http.Error(w, "Bad request", http.StatusBadRequest) return } if err := json.Unmarshal(body, &data); err != nil { http.Error(w, "Bad request", http.StatusBadRequest) return } if data.Pending == 1 { // Payment detected but not confirmed log.Printf("Pending payment: %s BTC to %s", data.ValueCoin, data.AddressIn) // Update database updatePaymentStatus(data.AddressIn, "pending", map[string]interface{}{ "txid": data.TxidIn, "amount": data.ValueCoin, "confirmations": data.Confirmations, }) // Notify user notifyUser(data.AddressIn, "pending") } else if data.Confirmations >= 1 { // Payment confirmed log.Printf("Confirmed payment: %s BTC to %s", data.ValueCoin, data.AddressIn) // Update database updatePaymentStatus(data.AddressIn, "confirmed", map[string]interface{}{ "txid": data.TxidIn, "amount": data.ValueCoin, "confirmations": data.Confirmations, }) // Process order processSuccessfulPayment(data.AddressIn) // Notify user notifyUser(data.AddressIn, "confirmed") } w.WriteHeader(http.StatusOK) w.Write([]byte("OK")) } type WebhookData struct { AddressIn string `json:"address_in"` AddressOut string `json:"address_out"` TxidIn string `json:"txid_in"` TxidOut string `json:"txid_out"` Confirmations int `json:"confirmations"` Value float64 `json:"value"` ValueCoin string `json:"value_coin"` Pending int `json:"pending"` } ``` ```bash # Test webhook locally with ngrok ngrok http 3000 # Your webhook URL will be: https://abc123.ngrok.io/webhook ``` > **INFO** >**Webhook Reliability & Security:** > > **Response Requirements:** > - Always respond with `*ok*` message or HTTP 200 status code to stop retries > - BlockBee uses exponential backoff: starts at 6 minutes, doubles each retry, stops after 3 days > > **IP Whitelisting:** > - Whitelist these BlockBee server IPs: `51.77.105.132` and `135.125.112.47` > - This prevents security systems (like Cloudflare) from blocking webhooks > > **Common Issues:** > - Wrong token sent to address (e.g., created USDT address but sent TRX) > - Callback URL not reachable online > - Security systems blocking webhook requests > > **Duplicate Prevention:** > - Always check the `uuid` field to prevent processing the same transaction twice > - Store UUIDs in your database before processing any payment ### Method 2: Logs Endpoint (Polling) If webhooks aren't suitable for your setup, or as a backup method, you can use the logs endpoint to check payment status. This is particularly useful for troubleshooting webhook issues or implementing cron jobs to monitor payments. > **INFO: Using Our Official Libraries** >You can also check payment logs using our official libraries: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const bb = new BlockBee('btc', 'YOUR_WALLET_ADDRESS', callbackUrl, params, blockbeeParams, 'YOUR_API_KEY'); > const logs = await bb.checkLogs(); > // logs.callbacks contains the payment history > ``` > > ```php > // Using the official PHP library > $bb = new BlockBee\BlockBee('btc', 'YOUR_WALLET_ADDRESS', $callbackUrl, $params, $blockbeeParams, 'YOUR_API_KEY'); > $logs = $bb->check_logs(); > // $logs->callbacks contains the payment history > ``` > > ```python > # Using the official Python library > from blockbee import BlockBeeHelper > > bb = BlockBeeHelper('btc', 'YOUR_WALLET_ADDRESS', callback_url, params, bb_params, 'YOUR_API_KEY') > logs = bb.get_logs() > # logs['callbacks'] contains the payment history > ``` ```javascript // Check payment status using logs endpoint const checkPaymentStatus = async (callbackUrl) => { const encodedCallback = encodeURIComponent(callbackUrl); const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', callback: encodedCallback }); const response = await fetch(`https://api.blockbee.io/btc/logs/?${params}`); const data = await response.json(); // Check if API request was successful if (data.status !== 'success') { console.error('API request failed:', data); return { error: 'API request failed' }; } if (data.callbacks && data.callbacks.length > 0) { const processedTransactions = []; // Process each transaction for (const callback of data.callbacks) { // Check if transaction is confirmed (pending = 0 in logs) const confirmedLog = callback.logs.find(log => log.pending === 0); const isConfirmed = confirmedLog !== undefined; processedTransactions.push({ uuid: callback.uuid || `${callback.txid_in}-${callback.value_coin}`, // Use UUID or fallback txid: callback.txid_in, amount: callback.value_coin, confirmations: callback.confirmations, status: callback.result, isConfirmed: isConfirmed, lastUpdate: callback.last_update }); } return { transactions: processedTransactions }; } return { transactions: [] }; }; // Process payments with duplicate prevention const processPayments = async (callbackUrl) => { const result = await checkPaymentStatus(callbackUrl); if (result.error) { console.error('Failed to check payment status:', result.error); return; } for (const transaction of result.transactions) { // Check if we've already processed this transaction UUID const alreadyProcessed = await checkTransactionInDatabase(transaction.uuid); if (!alreadyProcessed) { if (transaction.isConfirmed && transaction.status === 'done') { console.log(`New confirmed payment: ${transaction.amount} BTC`); // Store transaction in database with UUID await storeTransaction({ uuid: transaction.uuid, txid: transaction.txid, amount: transaction.amount, confirmations: transaction.confirmations, status: 'confirmed', processed_at: new Date() }); // Process the payment (fulfill order, send confirmation, etc.) await processConfirmedPayment(transaction); } else if (transaction.status === 'pending') { console.log(`New pending payment: ${transaction.amount} BTC`); // Store as pending transaction await storeTransaction({ uuid: transaction.uuid, txid: transaction.txid, amount: transaction.amount, confirmations: transaction.confirmations, status: 'pending', processed_at: new Date() }); // Notify user of pending payment await notifyPendingPayment(transaction); } } } }; // Helper functions (implement based on your database) const checkTransactionInDatabase = async (uuid) => { // Check if transaction UUID exists in your database // Return true if exists, false if new }; const storeTransaction = async (transactionData) => { // Store transaction in your database // Include the UUID to prevent duplicate processing }; const processConfirmedPayment = async (transaction) => { // Process confirmed payment (fulfill order, send email, etc.) }; const notifyPendingPayment = async (transaction) => { // Notify user of pending payment }; ``` ```php <?php // Check payment status using logs endpoint function checkPaymentStatus($callbackUrl) { $encodedCallback = urlencode($callbackUrl); $params = http_build_query([ 'apikey' => 'YOUR_API_KEY', 'callback' => $encodedCallback ]); $url = 'https://api.blockbee.io/btc/logs/?' . $params; $result = file_get_contents($url); $data = json_decode($result, true); // Check if API request was successful if ($data['status'] !== 'success') { error_log('API request failed: ' . json_encode($data)); return ['error' => 'API request failed']; } if (!empty($data['callbacks'])) { $processedTransactions = []; // Process each transaction foreach ($data['callbacks'] as $callback) { // Check if transaction is confirmed (pending = 0 in logs) $isConfirmed = false; foreach ($callback['logs'] as $log) { if ($log['pending'] == 0) { $isConfirmed = true; break; } } $processedTransactions[] = [ 'uuid' => $callback['uuid'] ?? $callback['txid_in'] . '-' . $callback['value_coin'], 'txid' => $callback['txid_in'], 'amount' => $callback['value_coin'], 'confirmations' => $callback['confirmations'], 'status' => $callback['result'], 'isConfirmed' => $isConfirmed, 'lastUpdate' => $callback['last_update'] ]; } return ['transactions' => $processedTransactions]; } return ['transactions' => []]; } // Process payments with duplicate prevention function processPayments($callbackUrl) { $result = checkPaymentStatus($callbackUrl); if (isset($result['error'])) { error_log('Failed to check payment status: ' . $result['error']); return; } foreach ($result['transactions'] as $transaction) { // Check if we've already processed this transaction UUID $alreadyProcessed = checkTransactionInDatabase($transaction['uuid']); if (!$alreadyProcessed) { if ($transaction['isConfirmed'] && $transaction['status'] === 'done') { echo "New confirmed payment: " . $transaction['amount'] . " BTC\n"; // Store transaction in database with UUID storeTransaction([ 'uuid' => $transaction['uuid'], 'txid' => $transaction['txid'], 'amount' => $transaction['amount'], 'confirmations' => $transaction['confirmations'], 'status' => 'confirmed', 'processed_at' => date('Y-m-d H:i:s') ]); // Process the payment (fulfill order, send confirmation, etc.) processConfirmedPayment($transaction); } elseif ($transaction['status'] === 'pending') { echo "New pending payment: " . $transaction['amount'] . " BTC\n"; // Store as pending transaction storeTransaction([ 'uuid' => $transaction['uuid'], 'txid' => $transaction['txid'], 'amount' => $transaction['amount'], 'confirmations' => $transaction['confirmations'], 'status' => 'pending', 'processed_at' => date('Y-m-d H:i:s') ]); // Notify user of pending payment notifyPendingPayment($transaction); } } } } // Helper functions (implement based on your database) function checkTransactionInDatabase($uuid) { // Check if transaction UUID exists in your database // Return true if exists, false if new } function storeTransaction($transactionData) { // Store transaction in your database // Include the UUID to prevent duplicate processing } function processConfirmedPayment($transaction) { // Process confirmed payment (fulfill order, send email, etc.) } function notifyPendingPayment($transaction) { // Notify user of pending payment } ?> ``` ```python import requests from urllib.parse import quote def check_payment_status(callback_url): """Check payment status using logs endpoint""" encoded_callback = quote(callback_url) params = { 'apikey': 'YOUR_API_KEY', 'callback': encoded_callback } response = requests.get('https://api.blockbee.io/btc/logs/', params=params) data = response.json() if data.get('callbacks'): latest_callback = data['callbacks'][0] return { 'status': latest_callback['result'], 'confirmations': latest_callback['confirmations'], 'amount': latest_callback['value_coin'], 'txid': latest_callback['txid_in'] } return {'status': 'no_payments', 'confirmations': 0, 'amount': 0} def poll_payment_status(callback_url): """Use in a cron job or polling function""" status = check_payment_status(callback_url) if status['status'] == 'done': print("Payment confirmed and processed!") # Update database, notify user, etc. elif status['status'] == 'pending': print("Payment detected but not confirmed yet") # Show pending status to user ``` ```ruby require 'net/http' require 'json' require 'uri' def check_payment_status(callback_url) encoded_callback = URI.encode_www_form_component(callback_url) params = { apikey: 'YOUR_API_KEY', callback: encoded_callback } query_string = URI.encode_www_form(params) uri = URI("https://api.blockbee.io/btc/logs/?#{query_string}") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Get.new(uri) response = http.request(request) data = JSON.parse(response.body) if data['callbacks'] && !data['callbacks'].empty? latest_callback = data['callbacks'][0] return { status: latest_callback['result'], confirmations: latest_callback['confirmations'], amount: latest_callback['value_coin'], txid: latest_callback['txid_in'] } end { status: 'no_payments', confirmations: 0, amount: 0 } end def poll_payment_status(callback_url) status = check_payment_status(callback_url) case status[:status] when 'done' puts "Payment confirmed and processed!" # Update database, notify user, etc. when 'pending' puts "Payment detected but not confirmed yet" # Show pending status to user end end ``` ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using System.Web; using Newtonsoft.Json; public class PaymentStatusChecker { private static readonly HttpClient client = new HttpClient(); public async Task<dynamic> CheckPaymentStatus(string callbackUrl) { var encodedCallback = HttpUtility.UrlEncode(callbackUrl); var queryParams = HttpUtility.ParseQueryString(string.Empty); queryParams["apikey"] = "YOUR_API_KEY"; queryParams["callback"] = encodedCallback; var url = $"https://api.blockbee.io/btc/logs/?{queryParams}"; var response = await client.GetAsync(url); var result = await response.Content.ReadAsStringAsync(); var data = JsonConvert.DeserializeObject<dynamic>(result); if (data.callbacks != null && data.callbacks.Count > 0) { var latestCallback = data.callbacks[0]; return new { status = latestCallback.result, confirmations = latestCallback.confirmations, amount = latestCallback.value_coin, txid = latestCallback.txid_in }; } return new { status = "no_payments", confirmations = 0, amount = 0 }; } public async Task PollPaymentStatus(string callbackUrl) { var status = await CheckPaymentStatus(callbackUrl); if (status.status == "done") { Console.WriteLine("Payment confirmed and processed!"); // Update database, notify user, etc. } else if (status.status == "pending") { Console.WriteLine("Payment detected but not confirmed yet"); // Show pending status to user } } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import com.google.gson.Gson; import java.util.Map; public class PaymentStatusChecker { private static final HttpClient client = HttpClient.newHttpClient(); private static final Gson gson = new Gson(); public Map<String, Object> checkPaymentStatus(String callbackUrl) { try { String encodedCallback = URLEncoder.encode(callbackUrl, StandardCharsets.UTF_8); String url = "https://api.blockbee.io/btc/logs/" + "?apikey=YOUR_API_KEY" + "&callback=" + encodedCallback; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); Map<String, Object> data = gson.fromJson(response.body(), Map.class); if (data.containsKey("callbacks") && !((java.util.List) data.get("callbacks")).isEmpty()) { Map<String, Object> latestCallback = (Map<String, Object>) ((java.util.List) data.get("callbacks")).get(0); return Map.of( "status", latestCallback.get("result"), "confirmations", latestCallback.get("confirmations"), "amount", latestCallback.get("value_coin"), "txid", latestCallback.get("txid_in") ); } return Map.of("status", "no_payments", "confirmations", 0, "amount", 0); } catch (Exception e) { throw new RuntimeException("Payment status check failed", e); } } public void pollPaymentStatus(String callbackUrl) { Map<String, Object> status = checkPaymentStatus(callbackUrl); if ("done".equals(status.get("status"))) { System.out.println("Payment confirmed and processed!"); // Update database, notify user, etc. } else if ("pending".equals(status.get("status"))) { System.out.println("Payment detected but not confirmed yet"); // Show pending status to user } } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "io/ioutil" ) type PaymentStatus struct { Status string `json:"status"` Confirmations int `json:"confirmations"` Amount float64 `json:"amount"` Txid string `json:"txid"` } func checkPaymentStatus(callbackURL string) (*PaymentStatus, error) { encodedCallback := url.QueryEscape(callbackURL) apiURL := fmt.Sprintf("https://api.blockbee.io/btc/logs/?apikey=YOUR_API_KEY&callback=%s", encodedCallback) resp, err := http.Get(apiURL) if err != nil { return nil, err } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { return nil, err } var data map[string]interface{} json.Unmarshal(body, &data) if callbacks, ok := data["callbacks"].([]interface{}); ok && len(callbacks) > 0 { latestCallback := callbacks[0].(map[string]interface{}) return &PaymentStatus{ Status: latestCallback["result"].(string), Confirmations: int(latestCallback["confirmations"].(float64)), Amount: latestCallback["value_coin"].(float64), Txid: latestCallback["txid_in"].(string), }, nil } return &PaymentStatus{Status: "no_payments", Confirmations: 0, Amount: 0}, nil } func pollPaymentStatus(callbackURL string) { status, err := checkPaymentStatus(callbackURL) if err != nil { fmt.Printf("Error checking payment status: %v\n", err) return } switch status.Status { case "done": fmt.Println("Payment confirmed and processed!") // Update database, notify user, etc. case "pending": fmt.Println("Payment detected but not confirmed yet") // Show pending status to user } } ``` ```bash # Check payment status using logs endpoint CALLBACK_URL=$(echo "https://yoursite.com/webhook?order_id=12345" | jq -rR @uri) curl -G "https://api.blockbee.io/btc/logs/" \ --data-urlencode "apikey=YOUR_API_KEY" \ --data-urlencode "callback=${CALLBACK_URL}" \ | jq '.callbacks[0] | {status: .result, confirmations: .confirmations, amount: .value_coin, txid: .txid_in}' # Use in a cron job script #!/bin/bash check_payment_status() { local callback_url="$1" local encoded_callback=$(echo "$callback_url" | jq -rR @uri) curl -s -G "https://api.blockbee.io/btc/logs/" \ --data-urlencode "apikey=YOUR_API_KEY" \ --data-urlencode "callback=${encoded_callback}" \ | jq -r '.callbacks[0].result // "no_payments"' } # Poll payment status status=$(check_payment_status "https://yoursite.com/webhook?order_id=12345") if [ "$status" = "done" ]; then echo "Payment confirmed and processed!" elif [ "$status" = "pending" ]; then echo "Payment detected but not confirmed yet" fi ``` ### API Reference - **[GET /{ticker}/logs/](../api/get-payment-logs)** - Check payment address logs and webhook history ### Important Implementation Notes **API Status vs Payment Status:** - **`status`** field indicates API request success (`success`/`error`) - **Payment status** is found within the `callbacks` array and `logs` entries **Multiple Transactions:** - Each payment address can receive multiple transactions - Each transaction has a unique `uuid` (or use `txid_in` + `value_coin` as fallback) - **Always store the UUID** in your database to prevent duplicate processing **Confirmation Detection:** - Check `logs` array within each callback - Transaction is confirmed when `pending = 0` in any log entry - Don't rely solely on `result` field - check the logs for confirmation status **Duplicate Prevention:** - Store transaction UUIDs in your database - Check if UUID exists before processing any transaction - This prevents processing the same transaction multiple times ### Payment Status Values The logs endpoint returns different `result` values indicating payment status: - **`pending`** - Transaction is being confirmed by the blockchain - **`sent`** - Payment forwarded to your address but webhook didn't receive valid `*ok*` response - **`done`** - Payment forwarded and webhook sent to your URL with valid `*ok*` response received ### When to Use Each Method **Use Webhooks when:** - You need real-time payment notifications - Your application can receive HTTP requests - You want the most efficient solution **Use Logs Endpoint when:** - Webhooks aren't feasible (firewall restrictions, etc.) - You need to troubleshoot webhook issues - Implementing backup payment monitoring - Running periodic cron jobs to check payment status > **INFO** >**Pro Tip:** Use webhooks as your primary method and logs endpoint as a backup. This ensures you never miss a payment even if webhook delivery fails. ## Testing Your Integration Test your payment flow using real cryptocurrency with minimal cost: ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Low BlockBee fees on small amounts - Real blockchain testing without high costs Simply change your ticker from `btc` to `ltc` in your existing code. **If your integration works with LTC, it will work with any ticker** (`btc`, `eth`, `trc20/usdt`, `bep20/usdc`, etc.) - the API endpoints and webhook structure are identical across all cryptocurrencies. > **TIP** >**Multiple Payment Options:** Since the API is universal across all cryptocurrencies, you can easily offer your customers multiple payment options. Just let them choose their preferred cryptocurrency and use the corresponding ticker in your API calls. The same code handles Bitcoin, Ethereum, USDT (eg `trc20/usdt`), and any other supported cryptocurrency. > > Check the full list of supported cryptocurrencies at [blockbee.io/cryptocurrencies](https://blockbee.io/cryptocurrencies). ### 2. Test with $2 Worth of LTC - Send approximately **$2 USD worth of Litecoin** to test the complete flow - This covers blockchain fees + BlockBee fees with minimal cost - You can buy small amounts of LTC on most exchanges - Test both pending and confirmed webhook states ### 3. Test Checklist - ✅ Payment creation works with LTC - ✅ QR code displays correctly - ✅ Address copying functions - ✅ Pending webhook received (fast with LTC) - ✅ Confirmed webhook received - ✅ UI updates correctly - ✅ Amount calculations are accurate - ✅ Success flow completes ### 4. Testing Environment Setup ```bash # Use ngrok for local webhook testing ngrok http 3000 # Your test webhook URL: https://abc123.ngrok.io/webhook ``` > **TIP** >**Why Litecoin?** With $2 worth of LTC, total fees (blockchain + BlockBee) are typically under $0.10, making it the most cost-effective way to test real payment flows. Once testing is complete, switch to your preferred cryptocurrency for production. > **SUCCESS** >**Ready for production?** Once testing is complete, update your ticker from `ltc` to your preferred cryptocurrency (e.g., `btc`, `eth`, `trc20/usdt`) and update your destination addresses. --- # E-commerce Integration > Source: https://docs.blockbee.io/get-started/ecommerce > Description: Integrate cryptocurrency payments into your e-commerce platform with our ready-made plugins and custom solutions. ## Overview BlockBee provides seamless cryptocurrency payment integration for popular e-commerce platforms. Our plugins enable you to accept Bitcoin, Ethereum, and hundreds of other cryptocurrencies directly in your online store. > **INFO** >**No Coding Required:** Our plugins are designed to be plug-and-play solutions that work out of the box with your existing e-commerce platform. ## Available Plugins We offer official plugins for the most popular e-commerce platforms: ## Available Plugins ### WooCommerce Enable cryptocurrency payments in WordPress stores with automatic order status updates and customer notification system. ![WooCommerce Logo](/assets/images/plugins/woocommerce_logo.png) ### PrestaShop Integrate cryptocurrency payments directly into your PrestaShop store with automatic order processing and real-time payment status updates. ![PrestaShop Logo](/assets/images/plugins/prestashop_logo.png) ### OpenCart Seamless cryptocurrency payment integration for OpenCart stores with multi-store support and mobile-responsive checkout. ![OpenCart Logo](/assets/images/plugins/opencart_logo.png) ### Magento Enterprise-grade cryptocurrency payment processing for Magento stores with advanced order management and detailed reporting. ![Magento Logo](/assets/images/plugins/magento_logo.png) ### Odoo Integrate cryptocurrency payments into Odoo e-commerce and ERP systems with automated accounting and multi-company support. ![Odoo Logo](/assets/images/plugins/odoo_logo.png) > **INFO** >**Need a different platform?** Contact our support team at [support@blockbee.io](mailto:support@blockbee.io) for custom integration solutions. ## Custom Integration Don't see your platform listed? We offer custom integration services for specific e-commerce platforms and requirements. ### Low-Code Solutions For platforms without official plugins, we provide low-code solutions that can be easily integrated into your existing e-commerce platform. **What we offer:** - Custom payment gateway integration - API integration services - Platform-specific development - Testing and deployment support - Ongoing maintenance and updates ### Contact Support If you need a plugin for a specific platform or have custom integration requirements, our support team is here to help. > **INFO** >**Get in Touch:** Contact our support team at [support@blockbee.io](mailto:support@blockbee.io) to discuss your specific integration needs. ### Integration Options - **API Integration:** Use our REST API to build custom payment flows - **Webhook Integration:** Receive real-time payment notifications - **Custom Development:** We can develop platform-specific solutions - **Consultation:** Get expert guidance on the best integration approach ## Getting Started ### 1. Choose Your Platform Select the plugin that matches your e-commerce platform from the list above. ### 2. Get Your API Key Sign up at [dash.blockbee.io](https://dash.blockbee.io) to get your API key. ### 3. Install the Plugin Download and install the appropriate plugin for your platform. ### 4. Configure Settings Enter your API key and configure payment settings in your e-commerce admin panel. ### 5. Test Payments Use our test mode to verify everything works correctly before going live. > **SUCCESS** >**Ready to Start?** Choose your platform above and follow the installation guide to begin accepting cryptocurrency payments in your store! > **WARNING** >**Important:** Always test your integration in test mode before processing real payments. Our support team is available to help with any issues during setup. --- # Error Handling > Source: https://docs.blockbee.io/get-started/error-handling > Description: Understand common error codes, their meanings, and how to handle them when using the BlockBee API. # Error Handling This page covers the errors the BlockBee API returns and how to handle each one. ## Common Issues and Solutions ### Funds Stuck in Address **Issue**: Funds appear to be stuck in a cryptocurrency address and aren't being processed. **Possible Causes**: - Wrong cryptocurrency sent to the address. Eg. requested funds with `bep20/usdt` ticker and sent `bep20/usdc` - Wrong network (e.g., sending ERC-20 tokens to BSC address) - Minimum transaction amount not met **Solutions**: - Check if the address is valid for the specific cryptocurrency - Verify the minimum transaction amount for the cryptocurrency - If the wrong cryptocurrency was sent, contact [support](https://blockbee.io/contacts). ### Transaction Not Confirmed **Issue**: Transaction is sent but remains unconfirmed for an extended period. **Possible Causes**: - Network congestion - Transaction stuck in mempool **Solutions**: - Wait for network confirmation (can take 1-24 hours depending on the network) - Check transaction status using the blockchain explorer ### API Key Issues **Issue**: API requests failing with authentication errors. **Possible Causes**: - Missing or wrong API key in request - Account suspended or deactivated **Solutions**: - Verify your API key in the [BlockBee Dashboard](https://dash.blockbee.io/) - Ensure API key is included in all requests (as parameter or header) - Check if your account is active and in good standing - Generate a new API key if necessary ### Callback URL Problems **Issue**: Webhook notifications not being received. **Possible Causes**: - Invalid or inaccessible callback URL - Server not responding to webhook requests - Firewall blocking incoming requests - SSL certificate issues **Solutions**: - Ensure callback URL is publicly accessible - Test the URL manually to verify it responds - Check server logs for incoming webhook requests - Verify SSL certificate is valid (for HTTPS URLs) - Make sure your webhook signature verification is working - Allowlist BlockBee's IPs (`51.77.105.132` and `135.125.112.47`) in your firewall or Cloudflare rules. ## Error Response Format When a request fails, BlockBee returns JSON with `"status": "error"` and an `"error"` field describing the problem. ```json { "status": "error", "error": "API Key not provided" } ``` ## Common Errors Here are the most common errors organized by HTTP status codes: ### HTTP Status Code: 400 (Bad Request) - ``Non multi_token address already created for another token`` - In [ticker create](/api/create-payment-address) when you try creating an address with the same callback URL for a different [``ticker``](/api/create-payment-address#ticker) without [``multi_token``](/api/create-payment-address#multi_token) parameter enabled - ``Callback URL malformed, please provide a correct URL`` - In [ticker create](/api/create-payment-address) endpoint when the [``callback``](/api/create-payment-address#callback) parameter isn't valid - ``You must provide a valid address`` - In [ticker create](/api/create-payment-address) when the address provided in the [``address``](/api/create-payment-address#address) parameter is not valid - ``Maximum 20 output addresses`` - In [ticker create](/api/create-payment-address) when the amount of addresses provided in the [``address``](/api/create-payment-address#address) parameter exceeds 20 - ``You must provide a valid address and a callback`` - In [ticker create](/api/create-payment-address) when you didn't provide an [``address``](/api/create-payment-address#address) and a [``callback``](/api/create-payment-address#callback) parameter - ``Coin not available`` - Used in payout API when requested coin is not available - ``No data or data malformed`` - Used in payout views when request data is invalid - ``No notify url specified`` - Used in checkout deposit views when notification URL is missing - ``Invalid ticker`` - The specified `{ticker}` is not supported or does not exist. More information about tickers [here](/get-started/tickers) - ``Missing value`` - In [checkout request](/api/create-checkout), the [`value`](/api/create-checkout#value) parameter is missing - ``Address is invalid`` - The provided cryptocurrency address is not valid for the specified network - ``Callback URL is not a valid URL`` - In the [ticker create](/api/create-payment-address), the URL you provided in the [`callback`](/api/create-payment-address#callback) parameter is not a valid, publicly accessible URL - ``Address belongs to BlockBee`` - You are trying to send a payout to one of your own deposit addresses - ``Your request couldn't be processed, please try again later`` - A transient server error. Retry the request after a short delay. - ``No payment options available`` or ``No payment options for this value`` - In [checkout request](/api/create-checkout). No payment options exist for the requested [`value`](/api/create-checkout#value). Check the following: 1. **Payment Settings**: Ensure you have configured your [Payment Settings](https://dash.blockbee.io/profile/checkout) in your dashboard 2. **Receiving Addresses**: Confirm that you have set up receiving addresses for your desired cryptocurrencies at [dash.blockbee.io/profile/addresses](https://dash.blockbee.io/profile/addresses) 3. **Minimum Transaction Amounts**: Check that your requested value meets the minimum transaction requirements for the selected coins. See our [cryptocurrencies list](https://blockbee.io/cryptocurrencies) for specific minimums ### HTTP Status Code: 401 (Unauthorized) - ``KYC Required to use this feature`` - Used when KYC verification is required - ``Your KYC tier is insufficient to use this feature`` - Used when user's KYC level is too low - ``API Key not provided, please use api.cryptapi.io if you don't have an API key`` - Used when API key is missing - ``API Key not valid, please confirm your API key`` - Used when API key is invalid or missing ### HTTP Status Code: 403 (Forbidden) - ``Merchant account deactivated`` - Used when user account is inactive ### HTTP Status Code: 404 (Not Found) - ``Resource not found`` - General 404 error - ``Callback not found`` - When the callback provided in [logs endpoint](/api/get-payment-logs) gave no results ### Additional Common Errors - ``Not enough balance for payout`` - You do not have sufficient balance in your account to process a payout request - ``You need to configure your wallet in the dashboard`` - You have not set up a wallet address for the requested cryptocurrency in your settings --- # Choose Your Integration > Source: https://docs.blockbee.io/get-started/integrations > Description: Pick the BlockBee integration that fits your stack — custom payment flow, hosted checkout, subscriptions, e-commerce plugins, payment links, or no-code tools. # Choose Your Integration Already done the [Quickstart](/get-started)? Pick the integration that fits your product. Each card below links to a full guide. ## Before You Start Before diving into your integration, here are some important things to know: > **INFO** >**BlockBee Account Required**: You need a BlockBee account to get started. Create one for free at [dash.blockbee.io/register](https://dash.blockbee.io/register). > **WARNING** >**Minimum Transaction Amounts**: Every cryptocurrency has minimum transaction amounts on different blockchains. Transactions below these minimums will be **ignored by BlockBee systems and funds will be lost**. Always check the minimum amounts for your chosen cryptocurrencies before accepting payments. You can find the complete list at [blockbee.io/cryptocurrencies](https://blockbee.io/cryptocurrencies) or fetch them using the [info endpoint](/api/get-ticker-info). ## Choose Your Integration Method Pick the approach that best fits your needs and technical requirements: {% section id="developers" %} ### For Developers Build custom integrations with your own UI and flow: {% featureCard title="Custom Payment Flow" description="Build a fully customized payment experience with complete control over the user interface and flow. Perfect for developers who want maximum flexibility." icon="braces" link="/get-started/custom-payment-flow" linkText="Start Building" /%} {% featureCard title="Checkout Payments" description="Process one-time payments with our hosted checkout solution. Perfect for e-commerce, invoicing, and product sales." icon="shopping-cart" link="/get-started/checkout-payments" linkText="Set Up Payments" /%} {% featureCard title="Checkout Deposits" description="Accept cryptocurrency deposits with our hosted checkout pages. Perfect for wallets, exchanges, and deposit-based services." icon="arrow-down" link="/get-started/checkout-deposits" linkText="Set Up Deposits" /%} {% featureCard title="Recurring Subscriptions" description="Set up automated recurring payments for subscription-based services and memberships with our subscription API." icon="refresh-ccw-dot" link="/get-started/subscriptions" linkText="Configure Subscriptions" /%} {% featureCard title="Self-Custodial Wallet" description="Hold your own private keys. BlockBee handles payment routing and automated payouts — you control the funds. Requires API Key V2." icon="wallet" link="/get-started/self-custodial-wallet" linkText="Learn More" /%} {% featureCard title="Automated Payouts" description="Send cryptocurrency payments to multiple addresses automatically using our Self-Custodial Wallet system." icon="arrow-up" link="/get-started/payouts" linkText="Start Payouts" /%} {% featureCard title="Connect to MCP" description="Integrate with BlockBee using the Model Context Protocol for AI-assisted development and seamless API integration." icon="bot" link="/get-started/connect-to-mcp" linkText="Connect Now" /%} {% featureCard title="POS" description="Expand your payment options and increase revenue with our POS App that allows you to easily accept cryptocurrencies in your offline business!" icon="pos" link="/get-started/pos" linkText="Learn More" /%} ### No-Code Solutions Get started without any programming - perfect for non-technical users: {% featureCard title="eCommerce Plugins" description="Ready-made plugins for WordPress, WooCommerce, Shopify, and other popular e-commerce platforms. Install and configure in minutes." icon="blocks" link="/get-started/ecommerce" linkText="Browse Plugins" /%} {% featureCard title="Storefront" description="Launch a complete online store that accepts cryptocurrency payments. No coding required - just configure and go live." icon="store" link="/get-started/storefront" linkText="Create Store" /%} {% featureCard title="Payment Links" description="Generate shareable payment links for invoices, donations, or one-time payments. Share via email, social media, or embed anywhere." icon="link2" link="/get-started/payment-links" linkText="Create Links" /%} {% featureCard title="Telegram Bot" description="Accept cryptocurrency payments directly through Telegram. Perfect for communities, services, and automated sales." icon="telegram" link="/get-started/telegram-bot" linkText="Setup Bot" /%} ## Need Help? - **Support:** Visit our [knowledge base](https://docs.blockbee.io/kb) for tutorials and troubleshooting - **Community:** Join our [Discord server](https://discord.gg/pQaJ32SGrR) for tips and discussions > **INFO** >Pick your integration method above and follow the guide to get your first payment working. --- # Magento Plugin > Source: https://docs.blockbee.io/get-started/magento > Description: Integrate cryptocurrency payments into your Magento store with our official plugin ![Magento Logo](/assets/images/plugins/magento.png) # BlockBee for Magento Accept cryptocurrency payments on your Magento store ## Requirements ``` Magento >= 2.4 Magento >= 2.3.5 ``` ## Download {% button href="https://github.com/blockbee-io/magento-blockbee/releases" variant="default" size="default" %} Download Plugin {% /button %} ## Description Accept payments in Bitcoin, Bitcoin Cash, Litecoin, Ethereum, USDT and Matic directly to your crypto wallet. ### Allow users to pay with crypto directly on your store The BlockBee extension enables your Magento store to get receive payments in cryptocurrency, with a simple setup. ### Accepted cryptocurrencies & tokens include: BlockBee supports 100+ cryptocurrencies and tokens. > **INFO** >View the complete list [here](https://blockbee.io/cryptocurrencies). BlockBee plugin will attempt to automatically convert the value you set on your store to the cryptocurrency your customer chose. Exchange rates are fetched every 5 minutes. ### Supported currencies for automatic exchange rates are: * (USD) US Dollar * (EUR) Euro * (GBP) GB Pound * (CAD) Canadian Dollar * (CHF) Swiss Franc * (JPY) Japanese Yen * (AED) UAE Dollar * (DKK) Danish Krone * (BRL) Brazilian Real * (CNY) Chinese Yuan * (HKD) Hong Kong Dollar * (INR) Indian Rupee * (MXN) Mexican Peso * (UGX) Uganda Shillings * (PLN) Poland Zloti * (PHP) Philippine Peso * (CZK) Czech Koruna * (HUF) Hungarian Forint * (BGN) Bulgarian Lev * (RON) Romanian Leu * (ZAR) South African Rand * (LKR) Sri Lankan Rupee * (TRY) Turkish Lira * (THB) Thai Baht * (RUB) Russian Ruble * (IDR) Indonesian Rupiah * (MYR) Malaysian Ringgit * (SGD) Singapore Dollar * (TWD) New Taiwan Dollar * (AUD) Australian Dollar * (NGN) Nigerian Naira * (SEK) Swedish Krona * (NOK) Norwegian Krone * (UAH) Ukrainian Hryvnia * (VND) Vietnamese Dong If your Magento's currency is none of the above, the exchange rates will default to USD. If you're using Magento in a different currency not listed here and need support, [contact us](https://blockbee.io/contacts/) via our live chat. ### Why choose BlockBee? BlockBee has no setup fees, no monthly fees and no hidden costs! BlockBee has a low 1% fee on the transactions processed. > **INFO** >For more info on our fees [click here](https://blockbee.io/fees/). ## Installation 1. Upload code to the folder app/code/Blockbee/Blockbee 2. Enter following commands to install module: ```bash php bin/magento module:enable Blockbee_Blockbee php bin/magento setup:upgrade php bin/magento setup:di:compile ``` 4. Enable and configure BlockBee in Magento Admin under Stores -> Configuration-> Sales -> Payment Methods -> BlockBee ## Configuration 1. Access your Magento Admin Panel 2. Go to Stores -> Configuration -> Sales -> Payment Methods -> BlockBee 3. Activate the payment method (if inactive) 4. Set the name you wish to show your users on Checkout (for example: "Cryptocurrency") 5. Paste your API Key in the API Key field 6. Select which cryptocurrencies you wish to accept (control + click to select many) 7. Input your addresses to the cryptocurrencies you selected. This is where your funds will be sent to, so make sure the addresses are correct. 8. Click "Save Changes" 9. All done! ## Tutorial ### Installing BlockBee Extension in Magento Follow these step-by-step instructions to install and configure the BlockBee cryptocurrency payment extension in your Magento store. #### Step 1: Access Magento Administration After completing the installation, go to the Magento Administration area and click **Stores**. ![Magento Step 1](/assets/images/tutorials/magento/magento_screen_1.png) #### Step 2: Navigate to Configuration In the menu, click **Configuration**. ![Magento Step 2](/assets/images/tutorials/magento/magento_screen_2.png) #### Step 3: Access Sales Configuration Click **SALES** to show the dropdown menu. ![Magento Step 3](/assets/images/tutorials/magento/magento_screen_3.png) #### Step 4: Open Payment Methods Then, click **Payment Methods**. ![Magento Step 4](/assets/images/tutorials/magento/magento_screen_4.png) #### Step 5: Locate BlockBee Settings In the Payment Methods page, scroll to the **BlockBee** area, where you will set up our extension. #### Step 6: Enable the Extension It's important to enable the extension by setting the **Enable** option to **"Yes"**. Feel free to set up the remaining settings as you wish. ![Magento Step 6](/assets/images/tutorials/magento/magento_screen_5.png) #### Step 7: Configure API Key and Cryptocurrencies Paste your **API Key** that you got from BlockBee Dashboard and select the cryptocurrencies you want to accept (CTRL + click on Windows and CMD + Click on MacOS, to accept multiple currencies). Make sure you also did set the address in the Dashboard otherwise the extension will throw errors in the payment. ![Magento Step 6](/assets/images/tutorials/magento/magento_screen_6.png) #### Step 8: Save Configuration Finally, **Save** the settings and your Magento Store is now ready to accept cryptocurrencies. ## Frequently Asked Questions ### Do I need an API key? Yes. To use our service you will need to register at our [dashboard](https://dash.blockbee.io/) and create a new API Key. ### How long do payments take before they're confirmed? This depends on the cryptocurrency you're using. Bitcoin usually takes up to 11 minutes, Ethereum usually takes less than a minute. ### Is there a minimum for a payment? Yes, the minimums change according to the chosen cryptocurrency and can be checked [here](https://blockbee.io/cryptocurrencies). If the Magento order total is below the chosen cryptocurrency's minimum, an error is raised to the user. > **INFO** >**Where can I get support?** The easiest and fastest way is via our live chat on our [website](https://blockbee.io) or via our [contact form](https://blockbee.io/contacts/). ## Changelog ### 1.0.0 * Initial release. ### 1.0.1 * Minor bugfixes and improvements. ### 1.0.2 * Minor bugfixes and improvements. ### 1.0.3 * Add new choices for order cancellation. ### 1.1.0 * Add new choices for order cancellation. * The extension now uses BlockBee Checkout ### Upgrade Notice * No breaking changes. --- # Odoo Plugin > Source: https://docs.blockbee.io/get-started/odoo > Description: Integrate cryptocurrency payments into your Odoo system with our official plugin ![Odoo Logo](/assets/images/plugins/odoo.png) # BlockBee for Odoo Accept cryptocurrency payments in Odoo. ## Requirements ``` Odoo = 16 ``` ## Download {% button href="https://apps.odoo.com/apps/modules/19.0/payment_blockbee" variant="default" size="default" %} Download Plugin {% /button %} ## Description Accept payments in Bitcoin, Bitcoin Cash, Litecoin, Ethereum, Doge and Matic directly to your crypto wallet. ### Allow your customers to pay with cryptocurrency The BlockBee extension enables your Odoo system to receive payments in cryptocurrency, with a simple setup. ### Accepted cryptocurrencies & tokens include: BlockBee supports 100+ cryptocurrencies and tokens. > **INFO** >View the complete list [here](https://blockbee.io/cryptocurrencies). ### Supported currencies for automatic exchange rates are: * (USD) US Dollar * (EUR) Euro * (GBP) GB Pound * (CAD) Canadian Dollar * (CHF) Swiss Franc * (JPY) Japanese Yen * (AED) UAE Dollar * (DKK) Danish Krone * (BRL) Brazilian Real * (CNY) Chinese Yuan * (HKD) Hong Kong Dollar * (INR) Indian Rupee * (MXN) Mexican Peso * (UGX) Uganda Shillings * (PLN) Poland Zloti * (PHP) Philippine Peso * (CZK) Czech Koruna * (HUF) Hungarian Forint * (BGN) Bulgarian Lev * (RON) Romanian Leu * (ZAR) South African Rand * (LKR) Sri Lankan Rupee * (TRY) Turkish Lira * (THB) Thai Baht * (RUB) Russian Ruble * (IDR) Indonesian Rupiah * (MYR) Malaysian Ringgit * (SGD) Singapore Dollar * (TWD) New Taiwan Dollar * (AUD) Australian Dollar * (NGN) Nigerian Naira * (SEK) Swedish Krona * (NOK) Norwegian Krone * (UAH) Ukrainian Hryvnia * (VND) Vietnamese Dong If your Odoo's currency is none of the above, BlockBee's Module won't function properly. You may [contact us](https://blockbee.io/contacts/) to add the FIAT currency you want. ### Why choose BlockBee? BlockBee has no setup fees, no monthly fees and no hidden costs! BlockBee has a low 1% fee (plus blockchain fees) on the transactions processed. > **INFO** >For more info on our fees [click here](https://blockbee.io/fees/). ## Installation and Configuration 1. Upload our module code to your addons folder inside a folder named `payment_blockbee`. 2. Enable Odoo's debug mode. 3. Go to the **Apps** page and click **Install**. 4. Once installed click **Activate**. 5. Now, click the menu in the top left and go to **Website**. There click **Configuration** and then **Payment Providers** 6. Select **BlockBee**. You will need an API Key which you might get at [BlockBee Dashboard](https://dash.blockbee.io/). 7. Finally we advise you to make a test order to verify if you set up BlockBee's Module correctly. ## Frequently Asked Questions ### Do I need an API key? Yes. To use our service you will need to register at our [dashboard](https://dash.blockbee.io/) and create a new API Key. ### How long do payments take before they're confirmed? This depends on the cryptocurrency you're using. Bitcoin usually takes up to 11 minutes, Ethereum usually takes less than a minute. ### Is there a minimum for a payment? Yes, the minimums change according to the chosen cryptocurrency and can be checked [here](https://blockbee.io/cryptocurrencies). If the Odoo order total is below the chosen cryptocurrency's minimum, an error is raised to the user. > **INFO** >**Where can I get support?** The easiest and fastest way is via our live chat on our [website](https://blockbee.io) or via our [contact form](https://blockbee.io/contacts/). ## Changelog ### 1.0.0 * Initial release. ### 1.1.0 * Supports invoices. ### 1.1.1 * Minor bugfixes. ### Upgrade Notice * No breaking changes. --- # OpenCart Plugin > Source: https://docs.blockbee.io/get-started/opencart > Description: Integrate cryptocurrency payments into your OpenCart store with our official plugin ![OpenCart Logo](/assets/images/plugins/opencart.png) # BlockBee for OpenCart Accept cryptocurrency payments on your OpenCart store ## Requirements ``` OpenCart >= 4.0 OpenCart >= 3.0 ``` ## Download {% button href="https://github.com/blockbee-io/opencart-blockbee/releases" variant="default" size="default" %} Download Plugin {% /button %} ## Description Accept payments in Bitcoin, Bitcoin Cash, Litecoin, Ethereum, USDT and Matic directly to your crypto wallet. ### Allow users to pay with crypto directly on your store The BlockBee plugin extends OpenCart, allowing you to get paid in crypto directly on your store, with a simple setup. ### Accepted cryptocurrencies & tokens include: BlockBee supports 100+ cryptocurrencies and tokens. > **INFO** >View the complete list [here](https://blockbee.io/cryptocurrencies). ### Auto-value conversion BlockBee will attempt to automatically convert the value you set on your store to the cryptocurrency your customer chose. Exchange rates are fetched every 5 minutes from CoinGecko. ### Supported currencies for automatic exchange rates are: * (USD) US Dollar * (EUR) Euro * (GBP) GB Pound * (CAD) Canadian Dollar * (CHF) Swiss Franc * (JPY) Japanese Yen * (AED) UAE Dollar * (DKK) Danish Krone * (BRL) Brazilian Real * (CNY) Chinese Yuan * (HKD) Hong Kong Dollar * (INR) Indian Rupee * (MXN) Mexican Peso * (UGX) Uganda Shillings * (PLN) Poland Zloti * (PHP) Philippine Peso * (CZK) Czech Koruna * (HUF) Hungarian Forint * (BGN) Bulgarian Lev * (RON) Romanian Leu * (ZAR) South African Rand * (LKR) Sri Lankan Rupee * (TRY) Turkish Lira * (THB) Thai Baht * (RUB) Russian Ruble * (IDR) Indonesian Rupiah * (MYR) Malaysian Ringgit * (SGD) Singapore Dollar * (TWD) New Taiwan Dollar * (AUD) Australian Dollar * (NGN) Nigerian Naira * (SEK) Swedish Krona * (NOK) Norwegian Krone * (UAH) Ukrainian Hryvnia * (VND) Vietnamese Dong If your OpenCart's currency is none of the above, the exchange rates will default to USD. If you're using OpenCart in a different currency not listed here and need support, [contact us](https://blockbee.io) via our live chat. ### Why choose BlockBee? BlockBee has no setup fees, no monthly fees, no hidden costs, and you don't even need to sign-up! Simply set your crypto addresses and you're ready to go. As soon as your customers pay we forward your earnings directly to your own wallet. BlockBee has a low 1% fee on the transactions processed. No hidden costs. > **INFO** >For more info on our fees [click here](https://blockbee.io/fees/). ## Installation 1. Open your OpenCart admin 2. Go to Extensions 3. Upload the .zip file ## Configuration 1. Access your OpenCart Admin Panel 2. Go to Extensions -> Extensions 3. Select "Payments" 4. Scroll down to "BlockBee" 5. Activate the payment method (if inactive) 6. Select which cryptocurrencies you wish to accept 7. Input your addresses to the cryptocurrencies you selected. This is where your funds will be sent to, so make sure the addresses are correct. 8. Save Changes 9. All done! ## Tutorial ### Installing BlockBee Extension in OpenCart Follow these step-by-step instructions to install and configure the BlockBee cryptocurrency payment extension in your OpenCart store. #### Step 1: Prepare Your Account In this article we will explain how to set up BlockBee's OpenCart Extension in your OpenCart Store. First you will need to create and set up your account in our BlockBee Dashboard. After setting up your BlockBee account, you will need to install the extension in your OpenCart Store. Currently, our OpenCart Extension supports both OpenCart 3 and OpenCart 4. You will need to download the right file for your version from here. Make sure the name of your file looks like this: `blockbee.ocmod.zip` #### Step 2: Access Administration Area Having the right file for your OpenCart Store, you will need to log-in into your administration area to install the extension. While in the administration area, click Extensions to open a dropdown, and then click Installer. ![OpenCart Step 2](/assets/images/tutorials/opencart/opencart_screen_1.png) #### Step 3: Upload Extension After clicking Installer, click the upload button. In OpenCart 3 and OpenCart 4 the upload button is in different places, check the image below to see their location. ![OpenCart Step 3](/assets/images/tutorials/opencart/opencart_screen_2.png) #### Step 4: Complete Installation Clicking this button will open a pop-up. Upload the file to install the extension and wait for the process to complete. **Note:** In OpenCart 4 you will need to install the extension here by clicking in the green button in Action area. Finally, click Extensions. ![OpenCart Step 4](/assets/images/tutorials/opencart/opencart_screen_3.png) #### Step 5: Configure Extension Inside Extensions, select Payments in Extension Type and then in the list select the BlockBee Extension. Finally, click in the green button to finish the installation and, to change the extension settings, click the blue button with a pencil inside. ![OpenCart Step 5](/assets/images/tutorials/opencart/opencart_screen_4.png) #### Step 6: Enable Extension In the settings area, its very important to set the Status (highlighted in the image below) to Enabled, otherwise the extension won't work. The remaining settings you can customize to fit your needs. ![OpenCart Step 6](/assets/images/tutorials/opencart/opencart_screen_5.png) #### Step 7: Configure API Key and Cryptocurrencies If you scroll a bit, you will see more settings which are very crucial for the extension. First, you need to paste the API Key you got from our dashboard in the API Key field. You will also need to select the cryptocurrencies you want to accept (to select multiple cryptocurrencies CTRL + click on Windows / CMD + click on Mac). **Note:** Don't forget to set up the addresses for in the dashboard, otherwise the extension won't work. ![OpenCart Step 7](/assets/images/tutorials/opencart/opencart_screen_6.png) #### Step 8: Save Configuration After all done you can save the settings and your OpenCart Store is now ready to accept cryptocurrency payments. ## Frequently Asked Questions ### Do I need an API key? Yes. To use our service you will need to register at our [dashboard](https://dash.blockbee.io/) and create a new API Key. ### How long do payments take before they're confirmed? This depends on the cryptocurrency you're using. Bitcoin usually takes up to 11 minutes, Ethereum usually takes less than a minute. ### Is there a minimum for a payment? Yes, the minimums change according to the chosen cryptocurrency and can be checked [here](https://blockbee.io/cryptocurrencies). If the OpenCart order total is below the chosen cryptocurrency's minimum, an error is raised to the user. > **INFO** >**Where can I get support?** The easiest and fastest way is via our live chat on our [website](https://blockbee.io) or via our [contact form](https://blockbee.io/contacts/). ## Changelog ### 1.0.0 * Initial release. ### 1.0.1 * Minor fixes and improvements. ### 1.0.2 * Minor bugfixes. ### 1.0.3 * Minor bugfixes. ### 1.0.4 * Add new choices for order cancellation. * Minor bugfixes. ### Upgrade Notice * No breaking changes --- # Payment Links > Source: https://docs.blockbee.io/get-started/payment-links > Description: Create and share payment links directly from the BlockBee dashboard. Perfect for quick payments, invoicing, and simple integrations. ## Overview Payment Links allow you to create and share payment URLs directly from the BlockBee dashboard. This is the simplest way to accept cryptocurrency payments without any coding required. Perfect for: - **Quick payments** - Create payment links on the fly - **Invoicing** - Send payment links to customers - **Simple integrations** - No API development needed - **Testing** - Quick way to test cryptocurrency payments > **INFO** >**Estimated time:** 5 minutes for a basic implementation ## Setup Before you can create payment links, you need to configure your BlockBee account. The setup is similar to Checkout Payments, but you won't need an API key since you'll be creating payments through the dashboard. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Payment Settings 1. **Set Default Currency:** Go to [Payment Settings](https://dash.blockbee.io/profile/checkout) and configure your default FIAT currency (USD, EUR, GBP, etc.) 2. **Customize Payment Page:** Optionally customize the appearance and branding of your payment pages > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to setup the payment settings. ## Create Payment Link Navigate to the [Payment Links](https://dash.blockbee.io/link/create) page in your BlockBee dashboard to create a new payment link. ![BlockBee Payment Link Creation Form](/assets/images/payment_link_create.png) *Figure 1: Payment link creation form in the BlockBee dashboard* ### Payment Link Configuration The payment link form is organized in tabs with the following configuration options: #### Payment Settings Tab - **Amount** - Set the payment amount in your configured FIAT currency - **Description** - Add a description for the payment - **Expire** - Choose whether the payment link should expire - **When?** - If "Expire" is set to "Yes", you can set the expiration date #### After Payment Tab - **Show confirmation page** - User sees a completion message with no redirection - **Redirect to a specified page** - Redirect user to a custom URL after payment - **URL** - Set the URL where the user should be redirected to ### Email Notifications When a payment is completed through your payment link, BlockBee will automatically send an email notification to your registered email address with the payment details. ## Share Payment Link Once you've created a payment link, you can share it with your customers in several ways: ### Direct Sharing - **Copy the URL** - Copy the payment link URL and share it directly - **QR Code** - Generate a QR code for the payment link - **Email** - Send the payment link via email - **Social Media** - Share on social media platforms ### Embedding - **Website** - Add the payment link to your website - **Invoice** - Include the payment link in invoices - **Messages** - Send via messaging platforms > **TIP** >**Pre-select cryptocurrency:** You can append `?coin=btc` to the payment link URL to pre-select Bitcoin (or any other supported cryptocurrency) on the payment page. ## Track Payments You can track payments made through your payment links in several ways: ### Dashboard Tracking - View payment status in the [Payment Links](https://dash.blockbee.io/link/create) section - Check payment history and status updates - Monitor pending and confirmed payments ### Email Notifications You'll receive email notifications to your registered email address when payments are completed through your payment links. ### Manual Checking You can also check payment status by visiting the payment link URL and viewing the payment status page. > **INFO** >**Payment Status:** Payments go through pending and confirmed states. The payment is only considered complete when it reaches the confirmed state. ## Testing Your Payment Links Test your payment links using real cryptocurrency with minimal cost. ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Real blockchain testing without high costs ### 2. Test with a Small Amount - Create a payment link for a small value (e.g., $2.00) - Complete the payment using Litecoin - This covers all fees with minimal cost (typically under $0.10) - Test both pending and confirmed payment states ### 3. Testing Checklist - ✅ Payment link creation works as expected - ✅ Payment page displays correctly - ✅ Email notifications are received - ✅ Payment status updates correctly - ✅ Customer can complete payment successfully > **SUCCESS** >**Ready for production?** Once testing is complete, ensure your email address is correctly configured in your BlockBee account. --- # Self-Custodial Wallet Payouts > Source: https://docs.blockbee.io/get-started/payouts > Description: Learn how to use BlockBee's Self-Custodial Wallet for automated payouts with API Key V2. # Self-Custodial Wallet Payouts BlockBee's Self-Custodial Wallet system allows you to automate sending cryptocurrency payments to multiple addresses. This system requires **API Key V2** and uses TSS cryptography so BlockBee cannot access your funds without your API key. ## Overview ### Key Concepts - **Self-Custodial Wallet**: Your own cryptocurrency wallet managed by BlockBee with advanced security features - **Payout Request**: Individual payment instruction (address + amount) for a specific cryptocurrency - **Payout**: Collection of Payout Requests that are processed together - **API Key V2**: Required authentication for Self-Custodial Wallet operations > **WARNING** >**CRITICAL** If you lose both your API Key V2 and Recovery Key, you will permanently lose access to your Self-Custodial Wallet. BlockBee cannot access your wallet without these keys. ### How It Works 1. **Create Payout Requests**: Define the addresses and amounts you want to send 2. **Process Payouts**: Send the requests to be executed by your Self-Custodial Wallet 3. **Monitor Status**: Track the progress and completion of your payouts 4. **Manage Balance**: Check your wallet balance and address ## Prerequisites - **API Key V2**: You must upgrade from API Key V1 to V2 to use Self-Custodial Wallet - **Sufficient Balance**: Ensure your Self-Custodial Wallet has enough funds for payouts + fees - **Supported Cryptocurrencies**: Check our [cryptocurrencies page](https://blockbee.io/cryptocurrencies) for supported tickers ## Recommended Workflow ### 1. Create and Process Payouts You have two approaches for creating payouts: #### Option A: Bulk Process (Recommended) Use the bulk process endpoint to create and send multiple payouts efficiently in one request: ```javascript const payoutData = { outputs: { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2, '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 } }; const response = await fetch('https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' }, body: JSON.stringify(payoutData) }); const result = await response.json(); const payoutId = result.payout_info.id; console.log('Payout ID:', payoutId); ``` ```php <?php $payoutData = [ 'outputs' => [ '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.2, '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.1 ] ]; $url = 'https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2'; $options = [ 'http' => [ 'method' => 'POST', 'header' => 'Content-Type: application/json', 'content' => json_encode($payoutData) ] ]; $context = stream_context_create($options); $response = file_get_contents($url, false, $context); $result = json_decode($response, true); $payoutId = $result['payout_info']['id']; echo 'Payout ID: ' . $payoutId; ?> ``` ```python import requests import json payout_data = { 'outputs': { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2, '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 } } url = 'https://api.blockbee.io/btc/payout/request/bulk/process/' params = {'apikey': 'YOUR_API_KEY_V2'} headers = {'Content-Type': 'application/json'} response = requests.post(url, params=params, headers=headers, json=payout_data) result = response.json() payout_id = result['payout_info']['id'] print('Payout ID:', payout_id) ``` ```ruby require 'net/http' require 'json' payout_data = { outputs: { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.2, '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.1 } } uri = URI('https://api.blockbee.io/btc/payout/request/bulk/process/') params = { apikey: 'YOUR_API_KEY_V2' } uri.query = URI.encode_www_form(params) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['Content-Type'] = 'application/json' request.body = payout_data.to_json response = http.request(request) result = JSON.parse(response.body) payout_id = result['payout_info']['id'] puts "Payout ID: #{payout_id}" ``` ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; public async Task CreatePayout() { var payoutData = new { outputs = new Dictionary<string, decimal> { { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d", 0.2m }, { "0x18B211A1Ba5880C7d62C250B6441C2400d588589", 0.1m } } }; using (var client = new HttpClient()) { var url = "https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2"; var content = new StringContent(JsonConvert.SerializeObject(payoutData), System.Text.Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, content); var result = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync()); var payoutId = result.payout_info.id; Console.WriteLine($"Payout ID: {payoutId}"); } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import com.google.gson.JsonObject; import com.google.gson.JsonParser; public void createPayout() throws Exception { String payoutData = "{\"outputs\":{\"0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d\":0.2,\"0x18B211A1Ba5880C7d62C250B6441C2400d588589\":0.1}}"; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(payoutData)) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); JsonObject result = JsonParser.parseString(response.body()).getAsJsonObject(); String payoutId = result.getAsJsonObject("payout_info").get("id").getAsString(); System.out.println("Payout ID: " + payoutId); } ``` ```go package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) type PayoutData struct { Outputs map[string]float64 `json:"outputs"` } type PayoutResponse struct { PayoutInfo struct { ID string `json:"id"` } `json:"payout_info"` } func createPayout() { payoutData := PayoutData{ Outputs: map[string]float64{ "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": 0.2, "0x18B211A1Ba5880C7d62C250B6441C2400d588589": 0.1, }, } jsonData, _ := json.Marshal(payoutData) url := "https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2" resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) if err != nil { panic(err) } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) var result PayoutResponse json.Unmarshal(body, &result) fmt.Printf("Payout ID: %s\n", result.PayoutInfo.ID) } ``` ```bash curl -X POST "https://api.blockbee.io/btc/payout/request/bulk/process/?apikey=YOUR_API_KEY_V2" \ -H "Content-Type: application/json" \ -d '{ "outputs": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": 0.2, "0x18B211A1Ba5880C7d62C250B6441C2400d588589": 0.1 } }' ``` > **INFO: Using Our Official Libraries** >For a simpler integration, you can also use our official libraries. Here's how you would create a bulk payout: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const requests = { > '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2, > '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 > }; > > const payout = await BlockBee.createPayout('btc', requests, 'YOUR_API_KEY_V2', true); > // payout.payout_info.id > ``` > > ```php > // Using the official PHP library > require 'vendor/autoload.php'; > > $requests = [ > '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.2, > '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.1 > ]; > > $payout = BlockBee\BlockBee::create_payout('btc', $requests, 'YOUR_API_KEY_V2', true); > // $payout->payout_info->id > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeHelper > > requests = { > '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.2, > '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 > } > > payout = BlockBeeHelper.create_payout('btc', requests, 'YOUR_API_KEY_V2', True) > # payout['payout_info']['id'] > ``` > > You can find the full documentation for our libraries here: > - [Node.js Library](/libraries/nodejs) > - [PHP Library](/libraries/php) > - [Python Library](/libraries/python) {% section id="batch-processing" %} #### Option B: Individual Requests + Batch Processing (Exchange-style) Create individual payout requests and then combine them into a single payout for batch processing, similar to how exchanges handle withdrawals. This approach is ideal for platforms that need to: 1. **Create withdrawals** when users request them 2. **Create payout requests** for each withdrawal 3. **Batch process** when enough requests accumulate or after a time period 4. **Create and process payouts** to execute all pending withdrawals ```javascript // Step 1: Create individual payout requests (when users request withdrawals) const payoutRequests = [ { address: '0x1234567890123456789012345678901234567890', amount: 0.2 }, { address: '0x0987654321098765432109876543210987654321', amount: 0.1 } ]; // Create multiple payout requests at once const bulkRequests = { requests: payoutRequests }; const bulkResponse = await fetch('https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' }, body: JSON.stringify(bulkRequests) }); const bulkResult = await bulkResponse.json(); const requestIds = bulkResult.request_ids; // Array of request IDs // Step 2: Create payout from individual requests (batch processing) const payoutResponse = await fetch('https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' }, body: JSON.stringify({ payout_request_ids: requestIds.join(',') }) }); const payoutResult = await payoutResponse.json(); const payoutId = payoutResult.payout_info.id; console.log('Payout ID:', payoutId); // Step 3: Process the payout (execute all withdrawals) const processResponse = await fetch(`https://api.blockbee.io/payout/process/${payoutId}/?apikey=YOUR_API_KEY_V2`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' } }); const processResult = await processResponse.json(); console.log('Payout processed:', processResult.status); ``` ```php <?php // Step 1: Create individual payout requests $payoutRequests = [ ['address' => '0x1234567890123456789012345678901234567890', 'amount' => 0.2], ['address' => '0x0987654321098765432109876543210987654321', 'amount' => 0.1] ]; // Create multiple payout requests at once $bulkRequests = ['requests' => $payoutRequests]; $url = 'https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2'; $options = [ 'http' => [ 'method' => 'POST', 'header' => 'Content-Type: application/json', 'content' => json_encode($bulkRequests) ] ]; $context = stream_context_create($options); $response = file_get_contents($url, false, $context); $result = json_decode($response, true); $requestIds = $result['request_ids']; // Array of request IDs // Step 2: Create payout from individual requests $payoutData = ['payout_request_ids' => implode(',', $requestIds)]; $url = 'https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2'; $options = [ 'http' => [ 'method' => 'POST', 'header' => 'Content-Type: application/json', 'content' => json_encode($payoutData) ] ]; $context = stream_context_create($options); $response = file_get_contents($url, false, $context); $result = json_decode($response, true); $payoutId = $result['payout_info']['id']; echo 'Payout ID: ' . $payoutId; ?> ``` ```python import requests import json # Step 1: Create individual payout requests payout_requests = [ {'address': '0x1234567890123456789012345678901234567890', 'amount': 0.2}, {'address': '0x0987654321098765432109876543210987654321', 'amount': 0.1} ] # Create multiple payout requests at once bulk_requests = {'requests': payout_requests} url = 'https://api.blockbee.io/btc/payout/request/bulk/' params = {'apikey': 'YOUR_API_KEY_V2'} headers = {'Content-Type': 'application/json'} response = requests.post(url, params=params, headers=headers, json=bulk_requests) result = response.json() request_ids = result['request_ids'] # Array of request IDs # Step 2: Create payout from individual requests payout_data = {'payout_request_ids': ','.join(request_ids)} url = 'https://api.blockbee.io/payout/create/' response = requests.post(url, params=params, headers=headers, json=payout_data) result = response.json() payout_id = result['payout_info']['id'] print('Payout ID:', payout_id) ``` ```ruby require 'net/http' require 'json' # Step 1: Create individual payout requests payout_requests = [ { address: '0x1234567890123456789012345678901234567890', amount: 0.2 }, { address: '0x0987654321098765432109876543210987654321', amount: 0.1 } ] # Create multiple payout requests at once bulk_requests = { requests: payout_requests } uri = URI('https://api.blockbee.io/btc/payout/request/bulk/') params = { apikey: 'YOUR_API_KEY_V2' } uri.query = URI.encode_www_form(params) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request_obj = Net::HTTP::Post.new(uri) request_obj['Content-Type'] = 'application/json' request_obj.body = bulk_requests.to_json response = http.request(request_obj) result = JSON.parse(response.body) request_ids = result['request_ids'] # Array of request IDs # Step 2: Create payout from individual requests payout_data = { payout_request_ids: request_ids.join(',') } uri = URI('https://api.blockbee.io/payout/create/') uri.query = URI.encode_www_form(params) request_obj = Net::HTTP::Post.new(uri) request_obj['Content-Type'] = 'application/json' request_obj.body = payout_data.to_json response = http.request(request_obj) result = JSON.parse(response.body) payout_id = result['payout_info']['id'] puts "Payout ID: #{payout_id}" ``` ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; using System.Collections.Generic; public async Task CreatePayoutExchangeStyle() { // Step 1: Create individual payout requests var payoutRequests = new List<object> { new { address = "0x1234567890123456789012345678901234567890", amount = 0.2m }, new { address = "0x0987654321098765432109876543210987654321", amount = 0.1m } }; using (var client = new HttpClient()) { // Create multiple payout requests at once var bulkRequests = new { requests = payoutRequests }; var url = "https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2"; var content = new StringContent(JsonConvert.SerializeObject(bulkRequests), System.Text.Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, content); var result = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync()); var requestIds = ((Newtonsoft.Json.Linq.JArray)result.request_ids).Select(x => x.ToString()).ToList(); // Step 2: Create payout from individual requests var payoutData = new { payout_request_ids = string.Join(",", requestIds) }; var payoutUrl = "https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2"; var payoutContent = new StringContent(JsonConvert.SerializeObject(payoutData), System.Text.Encoding.UTF8, "application/json"); var payoutResponse = await client.PostAsync(payoutUrl, payoutContent); var payoutResult = JsonConvert.DeserializeObject<dynamic>(await payoutResponse.Content.ReadAsStringAsync()); var payoutId = payoutResult.payout_info.id; Console.WriteLine($"Payout ID: {payoutId}"); } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import com.google.gson.JsonObject; import com.google.gson.JsonParser; import java.util.List; import java.util.ArrayList; public void createPayoutExchangeStyle() throws Exception { // Step 1: Create individual payout requests List<Object> payoutRequests = List.of( Map.of("address", "0x1234567890123456789012345678901234567890", "amount", 0.2), Map.of("address", "0x0987654321098765432109876543210987654321", "amount", 0.1) ); HttpClient client = HttpClient.newHttpClient(); // Create multiple payout requests at once JsonObject bulkRequests = new JsonObject(); bulkRequests.add("requests", new Gson().toJsonTree(payoutRequests)); HttpRequest bulkRequest = HttpRequest.newBuilder() .uri(URI.create("https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(bulkRequests.toString())) .build(); HttpResponse<String> bulkResponse = client.send(bulkRequest, HttpResponse.BodyHandlers.ofString()); JsonObject bulkResult = JsonParser.parseString(bulkResponse.body()).getAsJsonObject(); JsonArray requestIdsArray = bulkResult.getAsJsonArray("request_ids"); List<String> requestIds = new ArrayList<>(); for (int i = 0; i < requestIdsArray.size(); i++) { requestIds.add(requestIdsArray.get(i).getAsString()); } // Step 2: Create payout from individual requests String payoutRequestIds = String.join(",", requestIds); JsonObject payoutData = new JsonObject(); payoutData.addProperty("payout_request_ids", payoutRequestIds); HttpRequest payoutRequest = HttpRequest.newBuilder() .uri(URI.create("https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(payoutData.toString())) .build(); HttpResponse<String> payoutResponse = client.send(payoutRequest, HttpResponse.BodyHandlers.ofString()); JsonObject payoutResult = JsonParser.parseString(payoutResponse.body()).getAsJsonObject(); String payoutId = payoutResult.getAsJsonObject("payout_info").get("id").getAsString(); System.out.println("Payout ID: " + payoutId); } ``` ```go package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) type PayoutRequest struct { Address string `json:"address"` Amount float64 `json:"amount"` } type RequestResponse struct { RequestID string `json:"request_id"` } type BulkData struct { Requests []string `json:"requests"` } type BulkResponse struct { PayoutInfo struct { ID string `json:"id"` } `json:"payout_info"` } func createPayoutExchangeStyle() { // Step 1: Create individual payout requests payoutRequests := []PayoutRequest{ {Address: "0x1234567890123456789012345678901234567890", Amount: 0.2}, {Address: "0x0987654321098765432109876543210987654321", Amount: 0.1}, } // Create multiple payout requests at once bulkRequests := map[string]interface{}{ "requests": payoutRequests, } jsonData, _ := json.Marshal(bulkRequests) url := "https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2" resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) if err != nil { panic(err) } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) var bulkResult map[string]interface{} json.Unmarshal(body, &bulkResult) requestIdsInterface := bulkResult["request_ids"].([]interface{}) var requestIds []string for _, id := range requestIdsInterface { requestIds = append(requestIds, id.(string)) } // Step 2: Create payout from individual requests payoutRequestIds := strings.Join(requestIds, ",") payoutData := map[string]string{"payout_request_ids": payoutRequestIds} jsonData, _ := json.Marshal(payoutData) url = "https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2" resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) if err != nil { panic(err) } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) var result BulkResponse json.Unmarshal(body, &result) fmt.Printf("Payout ID: %s\n", result.PayoutInfo.ID) } ``` ```bash # Step 1: Create individual payout requests curl -X POST "https://api.blockbee.io/btc/payout/request/create/?apikey=YOUR_API_KEY_V2" \ -H "Content-Type: application/json" \ -d '{ "address": "0x1234567890123456789012345678901234567890", "amount": 0.2 }' curl -X POST "https://api.blockbee.io/btc/payout/request/create/?apikey=YOUR_API_KEY_V2" \ -H "Content-Type: application/json" \ -d '{ "address": "0x0987654321098765432109876543210987654321", "amount": 0.1 }' # Step 2: Create payout from individual requests curl -X POST "https://api.blockbee.io/payout/create/?apikey=YOUR_API_KEY_V2" \ -H "Content-Type: application/json" \ -d '{ "payout_request_ids": "request-id-1,request-id-2" }' ``` > **INFO: Using Our Official Libraries** >You can also use our official libraries for the exchange-style workflow: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > // Step 1: Create individual payout requests > const requests = { > '0x1234567890123456789012345678901234567890': 0.2, > '0x0987654321098765432109876543210987654321': 0.1 > }; > > const payout = await BlockBee.createPayout('btc', requests, 'YOUR_API_KEY_V2', false); > const requestIds = payout.request_ids; // Array of request IDs > > // Step 2: Create payout from individual requests > const payoutResult = await BlockBee.createPayoutByIds('YOUR_API_KEY_V2', requestIds); > const payoutId = payoutResult.payout_info.id; > > // Step 3: Process the payout > const processResult = await BlockBee.processPayout('YOUR_API_KEY_V2', payoutId); > ``` > > ```php > // Using the official PHP library > require 'vendor/autoload.php'; > > // Step 1: Create individual payout requests > $requests = [ > '0x1234567890123456789012345678901234567890' => 0.2, > '0x0987654321098765432109876543210987654321' => 0.1 > ]; > > $payout = BlockBee\BlockBee::create_payout('btc', $requests, 'YOUR_API_KEY_V2', false); > $requestIds = $payout->request_ids; // Array of request IDs > > // Step 2: Create payout from individual requests > $payoutResult = BlockBee\BlockBee::create_payout_by_ids('YOUR_API_KEY_V2', $requestIds); > $payoutId = $payoutResult->payout_info->id; > > // Step 3: Process the payout > $processResult = BlockBee\BlockBee::process_payout('YOUR_API_KEY_V2', $payoutId); > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeHelper > > # Step 1: Create individual payout requests > requests = { > '0x1234567890123456789012345678901234567890': 0.2, > '0x0987654321098765432109876543210987654321': 0.1 > } > > payout = BlockBeeHelper.create_payout('btc', requests, 'YOUR_API_KEY_V2', False) > request_ids = payout['request_ids'] # Array of request IDs > > # Step 2: Create payout from individual requests > payout_result = BlockBeeHelper.create_payout_by_ids('YOUR_API_KEY_V2', request_ids) > payout_id = payout_result['payout_info']['id'] > > # Step 3: Process the payout > process_result = BlockBeeHelper.process_payout('YOUR_API_KEY_V2', payout_id) > ``` ### Exchange Workflow Example Here's how a typical exchange would implement this workflow: 1. **User requests withdrawal** → Create payout request immediately 2. **Accumulate requests** → Store payout request IDs 3. **Batch processing** → When threshold reached or time passed, create payout 4. **Execute withdrawals** → Process the payout to send all transactions **Alternative: Create Multiple Requests at Once** You can also create multiple payout requests in one call using the bulk endpoint: ```javascript // Create multiple payout requests at once const bulkRequests = { requests: [ { address: '0x1234567890123456789012345678901234567890', amount: 0.2 }, { address: '0x0987654321098765432109876543210987654321', amount: 0.1 } ] }; const bulkResponse = await fetch('https://api.blockbee.io/btc/payout/request/bulk/?apikey=YOUR_API_KEY_V2', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' }, body: JSON.stringify(bulkRequests) }); const bulkResult = await bulkResponse.json(); const requestIds = bulkResult.request_ids; // Array of request IDs ``` {% section id="monitor-payout-status" %} ### 2. Monitor Payout Status Track the progress of your payouts using the payout ID: ```javascript const statusData = { payout_id: payoutId }; const statusResponse = await fetch('https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'YOUR_API_KEY_V2' }, body: JSON.stringify(statusData) }); const status = await statusResponse.json(); console.log('Payout status:', status.payout_info.status); ``` ```php <?php $statusData = [ 'payout_id' => $payoutId ]; $url = 'https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2'; $options = [ 'http' => [ 'method' => 'POST', 'header' => 'Content-Type: application/json', 'content' => json_encode($statusData) ] ]; $context = stream_context_create($options); $response = file_get_contents($url, false, $context); $status = json_decode($response, true); echo 'Payout status: ' . $status['payout_info']['status']; ?> ``` ```python import requests import json status_data = { 'payout_id': payout_id } url = 'https://api.blockbee.io/payout/status/' params = {'apikey': 'YOUR_API_KEY_V2'} headers = {'Content-Type': 'application/json'} response = requests.post(url, params=params, headers=headers, json=status_data) status = response.json() print('Payout status:', status['payout_info']['status']) ``` ```ruby require 'net/http' require 'json' status_data = { payout_id: payout_id } uri = URI('https://api.blockbee.io/payout/status/') params = { apikey: 'YOUR_API_KEY_V2' } uri.query = URI.encode_www_form(params) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.new(uri) request['Content-Type'] = 'application/json' request.body = status_data.to_json response = http.request(request) status = JSON.parse(response.body) puts "Payout status: #{status['payout_info']['status']}" ``` ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; public async Task CheckPayoutStatus(string payoutId) { var statusData = new { payout_id = payoutId }; using (var client = new HttpClient()) { var url = "https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2"; var content = new StringContent(JsonConvert.SerializeObject(statusData), System.Text.Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, content); var status = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync()); var payoutStatus = status.payout_info.status; Console.WriteLine($"Payout status: {payoutStatus}"); } } ``` ```java import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.net.URI; import com.google.gson.JsonObject; import com.google.gson.JsonParser; public void checkPayoutStatus(String payoutId) throws Exception { String statusData = "{\"payout_id\":\"" + payoutId + "\"}"; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(statusData)) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); JsonObject status = JsonParser.parseString(response.body()).getAsJsonObject(); String payoutStatus = status.getAsJsonObject("payout_info").get("status").getAsString(); System.out.println("Payout status: " + payoutStatus); } ``` ```go package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) type StatusData struct { PayoutID string `json:"payout_id"` } type StatusResponse struct { PayoutInfo struct { Status string `json:"status"` } `json:"payout_info"` } func checkPayoutStatus(payoutId string) { statusData := StatusData{ PayoutID: payoutId, } jsonData, _ := json.Marshal(statusData) url := "https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2" resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) if err != nil { panic(err) } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) var status StatusResponse json.Unmarshal(body, &status) fmt.Printf("Payout status: %s\n", status.PayoutInfo.Status) } ``` ```bash curl -X POST "https://api.blockbee.io/payout/status/?apikey=YOUR_API_KEY_V2" \ -H "Content-Type: application/json" \ -d '{ "payout_id": "your-payout-id-here" }' ``` > **INFO: Using Our Official Libraries** >You can also check payout status using our official libraries: > > ```javascript > // Using the official Node.js library > const BlockBee = require('@blockbee/api'); > > const status = await BlockBee.checkPayoutStatus('YOUR_API_KEY_V2', payoutId); > // status.payout_info.status > ``` > > ```php > // Using the official PHP library > require 'vendor/autoload.php'; > > $status = BlockBee\BlockBee::check_payout_status('YOUR_API_KEY_V2', $payoutId); > // $status->payout_info->status > ``` > > ```python > # Using the official Python library > from BlockBee import BlockBeeHelper > > status = BlockBeeHelper.check_payout_status('YOUR_API_KEY_V2', payout_id) > # status['payout_info']['status'] > ``` ## Payout Statuses - **Created**: Payout has been created and is queued for processing - **Processing**: Payout is being processed by the blockchain - **Done**: Payout has been successfully completed - **Error**: Payout failed (check the error message for details) ## Error Handling For detailed information about common errors and their solutions, see our [Error Handling Guide](/get-started/error-handling). ## Security Considerations - **API Key V2 Security**: Use advanced security practices for API Key V2 - **Recovery Key**: Safely store your recovery key for emergency access - **Address Validation**: Always verify destination addresses before creating payouts - **HTTPS Only**: Always use HTTPS for API requests in production ## Relevant API Endpoints For detailed information about all payout-related endpoints, see our [API Reference](/api/list-payout-requests). Key endpoints include: - **Payout Management**: Create, process, and monitor payouts - **Wallet Operations**: Check balance, get addresses - **Request Management**: Create and manage payout requests - **Status Tracking**: Monitor payout and request status ## Testing > **WARNING** >**Test with Small Amounts:** Before using Self-Custodial Wallet in production, test with small amounts of Litecoin (LTC) to ensure everything works correctly. ### Testing Workflow 1. **Get Test LTC**: Add a small amount of Litecoin to your Self-Custodial Wallet 2. **Create Test Payouts**: Use the examples above with small amounts (0.001 LTC) 3. **Monitor Results**: Check payout status and verify transactions 4. **Scale Up**: Once testing is successful, increase amounts gradually ### Test with Litecoin Litecoin is ideal for testing because: - **Low fees**: Minimal transaction costs - **Fast confirmations**: Quick transaction processing - **Widely supported**: Available on most exchanges - **Stable network**: Reliable for testing purposes Use the ticker `ltc` in your API calls for Litecoin testing. > **INFO** >**Dashboard Management:** You can also manage your Self-Custodial Wallet through the [BlockBee Dashboard](https://dash.blockbee.io/wallet). --- # Point of Sale (PoS) > Source: https://docs.blockbee.io/get-started/pos > Description: Accept cryptocurrency payments in physical locations using BlockBee's Point of Sale app. Available for Android devices and web browsers. ## Overview ![BlockBee POS (Point-of-Sale)](/assets/images/blockbee_pos.png) *BlockBee POS (Point-of-Sale)* BlockBee's Point of Sale (PoS) app allows you to accept cryptocurrency payments in physical locations. Perfect for retail stores, restaurants, and any business that needs to process crypto payments in person. **Available on:** - **Android App** - Download directly from [BlockBee](https://web.blockbee.io/file/android-apk) - **Web App** - Access at [pos.blockbee.io](https://pos.blockbee.io) > **INFO** >**Estimated time:** 10-15 minutes for a basic setup ## Setup Before you can start using the PoS app, you need to configure your BlockBee account. The setup is similar to Checkout Payments, but you won't need an API key since you'll be using the PoS app interface. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Payment Settings 1. **Set Default Currency:** Go to [Payment Settings](https://dash.blockbee.io/profile/checkout) and configure your default FIAT currency (USD, EUR, GBP, etc.) 2. **Customize Payment Page:** Optionally customize the appearance and branding of your payment pages > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to setup the payment settings. ### 4. Configure PoS Usernames Set up PoS usernames for your employees at [PoS Settings](https://dash.blockbee.io/profile/pos). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-create-a-pos-user) on how to create a PoS user. > **INFO: How PoS Usernames Work** >PoS usernames are separate from your main BlockBee account credentials. This is a security feature that allows employees to use the PoS app without having access to your main BlockBee account. > > **Why separate usernames?** > - **Security** - Employees can't access your main BlockBee account > - **Access Control** - You can create and manage different PoS users > - **Audit Trail** - Track which employee processed each transaction > - **Safety** - If a device is compromised, only PoS access is affected > > Each PoS username you create can be used to log into the PoS app (Android or web) to process payments. ## Access PoS ### Android App 1. Download the BlockBee PoS app directly from [BlockBee](https://web.blockbee.io/file/android-apk) 2. Open the app and log in using your PoS username (not your main BlockBee account) 3. You're ready to start accepting payments ### Web App 1. Navigate to [pos.blockbee.io](https://pos.blockbee.io) 2. Log in using your PoS username (not your main BlockBee account) 3. You're ready to start accepting payments > **WARNING** >**Important:** Always use your PoS username to log into the PoS app, not your main BlockBee account credentials. This ensures security and proper access control. ## Create Transaction ### Step 1: Enter Amount 1. Open the PoS app (Android or web) 2. Enter the payment amount in your configured FIAT currency 3. Add an optional description for the transaction ### Step 2: Generate Payment 1. Tap "Create Payment" or "Generate QR Code" 2. The app will create a unique payment address and QR code 3. Display the QR code to your customer ### Step 3: Customer Payment 1. Customer scans the QR code with their cryptocurrency wallet 2. Customer sends the exact amount shown 3. Payment is processed automatically > **TIP** >**Multiple Cryptocurrencies:** The PoS app supports all cryptocurrencies configured in your BlockBee account. Customers can pay with Bitcoin, Ethereum, USDT, or any other supported cryptocurrency. ## Complete Payment ### Payment Confirmation - The PoS app will automatically detect when payment is received - You'll see a confirmation message on the screen - The transaction is marked as complete ### Receipt Options - **Digital Receipt** - Send via email or SMS - **Print Receipt** - If using a connected printer - **No Receipt** - Customer can decline ### Transaction History - All transactions are logged in the PoS app - You can view transaction history and status - Export transaction data if needed > **INFO** >**Payment Status:** Payments go through pending and confirmed states. The payment is only considered complete when it reaches the confirmed state. ## Testing Your PoS Setup Test your PoS app using real cryptocurrency with minimal cost. ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Real blockchain testing without high costs ### 2. Test with a Small Amount - Create a transaction for a small value (e.g., $2.00) - Complete the payment using Litecoin - This covers all fees with minimal cost (typically under $0.10) - Test both pending and confirmed payment states ### 3. Testing Checklist - ✅ PoS username creation works - ✅ App login with PoS username works - ✅ Transaction creation works as expected - ✅ QR code displays correctly - ✅ Payment detection works - ✅ Confirmation process completes - ✅ Transaction history updates ### 4. Test Both Platforms - Test on Android app - Test on web app at [pos.blockbee.io](https://pos.blockbee.io) - Ensure both platforms work consistently > **SUCCESS** >**Ready for production?** Once testing is complete, ensure all your PoS usernames are properly configured and your employees know how to use the app. --- # PrestaShop Plugin > Source: https://docs.blockbee.io/get-started/prestashop > Description: Integrate cryptocurrency payments into your PrestaShop store with our official plugin ![PrestaShop Logo](/assets/images/plugins/prestashop.png) # BlockBee for PrestaShop Accept cryptocurrency payments on your PrestaShop website ## Requirements ``` PHP >= 7.3 PrestaShop >= 1.7 ``` ## Download {% button href="https://github.com/blockbee-io/prestashop-blockbee/releases" variant="default" size="default" %} Download Plugin {% /button %} ## Description Accept payments in Bitcoin, Bitcoin Cash, Litecoin, Ethereum, USDT and Matic directly to your crypto wallet, without any sign-ups or lengthy processes. All you need is to provide your crypto address. ### Allow users to pay with crypto directly on your store The BlockBee module enables your PrestaShop store to get receive payments in cryptocurrency, with a simple setup and no sign-ups required. ### Accepted cryptocurrencies & tokens include: BlockBee supports 100+ cryptocurrencies and tokens. > **INFO** >View the complete list [here](https://blockbee.io/cryptocurrencies/). ### Auto-value conversion BlockBee module will attempt to automatically convert the value you set on your store to the cryptocurrency your customer chose. Exchange rates are fetched every 5 minutes. ### Supported currencies for automatic exchange rates are: * (USD) US Dollar * (EUR) Euro * (GBP) GB Pound * (CAD) Canadian Dollar * (CHF) Swiss Franc * (JPY) Japanese Yen * (AED) UAE Dollar * (DKK) Danish Krone * (BRL) Brazilian Real * (CNY) Chinese Yuan * (HKD) Hong Kong Dollar * (INR) Indian Rupee * (MXN) Mexican Peso * (UGX) Uganda Shillings * (PLN) Poland Zloti * (PHP) Philippine Peso * (CZK) Czech Koruna * (HUF) Hungarian Forint * (BGN) Bulgarian Lev * (RON) Romanian Leu * (ZAR) South African Rand * (LKR) Sri Lankan Rupee * (TRY) Turkish Lira * (THB) Thai Baht * (RUB) Russian Ruble * (IDR) Indonesian Rupiah * (MYR) Malaysian Ringgit * (SGD) Singapore Dollar * (TWD) New Taiwan Dollar * (AUD) Australian Dollar * (NGN) Nigerian Naira * (SEK) Swedish Krona * (NOK) Norwegian Krone * (UAH) Ukrainian Hryvnia * (VND) Vietnamese Dong If your PrestaShop's currency is none of the above, the exchange rates will default to USD. If you're using PrestaShop in a different currency not listed here and need support, [contact us](https://blockbee.io/contacts/) via our live chat. **Note:** BlockBee will not exchange your crypto for FIAT or other crypto, just convert the value ### Why choose BlockBee? BlockBee has no setup fees, no monthly fees, no hidden costs, and you don't even need to sign-up! Simply set your crypto addresses and you're ready to go. As soon as your customers pay we forward your earnings directly to your own wallet. BlockBee has a low 1% fee on the transactions processed. No hidden costs. > **INFO** >For more info on our fees [click here](https://blockbee.io/fees/). ## Installation ### Uploading in Prestashop Dashboard 1. Navigate to the 'Module Manager' in the PrestaShop dashboard 2. Click the 'Upload a Module' button 3. Select `prestashop-blockbee.zip` from your computer ### Using FTP 1. Download `prestashop-blockbee.zip` 2. Extract the `prestashop-blockbee` directory to your computer 3. Upload the `prestashop-blockbee` directory to the `/your-store/modules/` directory 4. Activate the module in the `Module Catalog` dashboard and then configure it. ## Configuration 1. Go to Prestashop dashboard 2. Select the "Modules" tab and click "Module Manager" 3. Search for "BlockBee" and click "configure" in our module 4. Set the name you wish to show your users on Checkout (for example: "Cryptocurrency") 5. Select which cryptocurrencies you wish to accept (control + click to select many) 6. Input your addresses to the cryptocurrencies you selected. This is where your funds will be sent to, so make sure the addresses are correct. 7. Click "Save" 8. All done! ### Enabling the Cronjob Some features require a cronjob to work. You need to create one in your hosting that runs every 1 minute. It should call this URL `YOUR-DOMAIN/module/blockbee/cronjob?nonce=your_nonce_here`, using `CURL`. The required `nonce` its generated in the Module Manager configuration. ## Tutorial ### Installing BlockBee Module in PrestaShop Our PrestaShop Module allows you to get paid in all our supported cryptocurrencies in your PrestaShop Store, with a simple set-up. First you need to create an account. In this page we will guide you throughout the configuration and installation of our official PrestaShop Module. #### Step 1: Download and Access Admin Area 1. Download our PrestaShop Module and access your PrestaShop store's admin area. Click in Modules to open a dropdown menu. ![PrestaShop Step 1](/assets/images/tutorials/prestashop/prestashop_screen_1.png) #### Step 2: Access Module Manager 2. In the dropdown menu click Module Manager. ![PrestaShop Step 2](/assets/images/tutorials/prestashop/prestashop_screen_2.png) #### Step 3: Upload Module 3. After clicking Module Manager you will enter a new screen where you must click Upload a module. ![PrestaShop Step 3](/assets/images/tutorials/prestashop/prestashop_screen_3.png) #### Step 4: Select File 4. You can either drop the zip file in the modal's red area or click "select file" to pick from your file system. ![PrestaShop Step 4](/assets/images/tutorials/prestashop/prestashop_screen_4.png) #### Step 5: Complete Installation 5. Once the installation is completed, click Configure. ![PrestaShop Step 5](/assets/images/tutorials/prestashop/prestashop_screen_5.png) #### Step 6: Activate Module 6. First, you need to activate the Module. You can configure the rest of the settings to fit your needs. ![PrestaShop Step 6](/assets/images/tutorials/prestashop/prestashop_screen_6.png) #### Step 7: Configure API Key and Cryptocurrencies 7. Scroll down the settings page so you can see the remaining fields that are mandatory to set up. **API Keys:** Paste the API Key you obtained from your BlockBee Dashboard. **Select cryptocurrencies:** Select the cryptocurrencies you want to accept in your PrestaShop Store. (You may use CTRL + Mouse click on Windows or Command + Mouse click on Mac to select multiple cryptocurrencies). ![PrestaShop Step 7](/assets/images/tutorials/prestashop/prestashop_screen_7.png) #### Step 8: Configure Cronjob 8. Here you can define your Cronjob Nonce, though one is already defined by default for you. The automatic conversion and automatic order cancelation need a defined Cronjob to function. For that you must set-up a Cronjob that calls the provided link every 5 minutes. If you aren't sure how this works, contact your hosting provider. ![PrestaShop Step 8](/assets/images/tutorials/prestashop/prestashop_screen_8.png) #### Step 9: Save Configuration 9. Finally check again your settings and make sure you hit Save before closing the page. ## Frequently Asked Questions ### Do I need an API key? No. You just need to insert your crypto address of the cryptocurrencies you wish to accept. Whenever a customer pays, the money will be automatically and instantly forwarded to your address. ### How long do payments take before they're confirmed? This depends on the cryptocurrency you're using. Bitcoin usually takes up to 11 minutes, Ethereum usually takes less than a minute. ### Is there a minimum for a payment? Yes, the minimums change according to the chosen cryptocurrency and can be checked [here](https://blockbee.io/cryptocurrencies). If the PrestaShop order total is below the chosen cryptocurrency's minimum, an error is raised to the user. > **INFO** >**Where can I get support?** The easiest and fastest way is via our live chat on our [website](https://blockbee.io) or via our [contact form](https://blockbee.io/contacts/). ## Changelog ### 1.0.0 * Initial release. ### 1.1.0 * Support for Prestashop 8 * Minor bugfixes ### 1.1.1 * Minor bugfixes ### 1.1.2 * Minor bugfixes ### 1.1.3 * Add new choices for order cancellation. ### Upgrade Notice * No breaking changes --- # Self-Custodial Wallet > Source: https://docs.blockbee.io/get-started/self-custodial-wallet > Description: Learn about BlockBee's Self-Custodial Wallet system for automated payouts and advanced fund management. # Self-Custodial Wallet The Self-Custodial Wallet lets you hold your own private keys while BlockBee handles payment routing and automated payouts. BlockBee never has access to your funds. ## What is Self-Custodial Wallet? The Self-Custodial Wallet is a cryptocurrency wallet where you control the private keys. BlockBee provides the infrastructure for receiving payments and sending payouts, but cannot move your funds without your API key. ### Key Features - **Full Fund Control**: You own and control your private keys - **Automated Payouts**: Send payments to multiple addresses automatically - **Advanced Security**: Multi-layer cryptography and recovery mechanisms - **Real-time Monitoring**: Track all transactions and balances - **Multi-Cryptocurrency Support**: Manage multiple cryptocurrencies in one wallet ## How Self-Custodial Wallet Works BlockBee uses **Threshold Signature Scheme (TSS) cryptography** so that no single party — including BlockBee — can move funds unilaterally. ### The Three-Share System When you upgrade to API Key V2, our system generates **three shares**, with at least **two required for transaction signatures**: 1. **BlockBee's Encrypted Share**: We securely store one encrypted share 2. **Your API Key**: One of your two shares 3. **Your Recovery Key**: Your second share for emergency access This covers all addresses across supported chains for your payout wallet, and achieves three goals: - **BlockBee cannot access funds unilaterally** — your API key is required for every transaction - **Automated payouts** — send a payout with a single API call using your API key - **Recovery** — if you lose your API key, use your Recovery Key to regenerate it > **WARNING** >If you lose both your API Key V2 and Recovery Key, your Self-Custodial Wallet funds are permanently inaccessible. BlockBee cannot recover them. Store both keys securely before using this feature. ## Getting Started ### 1. Upgrade to API Key V2 To begin using Self-Custodial Wallet, upgrade to API Key V2 via your API key settings: 1. Log into your [BlockBee Dashboard](https://dash.blockbee.io/) 2. Navigate to API Keys section 3. Generate a new API Key V2 4. **Securely store both your new API key and recovery key** - especially the recovery key, which is crucial for API key resetting if needed ### 2. Access Your Self-Custodial Wallet Once you have API Key V2, navigate to [Wallet](https://dash.blockbee.io/wallet) to view and fund your blockchain-specific addresses for payouts, or opt to directly receive your BlockBee payments. To route incoming BlockBee payments directly to your Payouts wallet, use the "Set Self-Custodial Wallet" option on that page. ### 3. Fund Your Wallet Send cryptocurrency to your Self-Custodial Wallet address: ```javascript // Get your wallet address const response = await fetch('https://api.blockbee.io/btc/payout/address/?apikey=YOUR_API_KEY_V2'); const walletInfo = await response.json(); console.log('Your wallet address:', walletInfo.address); ``` ### 4. Check Your Balance Check available balances and estimated blockchain fees before sending a payout: ```javascript // Check balance const balanceResponse = await fetch('https://api.blockbee.io/btc/payout/balance/?apikey=YOUR_API_KEY_V2'); const balance = await balanceResponse.json(); console.log('Available balance:', balance.balance); ``` > **WARNING** >Your balance must cover both the payout amount and the blockchain fee. For token transfers on Ethereum and similar networks, you also need the native coin (ETH, BNB, etc.) in your wallet to pay gas. Payouts fail if either balance is insufficient. ## Use Cases ### Automated Payouts Send payments to multiple addresses automatically. Run payouts from the dashboard or via the API — up to **100 addresses in a single request**. > **INFO** >For detailed information about payout workflows, API endpoints, and code examples, see our [Payouts Guide](/get-started/payouts). ### Platform Fund Distribution Perfect for platforms that need to distribute funds to users: - **Gaming Platforms**: Reward distribution to players - **Freelance Platforms**: Payment to contractors - **Investment Platforms**: Dividend distributions - **Content Platforms**: Creator payments ### Business Operations Streamline business cryptocurrency operations: - **Payroll**: Automated salary payments in cryptocurrency - **Vendor Payments**: Regular payments to suppliers - **Refunds**: Automated refund processing - **Rewards**: Customer loyalty and referral programs ## Security Features ### Threshold Signature Scheme (TSS) Cryptography Transactions require at least two of the three key shares. BlockBee holds one share; you hold two. No single party can move funds alone. ### Three-Share Recovery System The system generates three shares with at least two required for transaction signatures: - BlockBee's encrypted share (securely stored) - Your API key (one of your shares) - Your recovery key (your second share for emergency access) > **WARNING** >If you lose both your API Key V2 and Recovery Key, access to your Self-Custodial Wallet is permanently lost. BlockBee cannot recover it. ### Secure Infrastructure BlockBee stores its key share encrypted and runs regular security audits across all infrastructure. ## Best Practices ### 1. Secure API Key Management - Store API Key V2 securely - Never expose it in client-side code - Use environment variables in production ### 2. Recovery Key Safety - **Store both API Key V2 and Recovery Key securely** - You need both to maintain access - Consider using a hardware security module (HSM) for maximum security - Test recovery procedures periodically > **WARNING** >If you lose both keys, access to your Self-Custodial Wallet is permanently lost. ### 3. Balance Management - Always maintain sufficient balance for operations - Monitor fees and transaction costs - Set up alerts for low balance ### 4. Transaction Monitoring - Regularly check payout status - Monitor for failed transactions - Set up webhooks for real-time updates ## Supported Cryptocurrencies This feature is available on all **Ethereum Virtual Machine (EVM) compatible chains**, **Tron**, as well as on the **Bitcoin (BTC)**, **Litecoin (LTC)**, and **Bitcoin Cash (BCH)** networks. > **WARNING** >**Note**: This feature is not available on Doge network due to technical limitations of the Doge node. ## Migration from API Key V1 If you're currently using API Key V1, here's how to migrate: 1. **Generate API Key V2** in your dashboard 2. **Update your code** to use the new API key 3. **Test with small amounts** to ensure everything works 4. **Gradually migrate** your operations to V2 5. **Keep V1 active** during transition period 6. **Deactivate V1** once migration is complete ## Troubleshooting For detailed information about common errors and their solutions, see our [Error Handling Guide](/get-started/error-handling). ### Recovery Key Issues > **WARNING** >**CRITICAL** If you lose your Recovery Key, you will not be able to regenerate your API Key V2. If you lose both your API Key V2 and Recovery Key, you will permanently lose access to your Self-Custodial Wallet as BlockBee cannot access it without these keys. If you've lost your Recovery Key but still have your API Key V2, contact BlockBee support immediately for assistance. ### Getting Help - **Documentation**: Check our [API Reference](/api/create-payment-address) for detailed endpoint information - **Support**: Contact our support team for assistance - **Community:** Join our [Discord server](https://discord.gg/pQaJ32SGrR) for tips and discussions ## Next Steps Ready to get started with Self-Custodial Wallet? 1. [Upgrade to API Key V2](/get-started/authentication) 2. [Learn about Payouts](/get-started/payouts) 3. [Explore API Endpoints](/api/get-wallet-address) 4. [Check Supported Cryptocurrencies](https://blockbee.io/cryptocurrencies) --- # Storefront > Source: https://docs.blockbee.io/get-started/storefront > Description: Launch a complete online store that accepts cryptocurrency payments. No coding required - just configure and go live. # Storefront ![Storefront](/assets/images/storefront.jpg) *Storefront Page* Launch a complete online store that accepts cryptocurrency payments. No coding required - just configure and go live. ## Overview BlockBee Storefront is a hosted solution that allows you to create a complete online store without any coding knowledge. When customers make purchases and complete payments, you'll receive email confirmations with all the details. ### Key Features - **No Coding Required**: Set up your store entirely through the BlockBee dashboard - **Hosted Solution**: Your store is hosted on BlockBee's secure infrastructure - **Cryptocurrency Payments**: Accept Bitcoin, Ethereum, and 100+ other cryptocurrencies - **Email Notifications**: Receive instant email confirmations for all sales - **Customizable**: Add your business logo, customize payment options, and configure products - **Mobile Responsive**: Your store works perfectly on all devices ### How It Works 1. **Setup**: Configure your addresses, payment settings, and products in the BlockBee dashboard 2. **Launch**: Your store goes live at a custom URL (e.g., `pay.blockbee.io/s/your-store/`) 3. **Sell**: Customers browse your products and pay with cryptocurrency 4. **Receive**: Get email notifications for all successful sales ## Setup Process To get your Storefront up and running, you need to complete three main configuration steps: ### Step 1: Configure Addresses First, set up the cryptocurrency addresses where you want to receive payments. 1. Go to [BlockBee Dashboard - Addresses](https://dash.blockbee.io/profile/addresses) 2. Add the cryptocurrency addresses for the coins you want to accept 3. Ensure all addresses are valid and active > **WARNING** >**Important**: You must configure addresses before setting up payments. Without valid addresses, your storefront won't function properly. ### Step 2: Configure Payment Settings Set up your business branding and payment preferences. 1. Go to [BlockBee Dashboard - Checkout](https://dash.blockbee.io/profile/checkout) 2. Upload your business logo 3. Select which cryptocurrencies to accept 4. Configure payment display options 5. Set up any additional payment preferences > **INFO** >Learn how to setup the Payment Settings [here](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) page. ### Step 3: Configure Storefront Settings Set up your products and store configuration. 1. Go to [BlockBee Dashboard - Storefront](https://dash.blockbee.io/profile/storefront) 2. Add the products you want to sell 3. Configure your store slug (this will be part of your URL) 4. Set up redirect URLs for after payment completion 5. Configure any additional store settings ## Usage ### Store URL Format Your storefront will be available at: ``` pay.blockbee.io/s/{your-store-slug}/ ``` For example, if your store slug is "test", your store URL would be: ``` pay.blockbee.io/s/test/ ``` ### Customer Experience 1. **Browse**: Customers visit your store URL 2. **Select**: They choose products and add them to cart 3. **Pay**: They select their preferred cryptocurrency 4. **Complete**: Payment is processed automatically 5. **Redirect**: Customer is redirected to your specified URL ### Email Notifications You'll receive email confirmations for every successful sale containing: - Customer information - Product details - Payment amount and cryptocurrency used - Transaction details - Timestamp ## Examples ### Example Store Setup **Store Slug**: `my-electronics-store` **URL**: `pay.blockbee.io/s/my-electronics-store/` **Products**: - iPhone 15 Pro - $999 - MacBook Air - $1,199 - AirPods Pro - $249 **Accepted Cryptocurrencies**: Bitcoin, Ethereum, USDT, Litecoin **Redirect URL**: `https://mywebsite.com/thank-you` ### Example Email Notification ![Example Storefront Email](/assets/images/example_storefront_email.jpg) *Example Storefront Email* ## Frequently Asked Questions ### Do I need technical knowledge to use Storefront? No! Storefront is designed to be completely no-code. You can set up your entire store through the BlockBee dashboard interface. ### What cryptocurrencies can I accept? You can accept any cryptocurrency that you have configured addresses for. BlockBee supports 100+ cryptocurrencies including Bitcoin, Ethereum, USDT, and many others. ### How do I get paid? When customers complete payments, the cryptocurrency is automatically forwarded to the addresses you configured in your dashboard. You'll also receive email notifications for all sales. ### Can I customize the appearance of my store? Yes! You can upload your business logo and configure various display options through the checkout settings in your dashboard. ### What happens if a customer doesn't complete payment? If a customer doesn't complete their payment, no funds are transferred and no email notification is sent. You can track incomplete orders through your dashboard. > **INFO** >You can check all the payments and orders at [Checkout Payments](https://dash.blockbee.io/payments/checkout) page. ### Can I change my store URL? Yes, you can update your store slug in the storefront settings, which will change your store URL. However, the old URL will no longer work. ### Is there a limit on the number of products I can sell? There are reasonable limits on the number of products you can add to your store. Contact support if you need to sell a large number of items. > **INFO** >**Need Help?** If you have questions about setting up your Storefront, contact our support team via live chat on our [website](https://blockbee.io) or through our [contact form](https://blockbee.io/contacts/). --- # Subscriptions > Source: https://docs.blockbee.io/get-started/subscriptions > Description: Implement recurring payments with BlockBee's subscription system. Learn how to create, manage, and handle webhooks for subscriptions. ## Overview BlockBee Subscriptions allow you to offer recurring crypto payments for your services. You can create subscriptions for users, fetch their status, and handle renewal/expiration notifications via webhooks. BlockBee manages the payment interface and reminders, while you handle business logic on your end. > **INFO** >**Estimated time:** 10-15 minutes for a basic implementation ## Setup Before you can start implementing subscriptions, you need to configure your BlockBee account and get your API credentials. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive subscription payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Subscription Settings Configure your subscription plans and settings at [Subscription Settings](https://dash.blockbee.io/profile/subscriptions). ### 4. Generate API Key 1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard 2. Click "Generate New API Key" 3. Copy the generated API key - you'll need this for all API requests > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to generate an API Key. > **WARNING** >**Keep your API key secure:** Never expose your API key in client-side code or public repositories. Store it securely in environment variables or server-side configuration. ## Step 1: Create Subscription To start, create a subscription for your user using the API. ### API Endpoint **Method:** `GET` **URL:** `https://api.blockbee.io/subscription/create/` > **TIP** >**API Reference:** See [Create a Subscription](/api/create-subscription) for full parameter details. ### Code Examples ```javascript // Create a subscription const createSubscription = async (userId, userEmail, option) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', user_id: userId, user_email: userEmail, option: option, // e.g., 'pro-plan' post: '1' }); const response = await fetch(`https://api.blockbee.io/subscription/create/?${params}`); const result = await response.json(); if (result.status === 'success') { return { token: result.token, subscriptionUrl: result.subscription_url }; } else { throw new Error('Failed to create subscription: ' + result.message); } }; ``` ```php // ... existing code ... ``` ```python # ... existing code ... ``` ```ruby # ... existing code ... ``` ```csharp // ... existing code ... ``` ```java // ... existing code ... ``` ```go // ... existing code ... ``` ```bash # ... existing code ... ``` ### Required Parameters - **`apikey`** – Your BlockBee API key - **`user_id`** – User identifier in your system - **`user_email`** – Customer email ### Optional Parameters - **`option`** – Subscription plan slug - **`post`** – Set to `1` for POST webhooks ### Response Returns a subscription token and URL. ```json { "status": "success", "token": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o" } ``` ## Step 2: Fetch & List Subscriptions You can fetch a single subscription or list all subscriptions for your profile. ### Fetch Subscription **Method:** `GET` **URL:** `https://api.blockbee.io/subscription/fetch/` **Parameters:** - `apikey` (required) - `token` (required) ### List Subscriptions **Method:** `GET` **URL:** `https://api.blockbee.io/subscription/list/` **Parameters:** - `apikey` (required) - `p` (page, optional) > **TIP** >**API Reference:** See [Fetch Subscription](/api/get-subscription) and [List Subscriptions](/api/list-subscriptions) for full details. ### Code Examples ```javascript // Fetch a subscription const fetchSubscription = async (token) => { const params = new URLSearchParams({ apikey: 'YOUR_API_KEY', token }); const response = await fetch(`https://api.blockbee.io/subscription/fetch/?${params}`); return await response.json(); }; ``` ## Step 3: Handle Webhooks BlockBee sends webhooks for subscription payments (renewals) and expiration. Your application must handle these to update user access and status. ### 1. Payment Notification Webhook Sent when a user makes a payment (initial or renewal). > **TIP** >**Webhook Reference:** For complete webhook field documentation, see our [Subscriptions Webhook reference](/webhooks/subscriptions-webhook). ### 2. Expiration Notification Webhook Sent when a subscription expires. > **TIP** >**Webhook Reference:** For complete webhook field documentation, see our [Subscriptions Webhook reference](/webhooks/subscriptions-webhook). ### Webhook Handling Example ```javascript // Express.js webhook handler app.post('/subscription-webhook', express.json(), (req, res) => { const { action, subscription_id, subscription_end_date_ts, payment_status } = req.body; if (action === 'renew' && payment_status === 'done') { // Grant/extend access for user } else if (action === 'expired') { // Revoke access for user } res.status(200).send('*ok*'); }); ``` > **TIP** >**Signature Verification:** Always verify webhook signatures. See [Verify Webhook Signature](/webhooks/verify-webhook-signature). ### Best Practices - **Idempotency:** Use `subscription_id` to avoid duplicate processing. - **Respond Quickly:** Always respond with `*ok*` and status 200. - **Asynchronous Processing:** Handle long tasks after responding. ## Testing Your Integration - Use a test user and plan for end-to-end flow. - Test both payment and expiration webhooks. - Use [ngrok](https://ngrok.com/) to expose your local server for webhook testing. ```bash ngrok http 3000 # Use the public URL as your webhook endpoint ``` > **SUCCESS** >**Ready for production?** Switch to your production API Key and endpoints when going live. --- # Telegram Bot > Source: https://docs.blockbee.io/get-started/telegram-bot > Description: Monetize your Telegram channels and groups with automated subscription management using BlockBee Bot. Handle payments, user access, and subscription renewals automatically. ## Overview BlockBee Bot adds crypto subscription payments to your Telegram channels and groups. Set pricing for different time periods; the bot handles everything else. When a user subscribes, the bot generates a single-use invite link and adds them to your channel. When the subscription expires, the bot removes them automatically. No manual management required. > **INFO** >**Estimated time:** 15-20 minutes for a basic setup ## Setup Before you can start using the BlockBee Telegram Bot, you need to configure your BlockBee account and create a Telegram bot. ### 1. Create a BlockBee Account If you haven't already, [sign up for a BlockBee account](https://dash.blockbee.io/register) to get access to the dashboard. ### 2. Configure Addresses Set up the cryptocurrency addresses where you want to receive payments at [Addresses](https://dash.blockbee.io/profile/addresses). > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-set-up-the-addresses) on how to setup your addresses. ### 3. Configure Payment Settings 1. **Set Default Currency:** Go to [Payment Settings](https://dash.blockbee.io/profile/checkout) and configure your default FIAT currency (USD, EUR, GBP, etc.) 2. **Customize Payment Page:** Optionally customize the appearance and branding of your payment pages > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to setup the payment settings. ### 4. Generate API Key 1. Navigate to the [API Keys section](https://dash.blockbee.io/profile/api-keys) in your dashboard 2. Click "Generate New API Key" 3. Copy the generated API key - you'll need this for the BlockBee Bot > **INFO** >Check this handy [tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) on how to generate an API Key. > **WARNING** >**Keep your API key secure:** Never expose your API key in public channels or share it with unauthorized users. Store it securely and only use it for the BlockBee Bot configuration. ## How It Works The BlockBee Telegram Bot integrates with your Telegram channels and groups to provide automated subscription management: ### Payment Processing - **In-Telegram Payments** - Users can pay directly within Telegram using the bot interface - **Payment Links** - Users can also click payment links to complete payments on the BlockBee hosted checkout page - **Multiple Cryptocurrencies** - Supports all cryptocurrencies configured in your BlockBee account ### User Management - **Exclusive Invitation Links** - Each subscriber gets a unique, one-time-use invitation link - **Automatic Access Control** - Only subscribed users can join your channel/group - **Subscription Expiration** - Users are automatically removed when their subscription expires - **Renewal Notifications** - The bot sends notifications when subscriptions are nearing expiration, allowing users to renew - **Renewal Handling** - Seamless renewal process for existing subscribers ### Subscription Options - **Flexible Pricing** - Set different prices for various time periods (daily, weekly, monthly, etc.) - **Multiple Tiers** - Create different subscription levels with different access rights - **Automatic Billing** - Handle recurring payments and subscription renewals - **Coupon System** - Offer free subscriptions or discounts using coupon codes for promotional campaigns > **TIP** >**Technical Integration:** The bot uses BlockBee's checkout payments API to process payments, ensuring secure and reliable payment processing for your subscribers. ## Create Your Telegram Bot To create your own bot, you will need to use the BotFather. ### Step-by-Step Instructions 1. **Access BotFather** - Click [here](https://t.me/botfather) to access the BotFather 2. **Start Conversation** - Type `/start` to initiate the conversation 3. **Create New Bot** - Type `/newbot` to start the process of creating a new bot 4. **Choose Bot Name** - The BotFather will prompt you to choose a name for your bot. Remember that the bot's name must end with the word "bot" (e.g., TestBot or MyAwesomeBot) 5. **Get Bot Token** - After providing a suitable name, the BotFather will generate a bot token for you. This token is essential for accessing and controlling your bot's functionalities > **WARNING** >**Important:** Do not share the bot token with anyone. This token will be inserted into BlockBee Bot and should be kept secure. ![Telegram Bot Creation Process](/assets/images/tutorials/telegram/telegram_screen_1.png) *Figure 1: Creating a new bot with BotFather* ## Create Project in BlockBee Bot ### Step 1: Access BlockBee Bot To start using BlockBee Bot you must access it and then use the `/start` command (in some platforms, Telegram makes the Start as a button on the bottom). ### Step 2: Create New Project Then you must click the button "Create new project". ![Telegram Bot Creation Process](/assets/images/tutorials/telegram/telegram_screen_2.png) *Figure 2: Starting BlockBee Bot with /start command* ### Step 3: Insert Bot Token BlockBee Bot will then prompt you to insert your Telegram Bot token and then hit "send". ![Create New Project Button](/assets/images/tutorials/telegram/telegram_screen_3.png) *Figure 3: Creating a new project in BlockBee Bot* > **INFO** >**Required setup:** After the token is accepted, run `/start` again and click **Update API Key** to add your BlockBee API key. The flow is the same as inserting the bot token. Your API key must be valid — an invalid key causes errors when generating payments. If the token inserted is valid, the bot will reply with a success message. ![Insert Bot Token](/assets/images/tutorials/telegram/telegram_screen_4.png) *Figure 4: Inserting your Telegram bot token* ## Configure Your Project ### Step 1: Add Bot as Administrator Add your bot as an administrator to your Telegram Channel before continuing. The steps below will not work until the bot has admin permissions. ### Step 2: Manage Projects Send the `/start` command again and click **Manage projects**. Select your bot's name from the list. If it doesn't appear, reconfigure your Telegram Bot from step 1. ![Add Bot as Administrator](/assets/images/tutorials/telegram/telegram_screen_6.png) *Figure 6: Adding your bot as an administrator to your channel* ### Step 3: Select Channel Select the Telegram Channel you want to manage. The bot must already be an administrator in that channel. ![Manage Projects](/assets/images/tutorials/telegram/telegram_screen_7.png) *Figure 7: Managing your projects in BlockBee Bot* ### Step 4: Configure Subscriptions After selecting your Telegram Channel, the management options will be displayed. To begin, you will need to set up the subscription price for the desired time periods. You can do this by clicking on the "Subscriptions" button. ![Select Channel](/assets/images/tutorials/telegram/telegram_screen_8.png) *Figure 8: Selecting your Telegram channel to manage* ### Step 5: Set Pricing Once you click the "Subscriptions" button, a list of options for different time periods will be displayed. Here, you can set up the subscription price for the desired time period that you wish to accept. ![Subscriptions Button](/assets/images/tutorials/telegram/telegram_screen_9.png) *Figure 9: Accessing subscription configuration* ### Step 6: Enter Amount Upon clicking one of the available options, the BlockBee Bot will prompt you to enter the amount you want to charge in FIAT currency to your customers. BlockBee uses this amount to generate a payment address in the cryptocurrency your customer selects. > **INFO** >**Currency:** The amount is in the FIAT currency configured in your BlockBee Dashboard. ### Step 7: Activate Bot Finally, you will need to select the "Activate BlockBee_bot in this group" option to activate the bot in the channel you have chosen. ## Testing Your Telegram Bot Test your Telegram Bot setup using real cryptocurrency with minimal cost. ### 1. Use Litecoin for Testing We recommend using **Litecoin (LTC)** for testing because: - Low transaction fees (typically under $0.01) - Fast confirmation times (2.5 minutes average) - Real blockchain testing without high costs ### 2. Test with a Small Amount - Create a subscription for a small value (e.g., $2.00) - Complete the payment using Litecoin - This covers all fees with minimal cost (typically under $0.10) - Test both pending and confirmed payment states ### 3. Testing Checklist - ✅ Telegram bot creation works - ✅ BlockBee Bot project creation works - ✅ Bot token and API key configuration works - ✅ Channel/group selection works - ✅ Subscription pricing setup works - ✅ Bot activation in channel works - ✅ Payment processing works (in-Telegram and payment links) - ✅ User invitation link generation works - ✅ Automatic user removal on expiration works - ✅ Renewal notifications work correctly - ✅ Coupon system functions properly ### 4. Test User Flow - Test the complete user journey from subscription to channel access - Verify that invitation links work correctly - Test subscription expiration and automatic removal - Test renewal process for existing subscribers > **SUCCESS** >**Ready for production?** Once testing is complete, ensure your bot is properly configured and your channel/group is ready to accept subscribers. --- # Tickers > Source: https://docs.blockbee.io/get-started/tickers > Description: Learn about the {ticker} parameter and how it's used to specify cryptocurrencies and tokens in the BlockBee API. # Tickers The `{ticker}` parameter is a crucial part of many BlockBee API requests. It's a unique identifier that specifies the cryptocurrency or token you want to interact with. ## Structure A ticker is typically a short code that represents a specific cryptocurrency or a token on a particular network. - **For cryptocurrencies:** The ticker is usually the standard abbreviation, like `btc` for Bitcoin or `eth` for Ethereum. - **For tokens:** The ticker is composed of the network/blockchain followed by the token's symbol, separated by a slash. For example, `trc20/usdt` represents USDT on the TRC-20 (Tron) network. ## Examples Here are a few examples of how tickers are used in an API path: - `https://api.blockbee.io/btc/create/` - `https://api.blockbee.io/trc20/usdt/create/` ## Finding Tickers You can find a complete list of all supported tickers on our [Cryptocurrencies Page](https://blockbee.io/cryptocurrencies). --- # WooCommerce Plugin > Source: https://docs.blockbee.io/get-started/woocommerce > Description: Integrate cryptocurrency payments into your WooCommerce store with our official plugin ![WooCommerce Logo](/assets/images/plugins/woocommerce.png) # BlockBee for WooCommerce Accept cryptocurrency payments on your WooCommerce website ## Requirements ``` PHP >= 7.2 Wordpress >= 5.8 WooCommerce >= 5.8 ``` ## Download {% button href="https://wordpress.org/plugins/blockbee-cryptocurrency-payment-gateway/" variant="default" size="default" %} Download Plugin {% /button %} ## Description Accept payments in Bitcoin, Bitcoin Cash, Litecoin, Ethereum, Monero and IOTA directly to your crypto wallet. ### Allow users to pay with crypto directly on your store The BlockBee plugin extends WooCommerce, allowing you to get paid in crypto directly on your store, with a simple setup. ### Accepted cryptocurrencies & tokens include: BlockBee supports 100+ cryptocurrencies and tokens. > **INFO** >View the complete list [here](https://blockbee.io/cryptocurrencies/). ### Auto-value conversion BlockBee plugin will attempt to automatically convert the value you set on your store to the cryptocurrency your customer chose. Exchange rates are fetched every 5 minutes. ### Supported currencies for automatic exchange rates are: * (USD) US Dollar * (EUR) Euro * (GBP) GB Pound * (CAD) Canadian Dollar * (CHF) Swiss Franc * (JPY) Japanese Yen * (AED) UAE Dollar * (DKK) Danish Krone * (BRL) Brazilian Real * (CNY) Chinese Yuan * (HKD) Hong Kong Dollar * (INR) Indian Rupee * (MXN) Mexican Peso * (UGX) Uganda Shillings * (PLN) Poland Zloti * (PHP) Philippine Peso * (CZK) Czech Koruna * (HUF) Hungarian Forint * (BGN) Bulgarian Lev * (RON) Romanian Leu * (ZAR) South African Rand * (LKR) Sri Lankan Rupee * (TRY) Turkish Lira * (THB) Thai Baht * (RUB) Russian Ruble * (IDR) Indonesian Rupiah * (MYR) Malaysian Ringgit * (SGD) Singapore Dollar * (TWD) New Taiwan Dollar * (AUD) Australian Dollar * (NGN) Nigerian Naira * (SEK) Swedish Krona * (NOK) Norwegian Krone * (UAH) Ukrainian Hryvnia * (VND) Vietnamese Dong If your WooCommerce's currency is none of the above, the exchange rates will default to USD. If you're using WooCommerce in a different currency not listed here and need support, [contact us](https://blockbee.io) via our live chat. **Note:** BlockBee will not exchange your crypto for FIAT or other crypto, just convert the value ### Why choose BlockBee? BlockBee has no setup fees, no monthly fees, no hidden costs, and you don't even need to sign-up! Simply set your crypto addresses and you're ready to go. As soon as your customers pay we forward your earnings directly to your own wallet. BlockBee has a low 1% fee on the transactions processed. No hidden costs. > **INFO** >For more info on our fees [click here](https://blockbee.io/fees/). ## Installation ### Using The WordPress Dashboard 1. Navigate to the 'Add New' in the plugins dashboard 2. Search for 'BlockBee for WooCommerce' 3. Click 'Install Now' 4. Activate the plugin on the Plugin dashboard ### Uploading in WordPress Dashboard 1. Navigate to the 'Add New' in the plugins dashboard 2. Navigate to the 'Upload' area 3. Select `woocommerce-blockbee.zip` from your computer 4. Click 'Install Now' 5. Activate the plugin in the Plugin dashboard ### Using FTP 1. Download `woocommerce-blockbee.zip` 2. Extract the `woocommerce-blockbee` directory to your computer 3. Upload the `woocommerce-blockbee` directory to the `/wp-content/plugins/` directory 4. Activate the plugin in the Plugin dashboard ### Updating Automatic updates should work like a charm; as always though, ensure you backup your site just in case. ## Configuration 1. Go to WooCommerce settings 2. Select the "Payments" tab 3. Activate the payment method (if inactive) 4. Set the name you wish to show your users on Checkout (for example: "Cryptocurrency") 5. Fill the payment method's description (for example: "Pay with cryptocurrency") 6. Select which cryptocurrencies you wish to accept (control + click to select many) 7. Input your addresses to the cryptocurrencies you selected. This is where your funds will be sent to, so make sure the addresses are correct. 8. Click "Save Changes" 9. All done! ## Tutorial ### Installing BlockBee Plugin in WooCommerce The BlockBee plugin extends WooCommerce, allowing you to get paid in crypto directly on your Store, with a simple setup and no sign-ups required. In this page we will guide you throughout the configuration and installation of our official WooCommerce Plugin. #### Step 1: Access Plugins 1. First you need to have WooCommerce installed. Then you go to "Plugins". ![WooCommerce Step 1](/assets/images/tutorials/woocommerce/woocommerce_screen_1.png) #### Step 2: Add New Plugin 2. In the Plugins page click the Add New button. ![WooCommerce Step 2](/assets/images/tutorials/woocommerce/woocommerce_screen_2.png) #### Step 3: Search and Install 3. Type "BlockBee" in the search input and when our plug-in appear in the search result, click Install Now. Then just wait for WordPress to finish installing it. ![WooCommerce Step 3](/assets/images/tutorials/woocommerce/woocommerce_screen_3.png) #### Step 4: Activate Plugin 4. When WordPress finish installing BlockBee plug-in, click Activate. ![WooCommerce Step 4](/assets/images/tutorials/woocommerce/woocommerce_screen_4.png) #### Step 5: Access WooCommerce Settings 5. Then go to WooCommerce and click the Settings link. ![WooCommerce Step 5](/assets/images/tutorials/woocommerce/woocommerce_screen_5.png) #### Step 6: Navigate to Payments 6. In the WooCommerce Settings page click in the Payments button. ![WooCommerce Step 6](/assets/images/tutorials/woocommerce/woocommerce_screen_6.png) #### Step 7: Setup BlockBee 7. Here you will have to scroll to "BlockBee Cryptocurrency Payment Gateway" and click Finish set up. This action will take you into the plugin settings where you will finish the configuration. ![WooCommerce Step 7](/assets/images/tutorials/woocommerce/woocommerce_screen_7.png) #### Step 8: Configure API Key 8. Make sure the checkbox it's selected, to enable BlockBee plugin and that you get a valid API Key from our dashboard and paste it in the "API Key" field. This is mandatory, failing to do it so will result in the plug-in to error out when trying to make an order. You can also play around the settings a bit to make our WooCommerce plug-in fit your needs. ![WooCommerce Step 8](/assets/images/tutorials/woocommerce/woocommerce_screen_8.png) #### Step 9: Select Cryptocurrencies 9. Finally you must select the cryptocurrencies you want to accept in your WooCommerce store. You must make sure your wallet address set in the dashboard, otherwise plug-in will fail to make orders. **Note:** You can select multiple ones with CTRL + click on Windows, or CMD + click on MAC. ## Frequently Asked Questions ### Do I need an API key? Yes. To use our service you will need to register at our [dashboard](https://dash.blockbee.io/) and create a new API Key. ### How long do payments take before they're confirmed? This depends on the cryptocurrency you're using. Bitcoin usually takes up to 11 minutes, Ethereum usually takes less than a minute. ### Is there a minimum for a payment? Yes, the minimums change according to the chosen cryptocurrency and can be checked [here](https://blockbee.io/cryptocurrencies). If the WooCommerce order total is below the chosen cryptocurrency's minimum, an error is raised to the user. > **INFO** >**Where can I get support?** The easiest and fastest way is via our live chat on our [website](https://blockbee.io) or via our [contact form](https://blockbee.io/contacts/). ## Changelog ### 1.0.0 * Initial release. ### 1.0.1 * Minor fixes ### 1.0.2 * Minor fixes ### 1.0.3 * Minor fixes * UI improvements ### 1.0.4 * Minor fixes ### 1.0.5 * Minor fixes ### 1.0.6 * Minor fixes ### 1.0.7 * Minor fixes * Improvements on the callback processing algorithm ### 1.0.8 * Minor fixes ### 1.0.9 * Minor fixes ### 1.0.10 * Minor fixes ### 1.0.11 * Minor fixes ### 1.0.12 * Minor fixes ### 1.0.13 * Minor fixes ### 1.0.14 * Performance improvements. * Minor fixes. ### 1.0.15 * Minor fixes. ### 1.0.16 * Minor fixes. ### 1.0.17 * Support for WooCommerce HPOS. * Minor fixes. ### 1.0.18 * Add new choices for order cancellation. ### 1.0.19 * Minor fixes and improvements. ### 1.0.20 * Minor fixes and improvements. ### 1.1.0 * Support for new languages: German, French, Ukrainian, Russian and Chinese. ### 1.1.1 * Minor fixes and improvements. ### 1.1.2 * Minor fixes and improvements. ### 1.1.3 * Minor fixes and improvements. ### 1.1.4 * Minor fixes and improvements. ### 1.1.5 * Minor fixes and improvements. ### 1.1.6 * Minor improvements ### 1.1.7 * Minor improvements ### 1.2.0 * Support BlockBee Checkout page * Minor improvements ### 1.2.1 * Minor fixes ### 1.2.2 * Minor fixes ### 1.2.3 * Minor fixes ### 1.2.4 * Minor fixes ### 1.2.5 * Minor fixes ### 1.2.6 * Minor improvements ### 1.2.7 * Minor improvements. * Minor fixes. ### 1.2.8 * Minor improvements. * Minor fixes. ### 1.3.0 * Version bump ### 1.4.0 * Now supports WordPress Blocks. * Bug fixes. ### 1.4.1 * Now supports WordPress Blocks. * Bug fixes. ### 1.4.2 * Bug fixes. ### 1.4.3 * Bug fixes. ### 1.5.0 * Callback improvements * Minor bugfixes ### 1.5.1 * Version bump ### 1.5.2 * Minor bugfixes ### 1.5.3 * New customization options * Minor bugfixes ### Upgrade Notice * No breaking changes --- # Convert Price > Source: https://docs.blockbee.io/api/convert-price > Description: This method enables seamless price conversion between fiat currencies and cryptocurrencies, as well as between different cryptocurrencies. # Convert Prices This method enables seamless price conversion between fiat currencies and cryptocurrencies, as well as between different cryptocurrencies, by passing the ticker as a GET parameter. This approach provides flexibility and clarity when managing multiple conversions programmatically. **Note:** * Prices are fetched every 5 minutes from CoinMarketCap. **Method:** `GET` **Path:** ``` https://api.blockbee.io/convert/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`value`** (`number`) (required) - Example: `10`: Value you wish to convert in the cryptocurrency/token of the ticker you are using. - **`from`** (`string`) (required) - Example: `usd`: Specify the currency you wish to convert **from**, whether it is FIAT or cryptocurrency. Check our full list of supported [cryptocurrencies](https://blockbee.io/cryptocurrencies/). **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 - **`to`** (`string`) (required) - Example: `btc`: Specify the currency you wish to convert **to**, whether it is FIAT or cryptocurrency. Check our full list of supported [cryptocurrencies](https://blockbee.io/cryptocurrencies/). **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 ## Returns Returns the converted value and the exchange rate. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`value_coin`** (`string`): Converted value for the selected currencies. - **`exchange_rate`** (`string`): The exchange rate between the 2 currencies. ## Example Response ```json { "status": "success", "value_coin": "0.0000088", "exchange_rate": "0.00000880022" } ``` --- # Convert Prices Using Ticker > Source: https://docs.blockbee.io/api/convert-price-by-ticker > Description: With this method, you can effortlessly convert prices between FIAT currencies and cryptocurrencies, or even between different cryptocurrencies, by specifying the ticker directly in the URL path. This makes the conversion process straightforward and easy to implement. **Note:** * Prices are fetched every 5 minutes from CoinMarketCap. # Convert Prices Using Ticker With this method, you can effortlessly convert prices between FIAT currencies and cryptocurrencies, or even between different cryptocurrencies, by specifying the ticker directly in the URL path. This makes the conversion process straightforward and easy to implement. **Note:** * Prices are fetched every 5 minutes from CoinMarketCap. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/convert/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required) - Example: `btc`: 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies/) page. ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** * The API key can also be sent as a header named `apikey`. - **`value`** (`number`) (required) - Example: `1`: Value you wish to convert in the cryptocurrency/token of the ticker you are using. - **`from`** (`string`) (required) - Example: `USD`: Specify the currency you wish to convert from, whether it is FIAT or cryptocurrency. Check our full list of supported [cryptocurrencies](https://blockbee.io/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](https://blockbee.io/contacts/) 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 - (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 ## Returns Returns the converted value and the exchange rate. - **`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. ## Example Response ```json { "value_coin": "0.01", "exchange_rate": "47000", "status": "success" } ``` --- # Create a Checkout Payment Link > Source: https://docs.blockbee.io/api/create-checkout > Description: 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. # Create a Checkout Payment Link 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 - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`redirect_url`** (`string`) (required) - Example: `https://example.com/success/?order_id=12345`: 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` - **`value`** (`string`) (required) - Example: `10`: Value of the order in the FIAT currency set in your Payment Settings at BlockBee's [Dashboard](https://dash.blockbee.io/). - **`currency`** (`string`) - Example: `eur`: Set the FIAT currency used in the `value` parameter. **Note:** Will override the FIAT currency set in your Payment Settings at BlockBee's [Dashboard](https://dash.blockbee.io/). **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](https://blockbee.io/cryptocurrencies) page (eg: `currency=btc`). - **`item_description`** (`string`) - Example: `Order #1234`: Description of the product or service being paid. This information will appear on the Checkout page. - **`customer_name`** (`string`) - Example: `John Doe`: Your customer's name. Will be returned in the payment notification (webhook). - **`customer_email`** (`string`) - Example: `email@example.com`: Your customer's email. Will be returned in the payment notification (webhook). - **`expire_at`** (`number`) - Example: `1673438907`: 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** - **`notify_url`** (`string`) - Example: `https://example.com/callback/?order_id=12345`: 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](/webhooks/checkout-payments-webhook) * To prevent repeated IPNs to your systems, the response to the IPN request should be `*ok*` in plain text - **`post`** (`number`) - Example: `1`: 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` --- ## 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. - **`status`** (`string`) (required): Status of the request. Should be `success` if the request didn't fail. - **`payment_id`** (`string`) (required): ID of the checkout payment. May be used with the [logs](/api/get-checkout-logs) endpoint. - **`success_token`** (`string`) (required): A unique token that is passed to your `redirect_url` to verify the payment's authenticity on your end. - **`payment_url`** (`string`) (required): The URL for the hosted checkout page where the user can complete the payment. ## Example Response ```json { "status": "success", "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "success_token": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9NfG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "payment_url": "https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N" } ``` --- # Create Deposit Request > Source: https://docs.blockbee.io/api/create-deposit > Description: This method allows you to create a deposit request. # Create a Checkout Deposit Link This method allows you to create a new Deposit link. **Notes:** * Enables multiple payments and can serve as a static deposit link for your platform. **Method:** `GET` **Path:** ``` https://api.blockbee.io/deposit/request/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`notify_url`** (`string`) (required) - Example: `https://example.com/callback/?user_id=1124`: 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](/webhooks/checkout-deposits-webhook) * To prevent repeated IPNs to your systems, the response to the IPN request should be `*ok*` in plain text - **`currency`** (`string`) - Example: `eur`: Set the FIAT currency used in the `value` parameter. **Note:** Will override the FIAT currency set in your Payment Settings at BlockBee's [Dashboard](https://dash.blockbee.io/). **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](https://blockbee.io/cryptocurrencies) page (eg: `currency=btc`). - **`item_description`** (`string`) - Example: `Deposit #123`: Description of the product or service being paid. This information will appear on the Checkout page. - **`customer_name`** (`string`) - Example: `John Doe`: Your customer's name. Will be returned in the payment notification (webhook). - **`customer_email`** (`string`) - Example: `email@example.com`: Your customer's email. Will be returned in the payment notification (webhook). - **`post`** (`number`) - Example: `1`: 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` - **`suggested_value`** (`number`) - Example: `10`: Set this field if you'd like to suggest a specific amount in the deposit link. Must be a number higher than 0. **Notes:** * If disabled, the deposit link will display the minimum transaction amount instead * This is a suggested value only. Transactions will still be processed if the customer sends less (or more) than the suggested amount, provided it meets our [minimum transaction](https://blockbee.io/cryptocurrencies/) requirements --- ## Returns Returns the deposit link response. Returns an error if there's there's a missing required parameter of if you didn't configure the payment settings correctly. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`payment_url`** (`string`): Payment URL where your customer should be redirected to initiate the transaction. Note: It's possible to pre-select a cryptocurrency for the checkout page by using the `coin` GET parameter. * All of our supported tickers can be found at our [cryptocurrencies page](https://blockbee.io/cryptocurrencies). Replace `/` with `_` in ticker paths (e.g. `trc20_usdt`). * Example: In order to pre-select Bitcoin for the payment, append `?coin=trc20_usdt` to the payment_url as the following example: `https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N?coin=trc20_usdt`. - **`payment_id`** (`string`): ID of the deposit. May be used with the [logs endpoint](/api/get-deposit-logs). ## Example Response ```json { "status": "success", "payment_url": "https://pay.blockbee.io/deposit/Zz87cpYde6cKszIwn0A6oOxea2i1eGoJ/", "payment_id": "Zz87cpYde6cKszIwn0A6oOxea2i1eGoJ" } ``` --- # Create New Payment Address > Source: https://docs.blockbee.io/api/create-payment-address > Description: Generates a new address to give your customer for payment. Transactions below the minimum transfer limit for the chosen [cryptocurrency](https://blockbee.io/cryptocurrencies/) are rejected. **Notices:** * The length of this request must not exceed `8192` characters. * Check the minimum transfer limit for your chosen [cryptocurrency](https://blockbee.io/cryptocurrencies/) before generating an address. Transactions below the minimum are rejected. # Create New Payment Address Generates a new address to give your customer for payment. **Notices:** * The request must not exceed `8192` characters. * Check the minimum transfer limit for your chosen [cryptocurrency](https://blockbee.io/cryptocurrencies/) before generating an address. Transactions below the minimum are rejected. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/create/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required) - Example: `btc`: 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`callback`** (`string`) (required) - Example: `https://example.com/your_callback?invoice_id=123`: 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 [webhooks](/webhooks/custom-payment-flow-webhooks) as a `GET` parameter, even if you set the webhook to `post` or `json`. * 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](https://dash.blockbee.io/), BlockBee systems will not change the `address_out`, meaning you will need to change your callback URL to generate a new `address_in`. * URL-encode the callback URL if it contains query parameters, otherwise they may be dropped. * `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](/api/get-payment-logs) endpoint later. * See the [webhooks documentation](/webhooks/custom-payment-flow-webhooks) for the complete callback field reference. - **`address`** (`string`) - Example: `1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP`: By default, addresses are set in BlockBee's [Dashboard](https://dash.blockbee.io/), 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](https://dash.blockbee.io/), 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](https://blockbee.io/cryptocurrencies/)**) 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](/kb/payments/how-to-calculate-the-minimum-when-using-multiple-addresses). - **`pending`** (`integer`) - Example: `1`: 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. * See the [webhooks documentation](/webhooks/custom-payment-flow-webhooks) for the full list of fields sent with each callback. - **`confirmations`** (`integer`) - Example: `3`: Number of blockchain confirmations you want before receiving the [webhook](/webhooks/custom-payment-flow-webhooks). Min: `1` - **`post`** (`integer`) - Example: `1`: 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`. * Not compatible with the `json` parameter. - **`json`** (`integer`) - Example: `1`: Set this to `json=1` to enable. If enabled the callback body will be sent as `JSON`. If disabled, will default to `GET`. **Notes**: * `GET` parameters you added to the `callback` URL will still be sent as `GET`. * Not compatible with the `post` parameter. - **`priority`** (`string`) - Example: `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](/kb/developers/api/what-is-the-priority-parameter). - **`multi_token`** (`integer`) - Example: `1`: 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 TRC20 and all supported EVM-based blockchains (eg. ERC20, BEP20, POLYGON). * 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](/kb/developers/api/what-is-the-multi-token-parameter). - **`convert`** (`integer`) - Example: `1`: 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. --- ## Returns Returns the newly created payment address details. - **`address_in`** (`string`): Address generated by our API. You must provide it to your customer 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. - **`minimum_transaction_coin`** (`number`): The minimum transaction value coin. All the minimums can be found at our [cryptocurrencies page](https://blockbee.io/cryptocurrencies). - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. ## Example Response ```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", "minimum_transaction_coin": 0.008, "status": "success" } ``` --- # Create Payout > Source: https://docs.blockbee.io/api/create-payout > Description: Create a Payout by providing the Payout Request ID(s). # Create Payout Create a **Payout** by providing the **Payout Request** `ID`. **Notes:** * You can provide multiple IDs eg: `7f839bdd-5acd-4ce3-984d-1be8357b642d,7f839bdd-5asd-4ce3-984d-1be8357b646d`. **Method:** `POST` **Path:** ``` https://api.blockbee.io/payout/create/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- ## Request Body This endpoint requires a request body with the `payout_request_ids`. **Note**: The request `Content-Type` header must be set to `application/x-www-form-urlencoded`. - **`request_ids`** (`string`) (required) - Example: `{request_ids=7f839bdd-5acd-4ce3-984d-1be8357b642d,7f839bdd-5asd-4ce3-914d-1be8357b646d}`: The `ID` or a list of `IDs` of the Payout Requests you want to include in the Payout. --- ## Returns Returns information about the newly created payout. - **`status`** (`string`): Status of the request. Indicates success if the request has been accepted. - **`payout_info`** (`object`): Contains detailed information about the created payout. - **`id`** (`string`): The ID of the created payout. - **`status`** (`string`): The status of the created payout. Can be created, processing, done, rejected, or error. - **`display_status`** (`string`): The verbose status of the created payout. Can be Created, Pending Payment, Done, Rejected, or Error. - **`from`** (`string`): The source from which the payout was created, if applicable. - **`requests`** (`object`): A map of payout request addresses to their respective amounts. The keys are dynamic wallet addresses, and the values are the string amounts. - **`total_requested`** (`string`): The total cryptocurrency amount requested for the payout. - **`total_with_fee`** (`string`): The total amount requested including the fee. - **`error`** (`string`): The error message given in case the payout status is error. - **`blockchain_fee`** (`string`): The fee paid to the blockchain for the transaction. - **`fee`** (`string`): The fee associated with the payout. - **`coin`** (`string`): The cryptocurrency for the payout. - **`txid`** (`string`): The transaction ID of the payout, if it has been processed. - **`timestamp`** (`string`): The timestamp when the payout was created. ## Example Response ```json { "status": "success", "payout_info": { "id": "b4252c0a-03f1-4715-90b8-a32ba4c91b9f", "status": "created", "display_status": "Created", "from": "", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.2" }, "total_requested": "0.2", "total_with_fee": "0.201", "error": null, "blockchain_fee": 0, "fee": "0.001", "coin": "bep20_usdt", "txid": "", "timestamp": "10/07/2025 17:28:29" } } ``` --- # Create a Payout Request > Source: https://docs.blockbee.io/api/create-payout-request > Description: 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](https://dash.blockbee.io/), or by using BlockBee API. # 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](https://dash.blockbee.io/), or by using BlockBee API. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/payout/request/create/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. --- ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`address`** (`string`) (required) - Example: `TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF`: Provide the destination `address` where you want the Payout to be sent. - **`value`** (`number`) (required) - Example: `1.34`: Amount you wish to send to the provided destination `address`. --- ## Returns Returns the ID of the newly created payout request. - **`status`** (`string`): Status of the request. Should be success if the request didn't fail. - **`request_id`** (`string`): ID of the Payout Request. ## Example Response ```json { "status": "success", "request_id": "3825d29b-7a8f-47da-8623-e99850674247" } ``` --- # Bulk Create Payout Requests > Source: https://docs.blockbee.io/api/create-payout-requests-bulk > Description: This method allows you to create multiple payout requests in bulk for a specific ticker. # Create multiple Payout Requests Use this method to create multiple Payout Requests. **Notes:** * A `Payout Request` represents a payment request initiated to facilitate a transaction with your customer. **Method:** `POST` **Path:** ``` https://api.blockbee.io/{ticker}/payout/request/bulk/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. ## Request Body This endpoint requires a JSON request body with the payout requests. **Note**: The request `Content-Type` header must be set to `application/json`. ```json { "outputs": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": 0.2, "0x18B211A1Ba5880C7d62C250B6441C2400d588589": 0.1 } } ``` ## Returns Returns a success message if the payout requests were created successfully. - **`status`** (`string`): Status of the response, indicating the successful creation of Payout Requests. - **`request_ids`** (`Array of strings`): An array of request IDs for the newly created Payout Requests. ## Example Response ```json { "status": "success", "request_ids": [ "2a4437cb-4a5c-43c7-b3cb-4103bbae9486", "8676ebfb-14c4-4455-af85-59257a8d1d8f" ] } ``` --- # Create Subscription > Source: https://docs.blockbee.io/api/create-subscription > Description: This method allows you to create a subscription. # Create a Subscription Use this endpoint to create or update a Subscription for a given user. If a Subscription Option is provided, a payment will be prepared and a checkout URL returned. The customer will be notified before the subscription expires, so they can manually renew it. **Notes:** * Requires a configured Subscription Service. * At least one cryptocurrency must be enabled in the service options to generate a payment link. **Method:** `GET` **Path:** ``` https://api.blockbee.io/subscription/create/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`user_id`** (`string`) (required) - Example: `user_1234`: User identifier in your system. - **`user_email`** (`string`) (required) - Example: `example@mail.com`: Customer e-mail to notify before subscription expiration. - **`option`** (`string`) - Example: `pro`: Unique identifier for the subscription plan that the user will be charged for. This is useful when displaying subscription options on your own website or application. **Notes:** - When a subscription plan slug is provided, the `subscription_url` will be converted to a direct payment link for that specific plan. - **`post`** (`number`) - Example: `1`: 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`. --- ## Returns Returns the subscription details, including the subscription URL and a token. - **`status`** (`string`): Status of the request. - **`token`** (`string`): Token associated with the created subscription. - **`subscription_url`** (`string`): Subscription or payment link for the customer. ## Example Response ```json { "status": "success", "token": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o" } ``` --- # Estimate Blockchain Fees > Source: https://docs.blockbee.io/api/estimate-fees > Description: 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. # 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. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/estimate/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required) - Example: `btc`: 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies/) page. ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** * The API key can also be sent as a header named `apikey`. - **`addresses`** (`integer`) - Example: `1`: The number of addresses to forward the funds to. Should be the same you set in the BlockBee's [Dashboard](https://dash.blockbee.io/) or in the [`address`](/api/create-payment-address#address) parameter. **Notes:** * The higher the number of addresses, the higher the blockchain fee will be. - **`priority`** (`string`) - Example: `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](/kb/developers/api/what-is-the-priority-parameter). * Only supported when using Bitcoin, Ethereum/ERC-20 and Litecoin. ## Returns Returns the estimated cost for the transaction. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`estimated_cost`** (`integer`): Estimated cost in the blockchain's native cryptocurrency. **Notes:** * Example, transactions on the Bitcoin network will have costs estimated in BTC, while transactions using USDT on the TRC20 (Tron) network will have costs estimated in TRX. * You can also check our cryptocurrencies page for a quick estimation of blockchain fees. - **`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. In case your desired FIAT currency is not included in the list of supported currencies, contact us to request it: - (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 **Notes:** Updated every 5 minutes from CoinMarketCap. ## Example Response ```json { "status": "success", "estimated_cost": "0.00000213000", "estimated_cost_currency": { "AED": "0.84", "AUD": "0.35", "BGN": "0.38", "BRL": "1.26", "CAD": "0.31", "CHF": "0.18", "CNY": "1.65", "COP": "926.32", "CZK": "4.82", "DKK": "1.46", "EUR": "0.20", "GBP": "0.17", "HKD": "1.80", "HUF": "78.41", "IDR": "3731.31", "INR": "19.70", "JPY": "33.10", "LKR": "68.95", "MXN": "4.32", "MYR": "0.97", "NGN": "352.22", "NOK": "2.33", "PHP": "12.96", "PLN": "0.83", "RON": "0.99", "RUB": "18.11", "SEK": "2.20", "SGD": "0.29", "THB": "7.46", "TRY": "9.15", "TWD": "6.68", "UAH": "9.60", "UGX": "826.72", "USD": "0.23", "VND": "6016.13", "ZAR": "4.06" } } ``` --- # Payment QR Code Generator > Source: https://docs.blockbee.io/api/generate-qr-code > Description: This method generates a base64-encoded QR Code image for payments. # Payment QR Code Generator This method generates a base64-encoded QR Code image for payments. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/qrcode/ ``` --- ## Parameters ### Path Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`address`** (`string`) (required): 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`): Size of the QR Code image in pixels. Min: `64` Max: `1024` --- ## Returns Returns the base64-encoded QR Code image, and the payment URI. - **`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: ```html <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. ## Example Response ```json { "status": "success", "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAABsklEQVR4nO3WsQ3EIAwE0LnA/ld3MoQJc4K4v2ALzaKdg75vdv4qgQAEIAABCEAAAhCAAAQ@example", "payment_uri": "bitcoin:14PqCsA7KMgseZMPwg6mJy754MtQkrgszu?amount=0.1" } ``` --- # Get Checkout Logs > Source: https://docs.blockbee.io/api/get-checkout-logs > Description: This method allows you to get the logs for a checkout payment. # Retrieve Payment Logs This method allows you to check the payment status and the IPN logs for a payment using our API. **Method:** `GET` **Path:** ``` https://api.blockbee.io/checkout/logs/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): {% endpointParameter name="token" type="string" id="token" required=true example="fG78jtx96ugjtu0eIbeLmFB9z0feJf9N" %} The `payment_id` provided upon requesting the payment link. --- ## Returns Returns the payment logs. Returns an error if there's a missing required parameter or if you didn't configure the payment settings correctly. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`is_paid`** (`boolean`): `true` if the payment is paid. - **`is_pending`** (`boolean`): `true` if the payment is pending blockchain confirmation. - **`is_expired`** (`boolean`): `true` if the payment is expired. Any payment sent to the generated addresses after expiration will be disregarded. - **`is_partial`** (`boolean`): `true` if the payment is partially paid. This can happen if the amount transferred is below the total. - **`payment_data`** (`object[]`): Detailed information about each payment option. This object contains the following fields: - **`value`** (`string`): The total requested payment amount in the specified cryptocurrency. - **`value_paid`** (`string`): The amount that has already been paid. - **`value_outstanding`** (`string`): The remaining amount that has yet to be paid. - **`exchange_rate`** (`string`): The exchange rate applied to the payment. - **`coin`** (`string`): The cryptocurrency used for the payment (e.g., `eth`, `btc`, `bep20_usdt`). - **`txid`** (`string[]`): An array of transaction IDs related to the payment. - **`notifications`** (`object[]`): A list of notifications sent for payment processing. This object contains the following fields: - **`request_url`** (`string`): The URL to which the notification request was sent. - **`payload`** (`object`): The JSON payload sent in the notification. - **`payment_url`** (`string`): The URL for the hosted checkout page where the user can complete the payment. - **`redirect_url`** (`string`): URL where your customers will be redirected to after successfully completing the payment. - **`value`** (`string`): Value of the order. - **`success_token`** (`string`): A unique token that is passed to your `redirect_url` to verify the payment's authenticity on your end. - **`currency`** (`string`): The FIAT currency of the `value`. - **`is_paid`** (`integer`): `1` if the payment is paid. - **`paid_amount`** (`string`): The amount paid by the user. - **`paid_coin`** (`string`): The cryptocurrency the user paid with. - **`exchange_rate`** (`string`): The exchange rate applied to the payment. - **`txid`** (`string`): The transaction ID of the payment. - **`address`** (`string`): The address that received the payment. - **`status`** (`string`): Status of the payment. - **`response`** (`string`): The response received from the server for the notification. - **`response_status`** (`string`): The HTTP status code of the notification response. - **`pending`** (`boolean`): Indicates whether the notification is still pending. - **`timestamp`** (`string`): The timestamp when the notification was sent. ## Example Response ```json { "status": "success", "logs": [ { "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "status": "completed", "amount": "10", "currency": "eur", "created_at": "2024-03-12T14:40:11Z" } ] } ``` --- # Get Deposit Logs > Source: https://docs.blockbee.io/api/get-deposit-logs > Description: This method allows you to get the logs for a deposit request. # Retrieve Deposit Logs Fetches logs of all deposits made to your Deposit link, including transaction details, value in fiat currency, and the status of each deposit. This endpoint is essential for tracking incoming payments and ensuring they are correctly processed and reconciled in your system. **Method:** `GET` **Path:** ``` https://api.blockbee.io/deposit/logs/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`token`** (`string`) (required) - Example: `fG78jtx96ugjtu0eIbeLmFB9z0feJf9N`: The `payment_id` provided upon requesting the deposit link. --- ## Returns Returns a list of deposit transactions made to your account. - **`status`** (`string`): Status of the request. Should be success if the request didn't fail. - **`deposits`** (`object[]`): Array of objects - **`txid`** (`string`): The transaction ID of the deposit. - **`value`** (`string`): The amount deposited in cryptocurrency. - **`value_fiat`** (`string`): The equivalent fiat value of the deposited amount. - **`coin`** (`string`): The type of cryptocurrency used for the deposit. - **`pending`** (`boolean`): Indicates if the deposit is still pending. - **`logo`** (`string`): URL to the logo of the cryptocurrency used. - **`timestamp`** (`string`): The timestamp when the deposit was made. - **`total_deposited`** (`string`): The total amount deposited. - **`currency`** (`string`): The fiat currency used for the value_fiat field. - **`notifications`** (`object[]`): Notifications sent regarding deposit processing. - **`request_url`** (`string`): The URL to which the notification request was sent. - **`payload`** (`object`): Details of the notification sent. - **`payment_url`** (`string`): The URL for the hosted checkout page where the user can complete the payment. - **`redirect_url`** (`string`): URL where your customers will be redirected to after successfully completing the payment. - **`value`** (`string`): Value of the order. - **`success_token`** (`string`): A unique token that is passed to your `redirect_url` to verify the payment's authenticity on your end. - **`currency`** (`string`): The FIAT currency of the `value`. - **`is_paid`** (`integer`): `1` if the payment is paid. - **`paid_amount`** (`string`): The amount paid by the user. - **`paid_coin`** (`string`): The cryptocurrency the user paid with. - **`exchange_rate`** (`string`): The exchange rate applied to the payment. - **`txid`** (`string`): The transaction ID of the payment. - **`address`** (`string`): The address that received the payment. - **`status`** (`string`): Status of the payment. - **`response`** (`string`): The server's response to the notification request. - **`response_status`** (`string`): The HTTP status code of the response received. - **`pending`** (`boolean`): Indicates whether the notification is still pending. - **`timestamp`** (`string`): The timestamp when the notification was sent. ## Example Response ```json { "status": "success", "logs": [ { "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu", "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP", "value_coin": "0.00100000", "value_forwarded_coin": "0.00099000", "value_usd": "107.99", "callback_url": "https://example.com/your_callback?invoice_id=123", "confirmations": 3, "txid_in": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6", "txid_out": "z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1", "timestamp": "2024-01-15 10:30:45", "pending": 0, "fee": "0.00001000", "fee_usd": "1.08", "priority": "default", "value_coin_convert": "{\"USD\":\"107.99\",\"EUR\":\"98.45\"}", "value_forwarded_coin_convert": "{\"USD\":\"106.91\",\"EUR\":\"97.47\"}" } ] } ``` --- # Check Payment Address Logs > Source: https://docs.blockbee.io/api/get-payment-logs > Description: 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. # Check Payment Address 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. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/logs/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. --- ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- - **`callback`** (`string`) (required): 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. * URL-encode the `callback` when making the request. If using one of our libraries there's no need for it. --- ## Returns Returns a list of callbacks for the specified address. Returns an error if the address is not found or if there are no callbacks. - **`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. - **`callbacks`** (`Array of objects`): List of payments made to this address, together with the logs of the callbacks to your system. - **`txid_in`** (`string`): Hash of the transaction received from the client. - **`txid_out`** (`string`): Hash of the transaction of the payment to you. - **`value_coin`** (`number`): Value sent by your customer to the created address. - **`value_forwarded_coin`** (`number`): Value forwarded to your wallet address, after fees. - **`confirmations`** (`integer`): Number of blockchain confirmations of the current transaction. - **`last_update`** (`string`): Time and date when this callback was last updated (UTC-0). - **`result`** (`string`): Result status of this callback. It can be one of the following options: - `pending` (transaction is being confirmed by the blockchain) - `sent` (payment forwarded to your address but webhook didn't receive valid `*ok*` response) - `done` (payment forwarded and webhook sent to your URL with valid `*ok*` response received) - **`fee_percent`** (`number`): Percentage of the fee charged by BlockBee. - **`fee_coin`** (`number`): Value of BlockBee Fee deducted from `value_coin`. - **`logs`** (`Array of objects`): Last 10 requests to your server, ordered by timestamp descending. - **`request_url`** (`string`): URL that BlockBee API tried to call with the GET parameters included. **Notes:** - If was set to POST while creating the address the only GET parameters provided in the URL, will be the ones provided by you in the `callback` parameter, while the BlockBee parameters will be in POST. - **`responses`** (`string`): Response given by your systems to our callback. - **`response_status`** (`string`): HTTP Status code provided by your system to our callback. - **`next_try`** (`string`): Datetime in UTC-0 when callback will be retried (if not `done`). - **`pending`** (`integer`): Will be `1` if it is the pending callback. - **`confirmed`** (`integer`): Will be `1` if it is the confirmed callback ## Example Response ```json { "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu", "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP", "callback_url": "https://example.com/invoice/1234?payment_id=5678", "status": "success", "notify_pending": true, "notify_confirmations": 1, "priority": "default", "callbacks": [ { "txid_in": "33f11611f863d7475eb10daada2f225f0877561cf58cdfff175e99635dfd9120", "txid_out": "5ea53d5e728bfdb56b54c0b945990b69ae1e66cec56ab24679c9a622c4695276", "value_coin": 0.1, "value_forwarded_coin": 0.1, "confirmations": 13, "last_update": "15/02/2018 21:23:42", "result": "done", "fee_percent": 1, "fee_coin": 0.02, "logs": [ { "request_url": "https://example.com/callback.php?order_id=423&nonce=KRnrAtVbbPrA21TR4yQDESnTV5xxV4jR&uuid=883d30bc-d53b-46e4-9f4d-425001a6a45d&address_in=0x672FF17DDD6f2F6b1CA8c2A9cC8D25f0950AbCc5&address_out=0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d&confirmations=84484&txid_in=0x4ac6d4f5df0803f91d5fb34d566400bb4417e98d5a515be087a9447d1f22cbbc&txid_out=0x711e26fec256b9945cee5195636772266104adc293d9013caa27752433a7effd&fee=1&value=200&value_coin=2.00011&value_forwarded=184&value_forwarded_coin=1.844926267290333679&coin=bep20_usdt&result=sent&pending=0", "responses": "*ok*", "response_status": "200", "next_try": "14/10/2022 12:47:18", "pending": "0", "confirmed": 1 } ] } ] } ``` --- # Get Payout Status > Source: https://docs.blockbee.io/api/get-payout-status > Description: Get the status of a payout by providing the payout ID. # Check Payout Status Check the status of your Payout by providing its `ID`. **Method:** `POST` **Path:** ``` https://api.blockbee.io/payout/status/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- ## Request Body This endpoint requires a request body with the `payout_id`. **Note**: The request `Content-Type` header must be set to `application/x-www-form-urlencoded`. - **`payout_id`** (`string`) (required) - Example: `{payout_id: 7f839bdd-5acd-4ce3-984d-1be8357b642d}`: The ID of the payout you want to check. --- ## Returns Returns the status information of the payout. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`payout_info`** (`object`): Contains detailed information about the payout. - **`id`** (`string`): The ID of the Payout. - **`status`** (`string`): The status of the Payout. Can be created, processing, done, rejected, or error. - **`display_status`** (`string`): The status of the Payout. Can be Created, Pending Payment, Done, Rejected, or Error. - **`from`** (`string`): The source from which the Payout was created, if applicable. - **`requests`** (`object`): A map of payout request addresses to their respective amounts. - **`total_requested`** (`string`): The total cryptocurrency amount requested for the payout. - **`total_with_fee`** (`string`): The total amount requested including the fee. - **`error`** (`string`): The error message given in case the payout status is error. **Important Note:** This parameter will only be returned if there was an error with the Payout. - **`blockchain_fee`** (`string`): The fee paid to the blockchain for the transaction. - **`fee`** (`string`): The fee associated with the payout. - **`coin`** (`string`): The cryptocurrency for the payout. - **`txid`** (`string`): The transaction ID of the Payout, if it has been processed. - **`timestamp`** (`string`): The timestamp when the Payout was created. ## Responses ### 200 The Payout was created successfully. **Content Types:** - `application/json` ### 400 Your request couldn't be processed. Retry after a short delay. ## Example Response ```json { "status": "success", "payout_info": { "id": "ddcbab52-3fbc-478c-a103-ecdc2f0ed58c", "status": "done", "display_status": "Done", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.2" }, "total_requested": "0.2", "total_with_fee": "0.201", "error": null, "blockchain_fee": "0.000024738630000000", "fee": "0.001", "coin": "bep20_usdt", "txid": "0xcc522d6b94e3f284f3f00d43729167f792419c70ec4f9143fc1bddeb04c91912", "timestamp": "10/07/2025 17:01:27" } } ``` --- # BlockBee Service Information > Source: https://docs.blockbee.io/api/get-service-info > Description: Endpoint that provides information regarding BlockBee API Service (e.g supported blockchains, cryptocurrencies and tokens). # BlockBee Service Information Endpoint that provides information regarding BlockBee API Service (e.g supported blockchains, cryptocurrencies and tokens). **Method:** `GET` **Path:** ``` https://api.blockbee.io/info/ ``` --- ## Parameters ### Query Parameters - **`prices`** (`integer`) - Example: `1`: If you want to receive also the coin prices, set to `1` to enable the prices. --- ## Returns Returns a dictionary where keys are cryptocurrency tickers (e.g., `btc`) or blockchain tickers (e.g., `avax-c`). A `fee_tiers` key is also present at the top level. - **`btc`** (`object`): This object contains details about a specific cryptocurrency. The key is the dynamic ticker of the coin. The example shown is for Bitcoin (`btc`). - **`coin`** (`string`): Human readable name of the currency. - **`logo`** (`string`): The cryptocurrency logo. Useful to display it to your users. - **`ticker`** (`string`): Ticker of the currency. - **`minimum_transaction`** (`integer`) **[DEPRECATED]**: The minimum transaction value for this currency is expressed as an integer to facilitate precision value calculations. For example, in Python: `8000 / 10 ** 8`, where 8 represents the number of decimal places for the cryptocurrency. **Important Note:** Values below this value are disregarded by BlockBee. - **`minimum_transaction_coin`** (`string`): Minimum transaction value for this currency. **Important Note:** Values below this value are disregarded by BlockBee. - **`minimum_fee`** (`integer`) **[DEPRECATED]**: Minimum fee value expressed as an integer to facilitate precision value calculations. For example, in Python: `8000 / 10 ** 8`, where 8 represents the number of decimal places for the cryptocurrency. **Important Note:** 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. - **`minimum_fee_coin`** (`string`): The minimum fee value. **Important Note:** 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`** (`string`): Fee percentage for this currency. **Notes:** You can check our fees in this page. - **`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 FIAT currencies, values are the exchange rates. A list of supported FIAT currencies can be found below. If your desired FIat currency is not on the list, contact us. - (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 **Notes:** Updated every 5 minutes from CoinMarketCap. - **`prices_updated`** (`string`): Datetime of the last price update. - **`avax-c`** (`object`): This object contains details for a specific blockchain. The key is the dynamic ticker of the blockchain. Inside, it contains objects for each token supported on that blockchain, with the token's ticker as the key. - **`avax`** (`object`): This object contains details about a specific token on the blockchain. The key is the dynamic ticker of the token. The fields within this object are identical to those in the top-level cryptocurrency object (e.g., `btc`). - **`fee_tiers`** (`object[]`): An array of objects detailing the fee structure based on volume. - **`minimum`** (`string`): The minimum USD volume for this fee tier to apply. - **`fee`** (`string`): The fee percentage for this tier. ## Example Response ```json { "btc": { "coin": "Bitcoin", "logo": "https://api.cryptapi.io/media/token_logos/btc.png", "ticker": "btc", "minimum_transaction": 8000, "minimum_transaction_coin": "0.00008000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00000263", "prices": { "USD": "113687.2123324492", "EUR": "97303.8618504321" }, "prices_updated": "2025-07-10T17:35:17.529Z" }, "avax-c": { "avax": { "coin": "AVAX", "logo": "https://api.cryptapi.io/media/token_logos/avax_avax.png", "ticker": "avax", "minimum_transaction": 10000000000000000, "minimum_transaction_coin": "0.01000000", "minimum_fee": 0, "minimum_fee_coin": "0E-8", "fee_percent": "1.000", "network_fee_estimation": "0.0002641508790732", "prices": { "USD": "19.8455617107", "EUR": "16.9856376581" }, "prices_updated": "2025-07-10T17:35:17.529Z" } }, "fee_tiers": [ { "minimum": "0.00", "fee": "1.000" }, { "minimum": "10000.00", "fee": "0.900" } ] } ``` --- # Fetch Subscription > Source: https://docs.blockbee.io/api/get-subscription > Description: This method allows you to fetch a subscription by ID. # Fetch Subscription by Token Retrieve the details of a specific subscription using its token. **Notes:** * Requires a valid API Key with access to the profile. * The token must match a subscription created under your profile. **Method:** `GET` **Path:** ``` https://api.blockbee.io/subscription/fetch/ ``` ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`token`** (`string`) (required) - Example: `I55hhRINHptLJPwsqwYNxJOKBItRiq1o`: Unique subscription token. --- ## Returns Returns the details of the specified subscription. - **`status`** (`string`): Status of the request. - **`subscription`** (`object`): Contains detailed information about the subscription. - **`token`** (`string`): Token associated with the subscription. - **`url`** (`string`): Subscription or payment link for the customer. - **`active`** (`boolean`): Indicates if the subscription is active. - **`user_id`** (`string`): User identifier in your system. - **`user_email`** (`string`): Customer e-mail. - **`end_date_ts`** (`integer`): Timestamp of the subscription's expiration (may be null). - **`payment_list`** (`object[]`): List of completed payments for the subscription. - **`token`** (`string`): Token for the specific payment. - **`value`** (`string`): The value of the payment. - **`coin`** (`string`): The cryptocurrency used for the payment. - **`duration_ts`** (`integer`): Duration in seconds. - **`received_fiat`** (`string`): FIAT amount received for the payment. - **`is_paid`** (`boolean`): `true` if the payment is paid. - **`is_pending`** (`boolean`): `true` if the payment is pending blockchain confirmation. - **`is_partial`** (`boolean`): `true` if the payment is partially paid. ## Example Response ```json { "status": "success", "subscription": { "token": "J78yEgW01HIOGZqBeqzxpXFuCwHGQgdO", "url": "https://pay.blockbee.io/subscription/J78yEgW01HIOGZqBeqzxpXFuCwHGQgdO/", "active": true, "user_id": "user_example", "user_email": "example@mail.com", "end_date_ts": 1753022709, "payment_list": [ { "token": "Wd1lggEvyy1usHooflFiEGNQbBn4TNvJ", "value": "1.99", "coin": "usd", "duration_ts": 2592000, "received_fiat": "1.99", "is_paid": true, "is_pending": false, "is_partial": false } ] } } ``` --- # Get Ticker Information > Source: https://docs.blockbee.io/api/get-ticker-info > Description: This method allows you to get information for a specific `ticker`. **Notes:** * If the `prices` parameter is sent, the prices will be included in the response. # Get Ticker Information This method allows you to get information for a specific `ticker`. **Notes:** * If the `prices` parameter is sent, the prices will be included in the response. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/info/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required) - Example: `btc`: 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. {% /endpointParameter %} ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`prices`** (`integer`) - Example: `1`: If you want to receive also the coin prices, set to `1` to enable the prices. --- ## Returns Returns information about the specified `ticker`. - **`coin`** (`string`): Human readable name of the currency. - **`logo`** (`string`): The cryptocurrency logo. Useful to display it to your users. - **`ticker`** (`string`): Ticker of the currency. - **`minimum_transaction`** (`integer`) **[DEPRECATED]**: The minimum transaction value for this currency is expressed as an integer to facilitate precision value calculations. For example, in Python: `8000 / 10 ** 8`, where 8 represents the number of decimal places for the cryptocurrency. **Important Note:** Values below this value are disregarded by BlockBee. - **`minimum_transaction_coin`** (`string`): Minimum transaction value for this currency. **Important Note:** Values below this value are disregarded by BlockBee. - **`minimum_fee`** (`integer`) **[DEPRECATED]**: Minimum fee value expressed as an integer to facilitate precision value calculations. For example, in Python: `8000 / 10 ** 8`, where 8 represents the number of decimal places for the cryptocurrency. **Important Note:** 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. - **`minimum_fee_coin`** (`string`): The minimum fee value. **Important Note:** 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. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`prices`** (`object`): Object with the exchange rate of this currency in various FIAT currencies. Keys are the names of the FIAT currencies, values are the estimated costs. In case your desired FIAT currency is not included in the list of supported currencies, contact us to request it: - (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 **Notes:** Updated every 5 minutes from CoinMarketCap. - **`prices_updated`** (`string`): Datetime of the last price update. ## Example Response ```json { "coin": "Bitcoin", "logo": "https://api.cryptapi.io/media/token_logos/btc.png", "ticker": "btc", "minimum_transaction": 8000, "minimum_transaction_coin": "0.00008000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00000213", "status": "success", "prices": { "AED": "396670.6487738357", "AUD": "164918.3815821888", "BGN": "179415.3514938429", "BRL": "590043.3174856082", "CAD": "147390.5225671536", "CHF": "85663.8443900161", "CNY": "774067.3699410238", "COP": "435055971.0023019300", "CZK": "2265202.0635145637", "DKK": "685208.4835369790", "EUR": "91836.4258114617", "GBP": "79525.4974900668", "HKD": "847743.9480314957", "HUF": "36795946.8818968000", "IDR": "1752476212.5931296000", "INR": "9252608.6186747890", "JPY": "15553782.2703022100", "LKR": "32387917.7777397400", "MXN": "2031288.3776691742", "MYR": "456712.2757241769", "NGN": "165449934.6265569600", "NOK": "1093143.9098128967", "PHP": "6089640.4634586780", "PLN": "391876.4118251008", "RON": "465157.5109953081", "RUB": "8509597.1435057820", "SEK": "1032104.0819723385", "SGD": "137643.4035211648", "THB": "3502342.6344668176", "TRY": "4296777.8167729120", "TWD": "3136159.8249985916", "UAH": "4508904.8475288930", "UGX": "388339955.9410019500", "USD": "107995.3359480198", "VND": "2825993400.1024604000", "ZAR": "1907272.4736099340" }, "prices_updated": "2025-07-02T14:15:17.955Z" } ``` --- # Get Address > Source: https://docs.blockbee.io/api/get-wallet-address > Description: Using this endpoint you can fetch the Payout Wallet address for your API Key and the `ticker` provided. # Get Self-Custodial Wallet Address Using this endpoint you can fetch the Payout Wallet address for your API Key and the `ticker` provided. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/payout/address/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. --- ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- ## Returns Returns the Payout Wallet address for the provided `ticker`. - **`status`** (`string`): Status of the request. Should be success if the request didn't fail. - **`address`** (`string`): Address of your Payout Wallet. ## Example Response ```json { "status": "success", "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589" } ``` --- # Get Self-Custodial Wallet Balance > Source: https://docs.blockbee.io/api/get-wallet-balance > Description: Using this endpoint you can fetch the Payout Wallet balance for your API Key and the `ticker` provided. # Get Balance Using this endpoint you can fetch the Payout Wallet address **balance** for your API Key and the `ticker` provided. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/payout/balance/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. --- ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- ## Returns Returns the balance of the Payout Wallet for the provided `ticker`. - **`status`** (`string`): Status of the request. Should be success if the request didn't fail. - **`balance`** (`number`): Balance of your Payout Wallet address for the selected ticker. ## Example Response ```json { "status": "success", "balance": "0.12345678" } ``` --- # List Checkout Payments > Source: https://docs.blockbee.io/api/list-checkouts > Description: List checkout payment requests for a profile. # List Checkout Payments This method allows you to list checkout payment requests for a profile. **Notes:** * Use this endpoint to retrieve a paginated history of your checkout payments. * You can filter the results by date range and payment status. **Method:** `GET` **Path:** ``` https://api.blockbee.io/checkout/list/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`from`** (`string`) - Example: `1672531200`: Start date for filtering payments as a Unix timestamp. - **`to`** (`string`) - Example: `1704067199`: End date for filtering payments as a Unix timestamp. - **`status`** (`string`) - Example: `paid`: Filter payments by their current status. **Accepted values:** * `waiting` * `paid` * `pending` * `partial` * `expired` - **`page`** (`integer`) - Example: `1`: The page number you want to retrieve. **Default:** `1` - **`per_page`** (`integer`) - Example: `25`: Number of records per page. **Default:** `25` **Maximum:** `100` --- ## Returns Returns a list of checkout payment requests matching the provided filters. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`num_pages`** (`integer`): The total number of pages available. - **`payments`** (`object[]`): A list of checkout payment objects matching the filters. - **`source`** (`string`): Source of the payment. - **`token`** (`string`): The payment token identifier. - **`value`** (`string`): The requested payment amount. - **`value_fiat`** (`string`): The requested payment amount in fiat. - **`coin`** (`string`): The cryptocurrency used or requested. - **`total_paid_coin`** (`string`): The total amount paid in cryptocurrency. - **`total_paid_fiat`** (`string`): The total amount paid in fiat. - **`payment_list`** (`object`): Details about the specific transaction. - **`is_paid`** (`boolean`): Indicates if the payment is fully paid. - **`is_pending`** (`boolean`): Indicates if the payment is pending on the blockchain. - **`is_partial`** (`boolean`): Indicates if the payment is partially paid. - **`is_expired`** (`boolean`): Indicates if the payment request has expired. - **`timestamp`** (`string`): The creation time of the payment request. ## Example Response ```json { "status": "success", "data": [ { "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "value": "10", "currency": "usd", "status": "paid", "created_at": "2023-05-15T10:00:00Z" } ] } ``` --- # List Deposit Requests > Source: https://docs.blockbee.io/api/list-deposits > Description: List deposit requests for a profile. # List Deposit Requests This method allows you to list deposit requests for an API key profile. **Notes:** * Use this endpoint to retrieve a paginated history of your generated deposit addresses. * You can filter the results by date range and whether they have received payments. **Method:** `GET` **Path:** ``` https://api.blockbee.io/deposit/list/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). **Note:** The API key can also be sent as a header named `apikey`. - **`from`** (`string`) - Example: `1672531200`: Start date for filtering deposits as a Unix timestamp. - **`to`** (`string`) - Example: `1704067199`: End date for filtering deposits as a Unix timestamp. - **`status`** (`string`) - Example: `with_payments`: Filter deposits based on payment activity. **Accepted values:** * `with_payments` (Addresses that have received funds) * `without_payments` (Addresses with no detected payments) - **`page`** (`integer`) - Example: `1`: The page number you want to retrieve. **Default:** `1` - **`per_page`** (`integer`) - Example: `25`: Number of records per page. **Default:** `25` **Maximum:** `100` --- ## Returns Returns a list of deposit request objects matching the provided filters. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`num_pages`** (`integer`): The total number of pages available. - **`deposits`** (`object[]`): A list of deposit request objects matching the filters. - **`token`** (`string`): The deposit token identifier. - **`value_fiat`** (`string`): The total fiat value of all payments received for this deposit request. - **`payment_list`** (`object[]`): A list of payments received under this deposit request. - **`txid`** (`string`): The transaction ID of the payment. - **`value`** (`string`): The amount of cryptocurrency received. - **`value_fiat`** (`string`): The fiat value of the cryptocurrency received. - **`coin`** (`string`): The cryptocurrency ticker of the payment. - **`timestamp`** (`string`): The timestamp when the payment was detected. - **`currency`** (`string`): The fiat currency associated with the deposit. - **`timestamp`** (`string`): The creation time of the deposit request. ## Example Response ```json { "status": "success", "num_pages": 1, "deposits": [ { "token": "Zz87cpYde6cKDIIwn0A6oOxea2i1eGoJ", "value_fiat": "2.999478000000000000", "payment_list": [ { "txid": "0xd9f11104a96c0d89404ed8736c7382939185b9520a23768c648ac718cf9c7885", "value": "1.000000000000000000", "value_fiat": "1.000000000000000000", "coin": "polygon_usdt", "timestamp": "2026-01-28T17:04:21.590Z" } ], "currency": "usd", "timestamp": "2025-11-24T14:13:51.101Z" } ] } ``` --- # List Payout Requests > Source: https://docs.blockbee.io/api/list-payout-requests > Description: This method allows you to list payout requests for a specific ticker. # List Payout Requests Using this endpoint you can fetch the Payout Requests created for your API Key and the `ticker` provided. **Notes:** * This endpoint is paginated and will show only `50` Payout Requests per page. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/payout/request/list/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** * The API key can also be sent as a header named `apikey`. - **`status`** (`string`) - Example: `all`: Filter by the status of the Payout Request. Possible statuses: `all`, `pending`, `rejected`, `processing`, `done` - **`p`** (`number`) - Example: `1`: Specify the `page` of the list. As this endpoint follows pagination, displaying only `50` results per page, you'll need to specify the page number to access additional results. ## Returns Returns a paginated list of payout requests. - **`status`** (`string`): Status of the response. Should be success if the operation was successful. - **`payout_requests`** (`Array of objects`): An array of payout request objects. - **`id`** (`string`): The ID of the Payout Request. - **`payout_id`** (`string`): The ID of the Payout, if a Payout was already created with this Payout Request. - **`coin`** (`string`): The cryptocurrency for the Payout Request. - **`address`** (`string`): The Payout Request destination address. - **`value`** (`string`): The amount of cryptocurrency to Payout Request. - **`status`** (`string`): The status of the Payout Request. - **`display_status`** (`string`): The status of the Payout Request. - **`timestamp`** (`string`): The timestamp when the Payout Request was made. - **`num_pages`** (`integer`): The number of pages of Payout Requests available. ## Example Response ```json { "status": "success", "payout_requests": [ { "id": "7f839bdd-5acd-4ce3-984d-1be8357b642d", "address": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP", "value": "0.001", "status": "pending", "created_at": "2024-03-12T14:40:11Z" } ] } ``` --- # List Payouts > Source: https://docs.blockbee.io/api/list-payouts > Description: Using this endpoint you can fetch the Payout created for your API Key and the `ticker` provided. **Notes:** * This endpoint will list only the **Payout**, which is an aggregation of the **Payout Requests**. * This endpoint is paginated and will show only `50` Payout Requests per page. # List Payouts Using this endpoint you can fetch the Payout created for your API Key and the `ticker` provided. **Notes:** * This endpoint will list only the **Payout**, which is an aggregation of the **Payout Requests**. * This endpoint is paginated and will show only `50` Payout Requests per page. **Method:** `GET` **Path:** ``` https://api.blockbee.io/{ticker}/payout/list/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. --- ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- - **`status`** (`string`): Filter by the status of the Payout. --- - **`p`** (`number`): Specify the `page` of the list. As this endpoint follows pagination, displaying only `50` results per page, you'll need to specify the page number to access additional results. --- ## Returns Returns a list of payouts. - **`status`** (`string`): Status of the response. Should be success if the operation was successful. - **`payouts`** (`Array of objects`): An array of payout objects. - **`id`** (`string`): The ID of the payout. - **`status`** (`string`): The status of the payout. Can be created, processing, done, rejected, or error. - **`display_status`** (`string`): The verbose status of the payout. Can be Created, Pending Payment, Done, Rejected, or Error. - **`total_requested`** (`string`): The total cryptocurrency amount requested for the payout. - **`total_requested_fiat`** (`string`): The fiat equivalent of the total amount requested, if applicable. - **`total_with_fee`** (`string`): The total amount requested including the fee. - **`total_with_fee_fiat`** (`string`): The fiat equivalent of the total amount with fee, if applicable. - **`error`** (`string`): The error message given in case the payout status is error. **Important Note:** This parameter will only be returned if there was an error with the Payout. - **`blockchain_fee`** (`string`): The fee paid to the blockchain for the transaction. - **`fee`** (`string`): The fee associated with the payout. - **`coin`** (`string`): The cryptocurrency for the payout. - **`timestamp`** (`string`): The timestamp when the payout was created. - **`num_pages`** (`integer`): The number of pages of payout requests available. ## Example Response ```json { "status": "success", "payouts": [ { "id": "ccaf7868-2219-4dad-b0f7-d6e3a362b26f", "status": "done", "display_status": "Done", "total_requested": "0.1", "total_requested_fiat": "0.1", "total_with_fee": "0.1005", "total_with_fee_fiat": "0.1", "error": null, "blockchain_fee": "0.000024738630000000", "fee": "0.0005", "coin": "bep20_usdt", "timestamp": "10/07/2025 17:03:52" } ], "num_pages": 1 } ``` --- # List Subscriptions > Source: https://docs.blockbee.io/api/list-subscriptions > Description: This method allows you to list all subscriptions. # List Subscriptions Retrieve a paginated list of all subscriptions associated with your API profile, sorted by timestamp in descending order (most recent first). **Notes:** * Returns up to 50 subscriptions per page. * Requires a valid API Key with access to the profile. * Results are automatically sorted by creation timestamp, with the newest subscriptions appearing first. * Use pagination parameters to navigate through multiple pages of results. **Method:** `GET` **Path:** ``` https://api.blockbee.io/subscription/list/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required) - Example: `your_api_key_here`: API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. - **`p`** (`integer`) - Example: `1`: Page number for pagination. Defaults to 1. --- ## Returns Returns a paginated list of subscriptions. - **`status`** (`string`): Status of the request. - **`subscriptions`** (`object[]`): List of subscriptions tied to the API profile. - **`token`** (`string`): Token associated with the subscription. - **`url`** (`string`): Subscription or payment link for the customer. - **`active`** (`boolean`): Indicates if the subscription is active. - **`user_id`** (`string`): User identifier in your system. - **`user_email`** (`string`): Customer e-mail. - **`end_date_ts`** (`integer`): Timestamp of the subscription's expiration (may be null). - **`payment_list`** (`object[]`): List of completed payments for the subscription. - **`token`** (`string`): Token for the specific payment. - **`value`** (`string`): The value of the payment. - **`coin`** (`string`): The cryptocurrency used for the payment. - **`duration_ts`** (`integer`): Duration in seconds. - **`received_fiat`** (`string`): FIAT amount received for the payment. - **`is_paid`** (`boolean`): `true` if the payment is paid. - **`is_pending`** (`boolean`): `true` if the payment is pending blockchain confirmation. - **`is_partial`** (`boolean`): `true` if the payment is partially paid. - **`num_pages`** (`integer`): Total number of pages available. ## Example Response ```json { "status": "success", "subscriptions": [ { "token": "J78yEgW01HIOGZqBeqzxpXFuCwHGQgdO", "url": "https://pay.blockbee.io/subscription/J78yEgW01HIOGZqBeqzxpXFuCwHGQgdO/", "active": true, "user_id": "user_example", "user_email": "example@mail.com", "end_date_ts": 1753022709, "payment_list": [ { "token": "Wd1lggEvyy1usHooflFiEGNQbBn4TNvJ", "value": "1.99", "coin": "usd", "duration_ts": 2592000, "received_fiat": "1.99", "is_paid": true, "is_pending": false, "is_partial": false } ] } ], "num_pages": 1 } ``` --- # List API Transactions > Source: https://docs.blockbee.io/api/list-transactions > Description: List API transactions for one specific coin or context. # List API Transactions This method allows you to list API transactions for one coin/context. **Notes:** * Use this endpoint to paginate through transactions related to a specific cryptocurrency within your API key context. * You can filter the results by date range. **Method:** `GET` **Path:** ``` https://api.blockbee.io/<ticker>/list/ ``` --- ## Parameters ### Path Parameters - **`ticker`** (`string`) (required) - Example: `btc`: 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: `https://api.blockbee.io/trc20/usdt/list/`. ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's Dashboard. **Note:** The API key can also be sent as a header named `apikey`. - **`from`** (`string`) - Example: `1672531200`: Start date for filtering transactions as a Unix timestamp. - **`to`** (`string`) - Example: `1704067199`: End date for filtering transactions as a Unix timestamp. - **`page`** (`integer`) - Example: `1`: The page number you want to retrieve. **Default:** `1` - **`per_page`** (`integer`) - Example: `25`: Number of records per page. **Default:** `25` **Maximum:** `100` --- ## Returns Returns a list of transaction objects matching the provided filters. - **`status`** (`string`): Status of the request. Should be `success` if the request didn't fail. - **`num_pages`** (`integer`): The total number of pages available. - **`transactions`** (`object[]`): A list of transaction object records matching the provided filters. - **`uuid`** (`string`): The unique identifier for the transaction. - **`address_in`** (`string`): The payment address that received the funds. - **`address_out`** (`string`): The address where the funds were forwarded to. - **`txid_in`** (`string`): The transaction ID of the incoming payment. - **`txid_out`** (`string`): The transaction ID of the outgoing/forwarded payment. - **`link_to_txid_in`** (`string`): A link to view the incoming transaction on a blockchain explorer. - **`value`** (`string`): The amount received in cryptocurrency. - **`value_forwarded`** (`string`): The amount forwarded in cryptocurrency. - **`fiat`** (`string`): The fiat value of the received amount at the time of the transaction. - **`fiat_forwarded`** (`string`): The fiat value of the forwarded amount at the time of the transaction. - **`price`** (`string`): The cryptocurrency to fiat price at the time of the transaction. - **`coin`** (`string`): The cryptocurrency used for the transaction. - **`confirmations`** (`integer`): The number of blockchain confirmations for the transaction. - **`fee`** (`string`): The fee applied to the transaction. - **`fee_percent`** (`string`): The fee percentage applied. - **`fee_deducted`** (`boolean`): Indicates whether the fee was deducted from the forwarded amount. - **`blockchain_fee`** (`string`): The blockchain network fee for the transaction. - **`result`** (`string`): The outcome of the transaction process (e.g., `done`, `sent`). - **`timestamp`** (`string`): The date and time of the transaction. ## Example Response ```json { "status": "success", "data": [ { "txid": "7b47b4d1b09b5c3e602781b0ed82052dc6...", "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "value": "0.01000000", "created_at": "2023-05-15T10:00:00Z" } ] } ``` --- # Process Payout by ID > Source: https://docs.blockbee.io/api/process-payout-by-id > Description: Process a payout by providing the payout ID. # Process Payout by ID Use this endpoint to process a specific Payout using its `ID`. **Notes:** * Will throw an error if the Payout status is already `Done`. **Method:** `POST` **Path:** ``` https://api.blockbee.io/payout/process/ ``` --- ## Parameters ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** The API key can also be sent as a header named `apikey`. --- ## Request Body This endpoint requires a request body with the `payout_id`. **Note**: The request `Content-Type` header must be set to `application/x-www-form-urlencoded`. - **`payout_id`** (`string`) (required) - Example: `{payout_id: 7f839bdd-5acd-4ce3-984d-1be8357b642d}`: The ID of the payout you want to process. --- ## Returns Returns a success message with payout information. Returns an error if the payout has already been processed or if the `payout_id` is invalid. - **`status`** (`string`): Status of the request. - **`payout_info`** (`object`): Contains detailed information about the payout request. - **`id`** (`string`): Unique identifier for the payout request. - **`status`** (`string`): Current status of the payout request. Can be created, processing, done, rejected, or error. - **`display_status`** (`string`): Current verbose status of the payout request. Can be Created, Pending Payment, Done, Rejected, or Error. - **`from`** (`string`): Source address for the payout, if applicable. - **`requests`** (`object`): A mapping of destination addresses to the amount requested for each. - **`total_requested`** (`string`): Total cryptocurrency amount requested. - **`total_with_fee`** (`string`): Total cryptocurrency amount including the fee. - **`error`** (`string`): The error message given in case the payout status is error. - **`blockchain_fee`** (`string`): The fee paid to the blockchain for the transaction. - **`fee`** (`string`): Fee associated with the transaction. - **`coin`** (`string`): Cryptocurrency ticker for the transaction. - **`txid`** (`string`): Transaction ID, available once the payout is fulfilled. - **`timestamp`** (`string`): Timestamp when the payout was created. - **`queued`** (`boolean`): Indicates whether the payout is queued for processing. ## Example Response ```json { "status": "success", "queued": true, "payout_info": { "id": "ddcbab52-3fbc-478c-a103-ecdc2f0ed58c", "status": "processing", "display_status": "Pending Payment", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.2" }, "total_requested": "0.2", "total_with_fee": "0.201", "error": null, "blockchain_fee": "0E-18", "fee": "0.001", "coin": "bep20_usdt", "txid": "", "timestamp": "10/07/2025 17:01:27" } } ``` --- # Process Bulk Payout Requests > Source: https://docs.blockbee.io/api/process-payout-requests-bulk > Description: This method allows you to process multiple payout requests in bulk for a specific ticker. # Create and Send multiple Payout Requests Use this method to efficiently generate and dispatch multiple **Payout Requests**. This process not only facilitates the creation of one or several Payout Requests but also initiates the **Payout**, ensuring the automatic transfer of funds. **Method:** `POST` **Path:** ``` https://api.blockbee.io/{ticker}/payout/request/bulk/process/ ``` ## Parameters ### Path Parameters - **`ticker`** (`string`) (required): 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: `https://api.blockbee.io/trc20/usdt/create/`. **Notes:** * You can find all our tickers in our [cryptocurrencies](https://blockbee.io/cryptocurrencies) page. * Our Payouts system does not support `doge`. ### Query Parameters - **`apikey`** (`string`) (required): API Key provided by BlockBee's [Dashboard](https://dash.blockbee.io/). Unsure how to get yours? [Check this tutorial](/kb/tutorials/dashboard/how-to-generate-a-new-api-key). **Note:** * The API key can also be sent as a header named `apikey`. ## Request Body This endpoint requires a JSON request body with the payout requests. **Note**: The request `Content-Type` header must be set to `application/json`. ```json { "outputs": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": 0.2, "0x18B211A1Ba5880C7d62C250B6441C2400d588589": 0.1 } } ``` ## Returns Returns information about the created payout and its status. - **`status`** (`string`): Status of the request. Should be success if the request didn't fail. - **`payout_info`** (`object`): An object containing detailed information about the payout. - **`id`** (`string`): Unique identifier for the payout. - **`status`** (`string`): The status of the Payout. Can be created, processing, done, rejected, or error. - **`display_status`** (`string`): The status of the Payout. Can be Created, Pending Payment, Done, Rejected, or Error. - **`from`** (`string`): Source address for the payout, if applicable. - **`requests`** (`object`): A mapping of destination addresses to the amount requested for each. - **`total_requested`** (`string`): Total cryptocurrency amount requested. - **`total_with_fee`** (`string`): Total cryptocurrency amount including the fee. - **`error`** (`string`): The error message given in case the payout status is error. **Important Note:** This parameter will only be returned if there was an error with the Payout. - **`blockchain_fee`** (`string`): The fee paid to the blockchain for the transaction. - **`fee`** (`string`): Fee associated with the transaction. - **`coin`** (`string`): Cryptocurrency ticker for the transaction. - **`txid`** (`string`): Transaction ID, available once the payout is fulfilled. - **`timestamp`** (`string`): Timestamp when the payout was created. - **`queued`** (`boolean`): Indicates whether the payout is queued for processing. ## Example Response ```json { "status": "success", "queued": true, "payout_info": { "id": "ccaf7868-2219-4dad-b0f7-d6e3a362b26f", "status": "processing", "display_status": "Pending Payment", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.1" }, "total_requested": "0.1", "total_with_fee": "0.1005", "error": null, "blockchain_fee": 0, "fee": "0.0005", "coin": "bep20_usdt", "txid": "", "timestamp": "10/07/2025 17:03:52" } } ``` --- # Checkout Deposits Webhook > Source: https://docs.blockbee.io/webhooks/checkout-deposits-webhook > Description: Real-time webhook notifications sent when deposits are completed via BlockBee's hosted deposit solution. These webhooks notify you when a customer has successfully made a deposit to your deposit link. # Checkout Deposits Webhook Real-time webhook notifications sent when deposits are completed via BlockBee's hosted deposit solution. These webhooks notify you when a customer has successfully made a deposit to your deposit link and you should credit their account. **Method:** You choose when creating the deposit link: - `GET` (default) - Webhook data sent as URL query parameters - `POST` (set `post=1`) - Webhook data sent in request body **Content-Type:** You choose when creating the deposit link: - `application/x-www-form-urlencoded` (default) - Standard form encoding - `application/json` (set `json=1`) - JSON format in request body --- ## Webhook Overview Unlike custom payment flow webhooks, checkout deposit webhooks are sent only once when the deposit is complete and confirmed. There are no separate pending and confirmed states - you receive a single notification when the deposit is ready to be processed. The webhook contains all the information you need to: - Verify the deposit was legitimate - Credit the customer's account - Store transaction details for your records - Track which user made the deposit (via custom parameters in notify_url) --- ## Webhook Fields - **`uuid`** (`string`) (required): Unique identifier for each deposit made by your clients. This can be used to track any duplicate webhooks sent, in case our system doesn't mark the webhook as successful. **Important:** You can use this unique identifier for idempotency to prevent processing duplicate webhooks. Store this UUID when processing deposits and check if it has already been processed. **Example:** `afe11bea-768b-47ae-ba0f-907379fbe5ef` - **`txid`** (`string`) (required): Transaction hash of your client's deposit. **Example:** `0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32` - **`address`** (`string`) (required): Address generated by BlockBee where your client's deposit was received. **Example:** `3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM` - **`payment_url`** (`string`) (required): Deposit link where the deposit came from. **Note:** Any query parameters you add to the notify_url (like `?user_id=12345`) will be included in the webhook payload, allowing you to track which user the deposit belongs to. **Example:** `https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N` - **`currency`** (`string`) (required): FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard. **Example:** `usd` - **`paid_amount`** (`string`) (required): Amount paid in cryptocurrency by the user. **Note:** The cryptocurrency/token used to make the payment is described in the parameter `paid_coin`. **Example:** `1.23` - **`received_amount`** (`string`) (required): Value forwarded to you, after fees deducted. **Note:** The cryptocurrency/token used to make the payment is described in the parameter `paid_coin`. **Example:** `9.24` - **`paid_amount_fiat`** (`string`) (required): Amount paid in the FIAT currency described in the parameter `currency`. **Example:** `21234.32` (represents $212.34) - **`received_amount_fiat`** (`string`) (required): Value forwarded to you, after fees deducted in the FIAT currency selected. **Note:** FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard. **Example:** `9.24` (represents $9.24) - **`paid_coin`** (`string`) (required): Cryptocurrency/token used to make the payment. **Note:** The amount paid will be available in the parameter `paid_amount`. **Format:** - Native coins: `btc`, `eth`, `ltc`, `bch`, `trx` - ERC-20 tokens: `erc20_usdt`, `erc20_usdc` - TRC-20 tokens: `trc20_usdt`, `trc20_usdc` - BEP-20 tokens: `bep20_usdt`, `bep20_usdc` - Polygon tokens: `polygon_usdt`, `polygon_usdc` **Example:** `btc` - **`exchange_rate`** (`number`) (required): Exchange rate at the time of the payment. **Example:** `20000` - **`type`** (`string`) (required): Type of the IPN. **Example:** `deposit` - **`status`** (`string`) (required): Status of the transaction. **Example:** `done` --- ## Security: Verify Webhook Signatures > **WARNING** >**Security Warning!** Always verify incoming webhook signatures. For a complete guide, see our **[Verify Webhook Signatures Guide](/webhooks/verify-webhook-signature)**. --- ## Reliability and Best Practices For important information on how BlockBee handles webhook delivery, retries, and timeouts, along with essential best practices for building a reliable webhook handler, see our main guide. **➡️ [Read the How Webhooks Overview](/webhooks)** --- ## Implementation Examples ```javascript // Express.js webhook handler app.post('/webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } // 2. Extract data from the payload const { uuid, paid_amount_fiat, paid_coin, txid, status, payment_url } = req.body; // 3. Check for duplicates using UUID if (isWebhookAlreadyProcessed(uuid)) { return res.status(200).send('*ok*'); } // 4. Verify the deposit is complete if (status !== 'done') { return res.status(200).send('*ok*'); } // 5. Extract user ID from payment URL (if you added custom parameters) const urlParams = new URLSearchParams(payment_url.split('?')[1]); const userId = urlParams.get('user_id'); // 6. Process the successful deposit // Credit user account, store transaction, etc. processSuccessfulDeposit({ userId, amount: paid_amount_fiat, coin: paid_coin, txid: txid, uuid: uuid }); // 7. Mark this webhook as processed using the UUID markWebhookAsProcessed(uuid); // Always respond to stop retries res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $uuid = $data['uuid']; $paid_amount_fiat = $data['paid_amount_fiat']; $paid_coin = $data['paid_coin']; $txid = $data['txid']; $status = $data['status']; $payment_url = $data['payment_url']; // 3. Use the uuid to prevent processing the same webhook twice if (isWebhookAlreadyProcessed($uuid)) { http_response_code(200); echo '*ok*'; exit; } // 4. Verify the deposit is complete if ($status !== 'done') { http_response_code(200); echo '*ok*'; exit; } // 5. Extract user ID from payment URL (if you added custom parameters) $urlParts = parse_url($payment_url); $userId = null; if (isset($urlParts['query'])) { parse_str($urlParts['query'], $queryParams); $userId = $queryParams['user_id'] ?? null; } // 6. Process the successful deposit // Credit user account, store transaction, etc. processSuccessfulDeposit([ 'userId' => $userId, 'amount' => $paid_amount_fiat, 'coin' => $paid_coin, 'txid' => $txid, 'uuid' => $uuid ]); // 7. Mark this webhook as processed using the UUID markWebhookAsProcessed($uuid); // Always respond to stop retries http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/webhook', methods=['POST']) def webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() uuid = data.get('uuid') paid_amount_fiat = data.get('paid_amount_fiat') paid_coin = data.get('paid_coin') txid = data.get('txid') status = data.get('status') payment_url = data.get('payment_url') # 3. Use the uuid to prevent processing the same webhook twice if is_webhook_already_processed(uuid): return '*ok*', 200 # 4. Verify the deposit is complete if status != 'done': return '*ok*', 200 # 5. Extract user ID from payment URL (if you added custom parameters) from urllib.parse import urlparse, parse_qs parsed_url = urlparse(payment_url) query_params = parse_qs(parsed_url.query) user_id = query_params.get('user_id', [None])[0] # 6. Process the successful deposit # Credit user account, store transaction, etc. process_successful_deposit({ 'user_id': user_id, 'amount': paid_amount_fiat, 'coin': paid_coin, 'txid': txid, 'uuid': uuid }) # 7. Mark this webhook as processed using the UUID mark_webhook_as_processed(uuid) # Always respond to stop retries return '*ok*', 200 ``` ```ruby # Ruby on Rails webhook handler class WebhooksController < ApplicationController skip_before_action :verify_authenticity_token def deposit # 1. Verify the webhook signature unless verify_webhook_signature(request) render plain: 'Unauthorized', status: :unauthorized return end # 2. Extract data from the payload uuid = params[:uuid] paid_amount_fiat = params[:paid_amount_fiat] paid_coin = params[:paid_coin] txid = params[:txid] status = params[:status] payment_url = params[:payment_url] # 3. Use the uuid to prevent processing the same webhook twice if webhook_already_processed?(uuid) render plain: '*ok*', status: :ok return end # 4. Verify the deposit is complete unless status == 'done' render plain: '*ok*', status: :ok return end # 5. Extract user ID from payment URL (if you added custom parameters) uri = URI(payment_url) query_params = URI.decode_www_form(uri.query || '') user_id = query_params.assoc('user_id')&.last # 6. Process the successful deposit # Credit user account, store transaction, etc. process_successful_deposit( user_id: user_id, amount: paid_amount_fiat, coin: paid_coin, txid: txid, uuid: uuid ) # 7. Mark this webhook as processed using the UUID mark_webhook_as_processed(uuid) # Always respond to stop retries render plain: '*ok*', status: :ok end end ``` ```csharp // ASP.NET Core webhook handler [ApiController] [Route("webhook")] public class WebhookController : ControllerBase { [HttpPost("deposit")] public async Task<IActionResult> DepositWebhook([FromBody] DepositWebhookPayload payload) { // 1. Verify the webhook signature if (!VerifyWebhookSignature(Request)) { return Unauthorized("Unauthorized"); } // 2. Extract data from the payload var uuid = payload.Uuid; var paidAmountFiat = payload.PaidAmountFiat; var paidCoin = payload.PaidCoin; var txid = payload.Txid; var status = payload.Status; var paymentUrl = payload.PaymentUrl; // 3. Use the uuid to prevent processing the same webhook twice if (IsWebhookAlreadyProcessed(uuid)) { return Ok("*ok*"); } // 4. Verify the deposit is complete if (status != "done") { return Ok("*ok*"); } // 5. Extract user ID from payment URL (if you added custom parameters) var uri = new Uri(paymentUrl); var queryParams = HttpUtility.ParseQueryString(uri.Query); var userId = queryParams["user_id"]; // 6. Process the successful deposit // Credit user account, store transaction, etc. await ProcessSuccessfulDeposit(new DepositData { UserId = userId, Amount = paidAmountFiat, Coin = paidCoin, Txid = txid, Uuid = uuid }); // 7. Mark this webhook as processed using the UUID MarkWebhookAsProcessed(uuid); // Always respond to stop retries return Ok("*ok*"); } } public class DepositWebhookPayload { [JsonProperty("uuid")] public string Uuid { get; set; } [JsonProperty("paid_amount_fiat")] public string PaidAmountFiat { get; set; } [JsonProperty("paid_coin")] public string PaidCoin { get; set; } [JsonProperty("txid")] public string Txid { get; set; } [JsonProperty("status")] public string Status { get; set; } [JsonProperty("payment_url")] public string PaymentUrl { get; set; } } ``` ```java // Spring Boot webhook handler @RestController @RequestMapping("/webhook") public class WebhookController { @PostMapping("/deposit") public ResponseEntity<String> depositWebhook(@RequestBody DepositWebhookPayload payload) { // 1. Verify the webhook signature if (!verifyWebhookSignature(request)) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized"); } // 2. Extract data from the payload String uuid = payload.getUuid(); String paidAmountFiat = payload.getPaidAmountFiat(); String paidCoin = payload.getPaidCoin(); String txid = payload.getTxid(); String status = payload.getStatus(); String paymentUrl = payload.getPaymentUrl(); // 3. Use the uuid to prevent processing the same webhook twice if (isWebhookAlreadyProcessed(uuid)) { return ResponseEntity.ok("*ok*"); } // 4. Verify the deposit is complete if (!"done".equals(status)) { return ResponseEntity.ok("*ok*"); } // 5. Extract user ID from payment URL (if you added custom parameters) String userId = null; try { URI uri = new URI(paymentUrl); String query = uri.getQuery(); if (query != null) { String[] pairs = query.split("&"); for (String pair : pairs) { String[] keyValue = pair.split("="); if (keyValue.length == 2 && "user_id".equals(keyValue[0])) { userId = URLDecoder.decode(keyValue[1], StandardCharsets.UTF_8); break; } } } } catch (Exception e) { log.error("Error parsing payment URL", e); } // 6. Process the successful deposit // Credit user account, store transaction, etc. processSuccessfulDeposit(new DepositData(userId, paidAmountFiat, paidCoin, txid, uuid)); // 7. Mark this webhook as processed using the UUID markWebhookAsProcessed(uuid); // Always respond to stop retries return ResponseEntity.ok("*ok*"); } } public class DepositWebhookPayload { private String uuid; private String paidAmountFiat; private String paidCoin; private String txid; private String status; private String paymentUrl; // Getters and setters public String getUuid() { return uuid; } public void setUuid(String uuid) { this.uuid = uuid; } public String getPaidAmountFiat() { return paidAmountFiat; } public void setPaidAmountFiat(String paidAmountFiat) { this.paidAmountFiat = paidAmountFiat; } public String getPaidCoin() { return paidCoin; } public void setPaidCoin(String paidCoin) { this.paidCoin = paidCoin; } public String getTxid() { return txid; } public void setTxid(String txid) { this.txid = txid; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } public String getPaymentUrl() { return paymentUrl; } public void setPaymentUrl(String paymentUrl) { this.paymentUrl = paymentUrl; } } ``` ```go // Go webhook handler package main import ( "encoding/json" "log" "net/http" "net/url" "strings" ) type DepositWebhookPayload struct { Uuid string `json:"uuid"` PaidAmountFiat string `json:"paid_amount_fiat"` PaidCoin string `json:"paid_coin"` Txid string `json:"txid"` Status string `json:"status"` PaymentURL string `json:"payment_url"` } func depositWebhookHandler(w http.ResponseWriter, r *http.Request) { // 1. Verify the webhook signature if !verifyWebhookSignature(r) { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // 2. Extract data from the payload var payload DepositWebhookPayload if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3. Use the uuid to prevent processing the same webhook twice if isWebhookAlreadyProcessed(payload.Uuid) { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 4. Verify the deposit is complete if payload.Status != "done" { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 5. Extract user ID from payment URL (if you added custom parameters) userId := "" if parsedURL, err := url.Parse(payload.PaymentURL); err == nil { if queryParams := parsedURL.Query(); queryParams != nil { userId = queryParams.Get("user_id") } } // 6. Process the successful deposit // Credit user account, store transaction, etc. processSuccessfulDeposit(DepositData{ UserID: userId, Amount: payload.PaidAmountFiat, Coin: payload.PaidCoin, Txid: payload.Txid, Uuid: payload.Uuid, }) // 7. Mark this webhook as processed using the UUID markWebhookAsProcessed(payload.Uuid) // Always respond to stop retries w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) } type DepositData struct { UserID string Amount string Coin string Txid string Uuid string } ``` ```bash # Test webhook with curl (for development/testing) curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -d '{ "uuid": "afe11bea-768b-47ae-ba0f-907379fbe5ef", "paid_amount_fiat": "21234.32", "paid_coin": "btc", "txid": "0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32", "status": "done", "payment_url": "https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N?user_id=12345" }' # Expected response: *ok* ``` ### Key Security Checks 1. **Verify Webhook Signature** - Ensure the request is from BlockBee 2. **Check Deposit Status** - Only process when `status=done` 3. **Validate UUID** - Use the UUID for idempotency to prevent duplicate processing 4. **Extract User ID** - Use the `payment_url` to get your user identifier (if you added custom parameters) ### Best Practices - **Idempotency:** Use the `uuid` to ensure you only process each deposit once - **Respond Quickly:** Always respond with `*ok*` and a `200` status code - **Asynchronous Processing:** Handle long-running tasks in background jobs - **Error Handling:** Log errors but don't fail the webhook response - **Validation:** Verify all critical fields before processing the deposit ## Webhook Payload Example ```json { "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "payment_url": "https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "uuid": "afe11bea-768b-47ae-ba0f-907379fbe5ef", "txid": "0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32", "address": "3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM", "currency": "usd", "paid_amount": "1.23", "received_amount": "9.24", "paid_amount_fiat": "21234.32", "received_amount_fiat": "9.24", "paid_coin": "btc", "exchange_rate": 20000, "type": "deposit", "customer_name": "John Doe", "customer_email": "example@mail.com", "status": "done" } ``` --- # Checkout Payments Webhook > Source: https://docs.blockbee.io/webhooks/checkout-payments-webhook > Description: Real-time webhook notifications sent when payments are completed via BlockBee's hosted checkout solution. These webhooks notify you when a customer has successfully paid for their order. # Checkout Payments Webhook Real-time webhook notifications sent when payments are completed via BlockBee's hosted checkout solution. These webhooks notify you when a customer has successfully paid for their order and you should fulfill the purchase. **Method:** You choose when creating the payment: - `GET` (default) - Webhook data sent as URL query parameters - `POST` (set `post=1`) - Webhook data sent in request body **Content-Type:** You choose when creating the payment: - `application/x-www-form-urlencoded` (default) - Standard form encoding - `application/json` (set `json=1`) - JSON format in request body --- ## Webhook Overview Unlike custom payment flow webhooks, checkout payment webhooks are sent only once when the payment is complete and confirmed. There are no separate pending and confirmed states - you receive a single notification when the payment is ready to be processed. The webhook contains all the information you need to: - Verify the payment was legitimate - Update your order status - Fulfill the customer's purchase - Store transaction details for your records --- ## Webhook Fields - **`payment_url`** (`string`) (required): Payment link where the payment came from. **Example:** `https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N` - **`redirect_url`** (`string`) (required): Redirect URL provided when requesting a new payment link. **Note:** Any query parameters you add to this URL (like `?order_id=12345`) will be included in the webhook payload, allowing you to track which order the payment belongs to. **Example:** `https://example.com/success/?order_id=12345` - **`value`** (`number`) (required): Amount in FIAT you requested when creating the payment link. **Example:** `20000` (represents $200.00 in cents) - **`payment_id`** (`string`) (required): Unique identifier for the payment that can be used to track and identify the transaction. **Important:** You can use this unique identifier for idempotency to prevent processing duplicate webhooks. Store this ID when creating the payment and verify it matches in the webhook to ensure you're processing the correct transaction. **Example:** `fG78jtx96ugjtu0eIbeLmFB9z0feJf9N` - **`currency`** (`string`) (required): FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard. **Example:** `usd` - **`is_paid`** (`string`) (required): Should always be `1` for completed payments. **Example:** `1` - **`paid_amount`** (`string`) (required): Amount paid in cryptocurrency by the user. **Note:** The cryptocurrency/token used to make the payment is described in the parameter `paid_coin`. **Example:** `1.23` - **`paid_amount_fiat`** (`string`) (required): Amount paid in the FIAT currency described in the parameter `currency`. **Example:** `21234.32` (represents $212.34) - **`received_amount`** (`string`) (required): Value forwarded to you, after fees deducted. **Note:** The cryptocurrency/token used to make the payment is described in the parameter `paid_coin`. **Example:** `9.24` - **`received_amount_fiat`** (`string`) (required): Value forwarded to you, after fees deducted in the FIAT currency selected. **Note:** FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard. **Example:** `9.24` (represents $9.24) - **`paid_coin`** (`string`) (required): Cryptocurrency/token used to make the payment. **Note:** The amount paid will be available in the parameter `paid_amount`. **Format:** - Native coins: `btc`, `eth`, `ltc`, `bch`, `trx` - ERC-20 tokens: `erc20_usdt`, `erc20_usdc` - TRC-20 tokens: `trc20_usdt`, `trc20_usdc` - BEP-20 tokens: `bep20_usdt`, `bep20_usdc` - Polygon tokens: `polygon_usdt`, `polygon_usdc` **Example:** `btc` - **`exchange_rate`** (`number`) (required): Exchange rate at the time of the payment. **Example:** `20000` - **`txid`** (`string`) (required): Transaction hash(es) of your client's payment(s). **Note:** If multiple, it means your customer had to make multiple transactions to fulfill the payment, since the Checkout page supports partial payments. **Example:** `0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32,0x6e8b278e3db1948d2c694b7f709dd4e864ae80d516970ebfd05a98629b6efe15` - **`address`** (`string`) (required): Address generated by BlockBee where your client's payment was received. **Example:** `3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM` - **`type`** (`string`) (required): Type of the IPN. **Example:** `payment` - **`status`** (`string`) (required): Status of the transaction. **Example:** `done` --- ## Security: Verify Webhook Signatures > **WARNING** >**Security Warning!** Always verify incoming webhook signatures. For a complete guide, see our **[Verify Webhook Signatures Guide](/webhooks/verify-webhook-signature)**. --- ## Reliability and Best Practices For important information on how BlockBee handles webhook delivery, retries, and timeouts, along with essential best practices for building a reliable webhook handler, see our main guide. **➡️ [Read the Webhooks Overview](/webhooks)** --- ## Implementation Examples ```javascript // Express.js webhook handler app.post('/webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } // 2. Extract data from the payload const { is_paid, payment_id, value, paid_amount_fiat, paid_coin, txid, status, redirect_url } = req.body; // 3. Check for duplicates using payment_id if (isWebhookAlreadyProcessed(payment_id)) { return res.status(200).send('*ok*'); } // 4. Verify the payment is complete if (is_paid !== '1' || status !== 'done') { return res.status(200).send('*ok*'); } // 5. Verify the payment ID matches your records if (!verifyPaymentId(payment_id)) { console.error('Invalid payment ID received'); return res.status(200).send('*ok*'); } // 6. Extract order ID from redirect URL const urlParams = new URLSearchParams(redirect_url.split('?')[1]); const orderId = urlParams.get('order_id'); // 7. Process the successful payment // Update order status, fulfill purchase, etc. processSuccessfulPayment({ orderId, amount: paid_amount_fiat, coin: paid_coin, txid: txid }); // 8. Mark this webhook as processed using the payment_id markWebhookAsProcessed(payment_id); // Always respond to stop retries res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $is_paid = $data['is_paid']; $payment_id = $data['payment_id']; $value = $data['value']; $paid_amount_fiat = $data['paid_amount_fiat']; $paid_coin = $data['paid_coin']; $txid = $data['txid']; $status = $data['status']; $redirect_url = $data['redirect_url']; // 3. Use the payment_id to prevent processing the same webhook twice if (isWebhookAlreadyProcessed($payment_id)) { http_response_code(200); echo '*ok*'; exit; } // 4. Verify the payment is complete if ($is_paid !== '1' || $status !== 'done') { http_response_code(200); echo '*ok*'; exit; } // 5. Verify the payment ID matches your records if (!verifyPaymentId($payment_id)) { error_log('Invalid payment ID received'); http_response_code(200); echo '*ok*'; exit; } // 6. Extract order ID from redirect URL $urlParts = parse_url($redirect_url); $orderId = null; if (isset($urlParts['query'])) { parse_str($urlParts['query'], $queryParams); $orderId = $queryParams['order_id'] ?? null; } // 7. Process the successful payment // Update order status, fulfill purchase, etc. processSuccessfulPayment([ 'orderId' => $orderId, 'amount' => $paid_amount_fiat, 'coin' => $paid_coin, 'txid' => $txid ]); // 8. Mark this webhook as processed using the payment_id markWebhookAsProcessed($payment_id); // Always respond to stop retries http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/webhook', methods=['POST']) def webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() is_paid = data.get('is_paid') payment_id = data.get('payment_id') value = data.get('value') paid_amount_fiat = data.get('paid_amount_fiat') paid_coin = data.get('paid_coin') txid = data.get('txid') status = data.get('status') redirect_url = data.get('redirect_url') # 3. Use the payment_id to prevent processing the same webhook twice if is_webhook_already_processed(payment_id): return '*ok*', 200 # 4. Verify the payment is complete if is_paid != '1' or status != 'done': return '*ok*', 200 # 5. Verify the payment ID matches your records if not verify_payment_id(payment_id): print('Invalid payment ID received') return '*ok*', 200 # 6. Extract order ID from redirect URL from urllib.parse import urlparse, parse_qs parsed_url = urlparse(redirect_url) query_params = parse_qs(parsed_url.query) order_id = query_params.get('order_id', [None])[0] # 7. Process the successful payment # Update order status, fulfill purchase, etc. process_successful_payment({ 'order_id': order_id, 'amount': paid_amount_fiat, 'coin': paid_coin, 'txid': txid }) # 8. Mark this webhook as processed using the payment_id mark_webhook_as_processed(payment_id) # Always respond to stop retries return '*ok*', 200 ``` ```ruby # Ruby on Rails webhook handler class WebhooksController < ApplicationController skip_before_action :verify_authenticity_token def payment # 1. Verify the webhook signature unless verify_webhook_signature(request) render plain: 'Unauthorized', status: :unauthorized return end # 2. Extract data from the payload is_paid = params[:is_paid] payment_id = params[:payment_id] value = params[:value] paid_amount_fiat = params[:paid_amount_fiat] paid_coin = params[:paid_coin] txid = params[:txid] status = params[:status] redirect_url = params[:redirect_url] # 3. Use the payment_id to prevent processing the same webhook twice if webhook_already_processed?(payment_id) render plain: '*ok*', status: :ok return end # 4. Verify the payment is complete unless is_paid == '1' && status == 'done' render plain: '*ok*', status: :ok return end # 5. Verify the payment ID matches your records unless verify_payment_id(payment_id) Rails.logger.error 'Invalid payment ID received' render plain: '*ok*', status: :ok return end # 6. Extract order ID from redirect URL uri = URI(redirect_url) query_params = URI.decode_www_form(uri.query || '') order_id = query_params.assoc('order_id')&.last # 7. Process the successful payment # Update order status, fulfill purchase, etc. process_successful_payment( order_id: order_id, amount: paid_amount_fiat, coin: paid_coin, txid: txid ) # 8. Mark this webhook as processed using the payment_id mark_webhook_as_processed(payment_id) # Always respond to stop retries render plain: '*ok*', status: :ok end end ``` ```csharp // ASP.NET Core webhook handler [ApiController] [Route("webhook")] public class WebhookController : ControllerBase { [HttpPost("payment")] public async Task<IActionResult> PaymentWebhook([FromBody] PaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!VerifyWebhookSignature(Request)) { return Unauthorized("Unauthorized"); } // 2. Extract data from the payload var isPaid = payload.IsPaid; var paymentId = payload.PaymentId; var value = payload.Value; var paidAmountFiat = payload.PaidAmountFiat; var paidCoin = payload.PaidCoin; var txid = payload.Txid; var status = payload.Status; var redirectUrl = payload.RedirectUrl; // 3. Use the payment_id to prevent processing the same webhook twice if (IsWebhookAlreadyProcessed(paymentId)) { return Ok("*ok*"); } // 4. Verify the payment is complete if (isPaid != "1" || status != "done") { return Ok("*ok*"); } // 5. Verify the payment ID matches your records if (!VerifyPaymentId(paymentId)) { _logger.LogError("Invalid payment ID received"); return Ok("*ok*"); } // 6. Extract order ID from redirect URL var uri = new Uri(redirectUrl); var queryParams = HttpUtility.ParseQueryString(uri.Query); var orderId = queryParams["order_id"]; // 7. Process the successful payment // Update order status, fulfill purchase, etc. await ProcessSuccessfulPayment(new PaymentData { OrderId = orderId, Amount = paidAmountFiat, Coin = paidCoin, Txid = txid }); // 8. Mark this webhook as processed using the payment_id MarkWebhookAsProcessed(paymentId); // Always respond to stop retries return Ok("*ok*"); } } public class PaymentWebhookPayload { [JsonProperty("is_paid")] public string IsPaid { get; set; } [JsonProperty("payment_id")] public string PaymentId { get; set; } [JsonProperty("value")] public int Value { get; set; } [JsonProperty("paid_amount_fiat")] public string PaidAmountFiat { get; set; } [JsonProperty("paid_coin")] public string PaidCoin { get; set; } [JsonProperty("txid")] public string Txid { get; set; } [JsonProperty("status")] public string Status { get; set; } [JsonProperty("redirect_url")] public string RedirectUrl { get; set; } } ``` ```java // Spring Boot webhook handler @RestController @RequestMapping("/webhook") public class WebhookController { @PostMapping("/payment") public ResponseEntity<String> paymentWebhook(@RequestBody PaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!verifyWebhookSignature(request)) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized"); } // 2. Extract data from the payload String isPaid = payload.getIsPaid(); String paymentId = payload.getPaymentId(); Integer value = payload.getValue(); String paidAmountFiat = payload.getPaidAmountFiat(); String paidCoin = payload.getPaidCoin(); String txid = payload.getTxid(); String status = payload.getStatus(); String redirectUrl = payload.getRedirectUrl(); // 3. Use the payment_id to prevent processing the same webhook twice if (isWebhookAlreadyProcessed(paymentId)) { return ResponseEntity.ok("*ok*"); } // 4. Verify the payment is complete if (!"1".equals(isPaid) || !"done".equals(status)) { return ResponseEntity.ok("*ok*"); } // 5. Verify the payment ID matches your records if (!verifyPaymentId(paymentId)) { log.error("Invalid payment ID received"); return ResponseEntity.ok("*ok*"); } // 6. Extract order ID from redirect URL String orderId = null; try { URI uri = new URI(redirectUrl); String query = uri.getQuery(); if (query != null) { String[] pairs = query.split("&"); for (String pair : pairs) { String[] keyValue = pair.split("="); if (keyValue.length == 2 && "order_id".equals(keyValue[0])) { orderId = URLDecoder.decode(keyValue[1], StandardCharsets.UTF_8); break; } } } } catch (Exception e) { log.error("Error parsing redirect URL", e); } // 7. Process the successful payment // Update order status, fulfill purchase, etc. processSuccessfulPayment(new PaymentData(orderId, paidAmountFiat, paidCoin, txid)); // 8. Mark this webhook as processed using the payment_id markWebhookAsProcessed(paymentId); // Always respond to stop retries return ResponseEntity.ok("*ok*"); } } public class PaymentWebhookPayload { private String isPaid; private String paymentId; private Integer value; private String paidAmountFiat; private String paidCoin; private String txid; private String status; private String redirectUrl; // Getters and setters public String getIsPaid() { return isPaid; } public void setIsPaid(String isPaid) { this.isPaid = isPaid; } public String getPaymentId() { return paymentId; } public void setPaymentId(String paymentId) { this.paymentId = paymentId; } public Integer getValue() { return value; } public void setValue(Integer value) { this.value = value; } public String getPaidAmountFiat() { return paidAmountFiat; } public void setPaidAmountFiat(String paidAmountFiat) { this.paidAmountFiat = paidAmountFiat; } public String getPaidCoin() { return paidCoin; } public void setPaidCoin(String paidCoin) { this.paidCoin = paidCoin; } public String getTxid() { return txid; } public void setTxid(String txid) { this.txid = txid; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } public String getRedirectUrl() { return redirectUrl; } public void setRedirectUrl(String redirectUrl) { this.redirectUrl = redirectUrl; } } ``` ```go // Go webhook handler package main import ( "encoding/json" "log" "net/http" "net/url" "strconv" ) type PaymentWebhookPayload struct { IsPaid string `json:"is_paid"` PaymentID string `json:"payment_id"` Value int `json:"value"` PaidAmountFiat string `json:"paid_amount_fiat"` PaidCoin string `json:"paid_coin"` Txid string `json:"txid"` Status string `json:"status"` RedirectURL string `json:"redirect_url"` } func paymentWebhookHandler(w http.ResponseWriter, r *http.Request) { // 1. Verify the webhook signature if !verifyWebhookSignature(r) { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // 2. Extract data from the payload var payload PaymentWebhookPayload if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3. Use the payment_id to prevent processing the same webhook twice if isWebhookAlreadyProcessed(payload.PaymentID) { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 4. Verify the payment is complete if payload.IsPaid != "1" || payload.Status != "done" { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 5. Verify the payment ID matches your records if !verifyPaymentID(payload.PaymentID) { log.Printf("Invalid payment ID received: %s", payload.PaymentID) w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 6. Extract order ID from redirect URL orderID := "" if parsedURL, err := url.Parse(payload.RedirectURL); err == nil { if queryParams := parsedURL.Query(); queryParams != nil { orderID = queryParams.Get("order_id") } } // 7. Process the successful payment // Update order status, fulfill purchase, etc. processSuccessfulPayment(PaymentData{ OrderID: orderID, Amount: payload.PaidAmountFiat, Coin: payload.PaidCoin, Txid: payload.Txid, }) // 8. Mark this webhook as processed using the payment_id markWebhookAsProcessed(payload.PaymentID) // Always respond to stop retries w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) } type PaymentData struct { OrderID string Amount string Coin string Txid string } ``` ```bash # Test webhook with curl (for development/testing) curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -d '{ "is_paid": "1", "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "value": 20000, "paid_amount_fiat": "21234.32", "paid_coin": "btc", "txid": "0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32", "status": "done", "redirect_url": "https://example.com/success/?order_id=12345" }' # Expected response: *ok* ``` ### Key Security Checks 1. **Verify Webhook Signature** - Ensure the request is from BlockBee 2. **Check Payment Status** - Only process when `is_paid=1` and `status=done` 3. **Validate Payment ID** - Match against your stored payment ID to ensure you're processing the correct transaction 4. **Extract Order ID** - Use the `redirect_url` to get your order identifier ### Best Practices - **Idempotency:** Use the `payment_id` to ensure you only process each payment once - **Respond Quickly:** Always respond with `*ok*` and a `200` status code - **Asynchronous Processing:** Handle long-running tasks in background jobs - **Error Handling:** Log errors but don't fail the webhook response - **Validation:** Verify all critical fields before processing the payment ## Webhook Payload Example ```json { "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "payment_url": "https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N", "redirect_url": "https://example.com/success/?order_id=12345", "value": 20000, "currency": "usd", "is_paid": "1", "paid_amount": "1.23", "paid_amount_fiat": "21234.32", "received_amount": "9.24", "received_amount_fiat": "9.24", "paid_coin": "btc", "exchange_rate": 20000, "txid": "0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32,0x6e8b278e3db1948d2c694b7f709dd4e864ae80d516970ebfd05a98629b6efe15", "address": "3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM", "type": "payment", "customer_name": "John Doe", "customer_email": "example@mail.com", "status": "done" } ``` --- # Custom Payment Flow Webhooks > Source: https://docs.blockbee.io/webhooks/custom-payment-flow-webhooks > Description: Real-time webhook notifications sent when payments are received via custom payment flow. BlockBee sends two types of webhooks: pending (payment detected) and confirmed (payment verified). # Custom Payment Flow Webhooks Real-time webhook notifications sent when payments are received via custom payment flow. BlockBee sends two types of webhooks: **pending** (payment detected in mempool) and **confirmed** (payment verified by blockchain). **Method:** You choose when creating the payment: - `GET` (default) - Webhook data sent as URL query parameters - `POST` (set `post=1`) - Webhook data sent in request body **Content-Type:** You choose when creating the payment: - `application/x-www-form-urlencoded` (default) - Standard form encoding - `application/json` (set `json=1`) - JSON format in request body --- ## Tracking Payments with Custom Parameters > **INFO: Important: Add Custom Parameters to Your Webhook URL** >When creating custom payment flow payments, always add your own query parameters to the `notify_url` to track which order or user the payment belongs to. For example, adding `?order_id=123` or `?user_id=456` will ensure that these parameters are included in the webhook payload. > > This is the recommended way to link a BlockBee payment to a specific order or user in your system. --- ## Webhook Types ### Pending Webhook Sent when a payment is detected in the blockchain mempool but not yet confirmed. Particularly useful for slower blockchains (Bitcoin, Litecoin, Bitcoin Cash) to provide immediate user feedback. ### Confirmed Webhook Sent when a payment receives the specified number of confirmations. The transaction is considered final and funds are forwarded to your address. --- ## Webhook Fields ### Common Fields (Both Pending & Confirmed) These fields are included in both pending and confirmed webhooks: - **`uuid`** (`string`) (required): Unique identifier for each payment transaction. Use this to prevent processing duplicate webhooks. **Important:** Always store and check this UUID in your database before processing any payment to avoid duplicates. - **`address_in`** (`string`) (required): BlockBee-generated payment address where your customer sent the payment. - **`address_out`** (`string`) (required): Your destination address(es) where BlockBee forwards the payment. **Format:** - Single address: `1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP` - Multiple addresses: `{1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30}` - **`txid_in`** (`string`) (required): Transaction hash of your customer's payment on the blockchain. - **`coin`** (`string`) (required): Cryptocurrency ticker used for the payment. **Format:** - Native coins: `btc`, `eth`, `ltc`, `bch`, `trx` - ERC-20 tokens: `erc20_usdt`, `erc20_usdc` - TRC-20 tokens: `trc20_usdt`, `trc20_usdc` - BEP-20 tokens: `bep20_usdt`, `bep20_usdc` - Polygon tokens: `polygon_usdt`, `polygon_usdc` - **`price`** (`number`) (required): Cryptocurrency price in USD at the time the webhook was sent. - **`pending`** (`integer`) (required): Indicates webhook type: - `1` = Pending webhook (payment detected, not confirmed) - `0` = Confirmed webhook (payment verified and forwarded) ### Confirmed Webhook Only Fields These additional fields are only included in confirmed webhooks (`pending=0`): - **`txid_out`** (`string`) (required): Transaction hash of BlockBee's forwarding transaction to your address(es). - **`confirmations`** (`integer`) (required): Number of blockchain confirmations the transaction has received. - **`value_coin`** (`number`) (required): Payment amount sent by your customer before any fees are deducted. **Note:** For the amount after fees, use `value_forwarded_coin` - **`value_coin_convert`** (`string`): JSON-encoded object with FIAT currency conversions of `value_coin`. **Availability:** Only when `convert=1` was set during payment creation **Format:** `{"USD": "3.20", "EUR": "3.05", "GBP": "2.62", "CAD": "4.16", ...}` - **`value_forwarded_coin`** (`number`) (required): Amount forwarded to your address after BlockBee fees are deducted. - **`value_forwarded_coin_convert`** (`string`): JSON-encoded object with FIAT currency conversions of `value_forwarded_coin`. **Note:** Only present when `convert=1` was set during payment creation **Format:** `{"USD": "3.17", "EUR": "3.01", "GBP": "2.59", "CAD": "4.12", ...}` - **`fee_coin`** (`number`) (required): BlockBee service fee deducted from the `value_coin` amount. --- ## Security: Verify Webhook Signatures > **WARNING** >**Security Warning!** Always verify incoming webhook signatures. For a complete guide, see our **[Verify Webhook Signatures Guide](/webhooks/verify-webhook-signature)**. --- ## Reliability and Best Practices For important information on how BlockBee handles webhook delivery, retries, and timeouts, along with essential best practices for building a reliable webhook handler, see our main guide. **➡️ [Read the How Webhooks Work Guide](/webhooks/)** --- ## Implementation Examples ```javascript // Express.js webhook handler app.post('/webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } // 2. Extract data from the payload const { uuid, pending, value_coin, coin, order_id, user_id } = req.body; // Note: order_id and user_id come from custom parameters you added to notify_url // 3. Check for duplicates using UUID if (isWebhookAlreadyProcessed(uuid)) { return res.status(200).send('*ok*'); } // 4. Handle based on webhook type if (pending === 1) { // Handle pending payment notifyUser(user_id, 'Payment detected, awaiting confirmation...'); } else if (pending === 0) { // Handle confirmed payment processSuccessfulPayment({ uuid, value_coin, coin, orderId: order_id, userId: user_id }); } // 5. Mark this webhook as processed using the UUID markWebhookAsProcessed(uuid); // Always respond to stop retries res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $uuid = $data['uuid']; $pending = $data['pending']; $value_coin = $data['value_coin']; $coin = $data['coin']; $order_id = $data['order_id']; // This comes from the custom parameter you added to notify_url $user_id = $data['user_id']; // This comes from the custom parameter you added to notify_url // 3. Use the uuid to prevent processing the same webhook twice if (isWebhookAlreadyProcessed($uuid)) { http_response_code(200); echo '*ok*'; exit; } // 4. Handle based on webhook type if ($pending == 1) { // Handle pending payment notifyUser($user_id, 'Payment detected, awaiting confirmation...'); } else if ($pending == 0) { // Handle confirmed payment processSuccessfulPayment([ 'uuid' => $uuid, 'value_coin' => $value_coin, 'coin' => $coin, 'orderId' => $order_id, 'userId' => $user_id ]); } // 5. Mark this webhook as processed using the UUID markWebhookAsProcessed($uuid); // Always respond to stop retries http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/webhook', methods=['POST']) def webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() uuid = data.get('uuid') pending = data.get('pending') value_coin = data.get('value_coin') coin = data.get('coin') order_id = data.get('order_id') # This comes from the custom parameter you added to notify_url user_id = data.get('user_id') # This comes from the custom parameter you added to notify_url # 3. Use the uuid to prevent processing the same webhook twice if is_webhook_already_processed(uuid): return '*ok*', 200 # 4. Handle based on webhook type if pending == 1: # Handle pending payment notify_user(user_id, 'Payment detected, awaiting confirmation...') elif pending == 0: # Handle confirmed payment process_successful_payment({ 'uuid': uuid, 'value_coin': value_coin, 'coin': coin, 'order_id': order_id, 'user_id': user_id }) # 5. Mark this webhook as processed using the UUID mark_webhook_as_processed(uuid) # Always respond to stop retries return '*ok*', 200 ``` ```ruby # Ruby on Rails webhook handler class WebhooksController < ApplicationController skip_before_action :verify_authenticity_token def payment # 1. Verify the webhook signature unless verify_webhook_signature(request) render plain: 'Unauthorized', status: :unauthorized return end # 2. Extract data from the payload uuid = params[:uuid] pending = params[:pending] value_coin = params[:value_coin] coin = params[:coin] order_id = params[:order_id] # This comes from the custom parameter you added to notify_url user_id = params[:user_id] # This comes from the custom parameter you added to notify_url # 3. Use the uuid to prevent processing the same webhook twice if webhook_already_processed?(uuid) render plain: '*ok*', status: :ok return end # 4. Handle based on webhook type if pending == 1 # Handle pending payment notify_user(user_id, 'Payment detected, awaiting confirmation...') elsif pending == 0 # Handle confirmed payment process_successful_payment( uuid: uuid, value_coin: value_coin, coin: coin, order_id: order_id, user_id: user_id ) end # 5. Mark this webhook as processed using the UUID mark_webhook_as_processed(uuid) # Always respond to stop retries render plain: '*ok*', status: :ok end end ``` ```csharp // ASP.NET Core webhook handler [ApiController] [Route("webhook")] public class WebhookController : ControllerBase { [HttpPost("payment")] public async Task<IActionResult> PaymentWebhook([FromBody] CustomPaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!VerifyWebhookSignature(Request)) { return Unauthorized("Unauthorized"); } // 2. Extract data from the payload var uuid = payload.Uuid; var pending = payload.Pending; var valueCoin = payload.ValueCoin; var coin = payload.Coin; var orderId = payload.OrderId; // This comes from the custom parameter you added to notify_url var userId = payload.UserId; // This comes from the custom parameter you added to notify_url // 3. Use the uuid to prevent processing the same webhook twice if (IsWebhookAlreadyProcessed(uuid)) { return Ok("*ok*"); } // 4. Handle based on webhook type if (pending == 1) { // Handle pending payment await NotifyUser(userId, "Payment detected, awaiting confirmation..."); } else if (pending == 0) { // Handle confirmed payment await ProcessSuccessfulPayment(new PaymentData { Uuid = uuid, ValueCoin = valueCoin, Coin = coin, OrderId = orderId, UserId = userId }); } // 5. Mark this webhook as processed using the UUID MarkWebhookAsProcessed(uuid); // Always respond to stop retries return Ok("*ok*"); } } public class CustomPaymentWebhookPayload { [JsonProperty("uuid")] public string Uuid { get; set; } [JsonProperty("pending")] public int Pending { get; set; } [JsonProperty("value_coin")] public decimal ValueCoin { get; set; } [JsonProperty("coin")] public string Coin { get; set; } [JsonProperty("order_id")] public string OrderId { get; set; } [JsonProperty("user_id")] public string UserId { get; set; } } ``` ```java // Spring Boot webhook handler @RestController @RequestMapping("/webhook") public class WebhookController { @PostMapping("/payment") public ResponseEntity<String> paymentWebhook(@RequestBody CustomPaymentWebhookPayload payload) { // 1. Verify the webhook signature if (!verifyWebhookSignature(request)) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized"); } // 2. Extract data from the payload String uuid = payload.getUuid(); Integer pending = payload.getPending(); BigDecimal valueCoin = payload.getValueCoin(); String coin = payload.getCoin(); String orderId = payload.getOrderId(); // This comes from the custom parameter you added to notify_url String userId = payload.getUserId(); // This comes from the custom parameter you added to notify_url // 3. Use the uuid to prevent processing the same webhook twice if (isWebhookAlreadyProcessed(uuid)) { return ResponseEntity.ok("*ok*"); } // 4. Handle based on webhook type if (pending == 1) { // Handle pending payment notifyUser(userId, "Payment detected, awaiting confirmation..."); } else if (pending == 0) { // Handle confirmed payment processSuccessfulPayment(new PaymentData(uuid, valueCoin, coin, orderId, userId)); } // 5. Mark this webhook as processed using the UUID markWebhookAsProcessed(uuid); // Always respond to stop retries return ResponseEntity.ok("*ok*"); } } public class CustomPaymentWebhookPayload { private String uuid; private Integer pending; private BigDecimal valueCoin; private String coin; private String orderId; private String userId; // Getters and setters public String getUuid() { return uuid; } public void setUuid(String uuid) { this.uuid = uuid; } public Integer getPending() { return pending; } public void setPending(Integer pending) { this.pending = pending; } public BigDecimal getValueCoin() { return valueCoin; } public void setValueCoin(BigDecimal valueCoin) { this.valueCoin = valueCoin; } public String getCoin() { return coin; } public void setCoin(String coin) { this.coin = coin; } public String getOrderId() { return orderId; } public void setOrderId(String orderId) { this.orderId = orderId; } public String getUserId() { return userId; } public void setUserId(String userId) { this.userId = userId; } } ``` ```go // Go webhook handler package main import ( "encoding/json" "log" "net/http" ) type CustomPaymentWebhookPayload struct { Uuid string `json:"uuid"` Pending int `json:"pending"` ValueCoin float64 `json:"value_coin"` Coin string `json:"coin"` OrderID string `json:"order_id"` UserID string `json:"user_id"` } func paymentWebhookHandler(w http.ResponseWriter, r *http.Request) { // 1. Verify the webhook signature if !verifyWebhookSignature(r) { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // 2. Extract data from the payload var payload CustomPaymentWebhookPayload if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3. Use the uuid to prevent processing the same webhook twice if isWebhookAlreadyProcessed(payload.Uuid) { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } // 4. Handle based on webhook type if payload.Pending == 1 { // Handle pending payment notifyUser(payload.UserID, "Payment detected, awaiting confirmation...") } else if payload.Pending == 0 { // Handle confirmed payment processSuccessfulPayment(PaymentData{ Uuid: payload.Uuid, ValueCoin: payload.ValueCoin, Coin: payload.Coin, OrderID: payload.OrderID, UserID: payload.UserID, }) } // 5. Mark this webhook as processed using the UUID markWebhookAsProcessed(payload.Uuid) // Always respond to stop retries w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) } type PaymentData struct { Uuid string ValueCoin float64 Coin string OrderID string UserID string } ``` ```bash # Test webhook with curl (for development/testing) # Test pending webhook curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -d '{ "uuid": "dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2", "pending": 1, "value_coin": 0.05, "coin": "btc", "order_id": "12345", "user_id": "67890" }' # Test confirmed webhook curl -X POST http://localhost:3000/webhook \ -H "Content-Type: application/json" \ -d '{ "uuid": "dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2", "pending": 0, "value_coin": 0.05, "coin": "btc", "order_id": "12345", "user_id": "67890", "confirmations": 3, "value_forwarded_coin": 0.0495 }' # Expected response: *ok* ``` ## Webhook Payload Example ```json { "uuid": "dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2", "address_in": "3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM", "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP", "txid_in": "a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c", "txid_out": "b3285ggd50390211820g3b18b240decbba70eg3f33f6cf2941332eab2ge5f443d", "confirmations": 3, "value_coin": 0.05, "value_coin_convert": "{\"USD\": \"3.20\", \"EUR\": \"3.05\", \"GBP\": \"2.62\", \"CAD\": \"4.16\"}", "value_forwarded_coin": 0.0495, "value_forwarded_coin_convert": "{\"USD\": \"3.17\", \"EUR\": \"3.01\", \"GBP\": \"2.59\", \"CAD\": \"4.12\"}", "fee_coin": 0.0005, "coin": "btc", "price": 64000, "pending": 0 } ``` --- # Subscriptions Webhook > Source: https://docs.blockbee.io/webhooks/subscriptions-webhook > Description: BlockBee sends webhooks to notify your application about subscription events. This includes payment notifications when users renew subscriptions and expiration notifications when subscriptions end. ## Overview BlockBee sends webhooks to notify your application about subscription events. There are two types of webhook notifications: 1. **Payment Notification** (`action=renew`) - Sent when a user makes a payment to extend or create a subscription 2. **Expiration Notification** (`action=expired`) - Sent when a subscription reaches its end date > **INFO** >**Important:** Always verify webhook signatures to ensure requests are from BlockBee. See our [Verify Webhook Signature guide](/webhooks/verify-webhook-signature) for implementation details. ## Payment Notification Webhook Sent when a user makes a payment (initial subscription payment or renewal). ### Webhook Fields - **`action`** (`string`) (required) - Example: `renew`: Action performed: `renew` if user made a payment, either the initial one or the extension. **Notes:** - Important to check the `subscription_end_date_ts` as it will be updated with the current subscription end date. - **`subscription_id`** (`string`) (required) - Example: `I55hhRINHptLJPwsqwYNxJOKBItRiq1o`: Unique token of the subscription. - **`subscription_url`** (`string`) (required) - Example: `https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o`: Link to the subscription page. - **`subscription_start_date_ts`** (`integer`) (required) - Example: `1718131200`: Timestamp when the subscription started. - **`subscription_end_date_ts`** (`integer`) (required) - Example: `1720723200`: Timestamp when the subscription will expire. - **`subscription_option_slug`** (`string`) (required) - Example: `pro-plan`: Slug of the subscription option selected by the user. - **`subscription_option_duration_ts`** (`number`) (required) - Example: `2592000`: Duration of the subscription option selected by the user, in seconds. - **`subscription_option_value`** (`number`) (required) - Example: `5`: Value of the subscription option in fiat you selected in the Payment Settings. - **`subscription_user_id`** (`string`) (required) - Example: `user_123`: User identifier of your system provided in the here. - **`subscription_user_email`** (`string`) (required) - Example: `user@example.com`: Email address of the user, provided here. - **`payment_url`** (`string`) (required) - Example: `https://pay.blockbee.io/subscription/payment/ls25hhRINHptLJPwsqwYNxJOKBItRiq1o`: Payment link associated with this subscription renewal. - **`payment_redirect_url`** (`string`) (required) - Example: `https://example.com/payment-successful`: URL where the user will be redirected after payment. - **`payment_value`** (`number`) (required) - Example: `5`: Value expected to be paid in fiat. - **`payment_success_token`** (`string`) (required) - Example: `sU7EGOlRRxsxJu4zZoYLa69UXrSijzb73eP6nbQQgpJYAfSL3NiI407lpYqsMbR2`: Success token used to validate the payment. - **`payment_currency`** (`string`) (required) - Example: `usd`: Currency code (e.g. usd, eur). - **`payment_is_paid`** (`integer`) (required) - Example: `1`: Whether the payment is completed (1) or not (0). - **`payment_paid_amount`** (`number`) (required) - Example: `5`: Amount paid in crypto. - **`payment_paid_amount_fiat`** (`number`) (required) - Example: `4.85`: Amount paid in fiat. - **`payment_received_amount`** (`number`) (required) - Example: `5`: Amount received after fee deductions in crypto. - **`payment_received_amount_fiat`** (`number`) (required) - Example: `4.85`: Amount received after fee deductions in fiat. - **`payment_paid_coin`** (`string`) (required) - Example: `btc`: Coin used for payment (e.g. btc, trc20_usdt, etc...). - **`payment_exchange_rate`** (`number`) (required) - Example: `0.97`: Exchange rate at the time of payment. - **`payment_txid`** (`string`) (required) - Example: `0xa1234...,0xa5678...`: Comma-separated transaction IDs of the payment. - **`payment_address`** (`string`) (required) - Example: `0xabc123...`: Blockchain address that received the payment. - **`payment_type`** (`string`) (required) - Example: `payment`: Always `payment` for subscription renewals. - **`payment_status`** (`string`) (required) - Example: `done`: Payment status string. ### Example Payload ```json { "action": "renew", "subscription_id": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_start_date_ts": 1718131200, "subscription_end_date_ts": 1720723200, "subscription_option_slug": "pro-plan", "subscription_option_duration_ts": 2592000, "subscription_option_value": 5, "subscription_user_id": "user_123", "subscription_user_email": "user@example.com", "payment_url": "https://pay.blockbee.io/subscription/payment/ls25hhRINHptLJPwsqwYNxJOKBItRiq1o", "payment_redirect_url": "https://example.com/payment-successful", "payment_value": 5, "payment_success_token": "sU7EGOlRRxsxJu4zZoYLa69UXrSijzb73eP6nbQQgpJYAfSL3NiI407lpYqsMbR2", "payment_currency": "usd", "payment_is_paid": 1, "payment_paid_amount": 5, "payment_paid_amount_fiat": 4.85, "payment_received_amount": 5, "payment_received_amount_fiat": 4.85, "payment_paid_coin": "btc", "payment_exchange_rate": 0.97, "payment_txid": "0xa1234...,0xa5678...", "payment_address": "0xabc123...", "payment_type": "payment", "payment_status": "done" } ``` ## Expiration Notification Webhook Sent when a subscription has reached its end date and is no longer active. ### Webhook Fields - **`action`** (`string`) (required) - Example: `expired`: Indicates that the subscription has reached its end date and is no longer active. No further payments will be processed for expired subscriptions. - **`subscription_id`** (`string`) (required) - Example: `I55hhRINHptLJPwsqwYNxJOKBItRiq1o`: Unique token of the subscription. - **`subscription_url`** (`string`) (required) - Example: `https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o`: Link to the subscription page. - **`subscription_start_date_ts`** (`integer`) (required) - Example: `1718131200`: Timestamp when the subscription started. - **`subscription_end_date_ts`** (`integer`) (required) - Example: `1720723200`: Timestamp when the subscription will expire. - **`subscription_option_slug`** (`string`) (required) - Example: `pro-plan`: Slug of the subscription option selected by the user. - **`subscription_option_duration_ts`** (`number`) (required) - Example: `2592000`: Duration of the subscription option selected by the user, in seconds. - **`subscription_option_value`** (`number`) (required) - Example: `5`: Value of the subscription option in fiat you selected in the Payment Settings. - **`subscription_user_id`** (`string`) (required) - Example: `user_123`: User identifier of your system provided in the here. - **`subscription_user_email`** (`string`) (required) - Example: `user@example.com`: Email address of the user, provided here. ### Example Payload ```json { "action": "expired", "subscription_id": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_start_date_ts": 1718131200, "subscription_end_date_ts": 1720723200, "subscription_option_slug": "pro-plan", "subscription_option_duration_ts": 2592000, "subscription_option_value": 5, "subscription_user_id": "user_123", "subscription_user_email": "user@example.com" } ``` ## Webhook Handling Here are code examples for handling subscription webhooks in different programming languages: ```javascript // Express.js webhook handler app.post('/subscription-webhook', express.json(), (req, res) => { // 1. Verify the webhook signature if (!verifyWebhookSignature(req)) { return res.status(401).send('Unauthorized'); } const { action, subscription_id, subscription_user_id, payment_status } = req.body; // Use subscription_id to prevent duplicate processing if (isWebhookAlreadyProcessed(subscription_id)) { return res.status(200).send('*ok*'); } if (action === 'renew' && payment_status === 'done') { // Grant or extend access for the user // Update subscription end date in your database // Send confirmation email to user console.log(`Subscription renewed for user: ${subscription_user_id}`); } else if (action === 'expired') { // Revoke access for the user // Update subscription status in your database // Send expiration notification to user console.log(`Subscription expired for user: ${subscription_user_id}`); } // Mark this webhook as processed markWebhookAsProcessed(subscription_id); // Always respond with *ok* res.status(200).send('*ok*'); }); ``` ```php <?php // webhook.php // 1. Verify the webhook signature if (!verifyWebhookSignature()) { http_response_code(401); exit('Unauthorized'); } // 2. Extract data from the payload $data = json_decode(file_get_contents('php://input'), true); $action = $data['action']; $subscriptionId = $data['subscription_id']; $userId = $data['subscription_user_id']; $paymentStatus = $data['payment_status'] ?? null; // 3. Use subscription_id to prevent duplicate processing if (isWebhookAlreadyProcessed($subscriptionId)) { http_response_code(200); echo '*ok*'; exit; } if ($action === 'renew' && $paymentStatus === 'done') { // Grant or extend access for the user // Update subscription end date in your database // Send confirmation email to user error_log("Subscription renewed for user: {$userId}"); } elseif ($action === 'expired') { // Revoke access for the user // Update subscription status in your database // Send expiration notification to user error_log("Subscription expired for user: {$userId}"); } // 4. Mark this webhook as processed markWebhookAsProcessed($subscriptionId); // 5. Always respond with *ok* http_response_code(200); echo '*ok*'; ?> ``` ```python # Flask webhook handler @app.route('/subscription-webhook', methods=['POST']) def subscription_webhook(): # 1. Verify the webhook signature if not verify_webhook_signature(request): return 'Unauthorized', 401 # 2. Extract data from the payload data = request.get_json() action = data.get('action') subscription_id = data.get('subscription_id') user_id = data.get('subscription_user_id') payment_status = data.get('payment_status') # 3. Use subscription_id to prevent duplicate processing if is_webhook_already_processed(subscription_id): return '*ok*', 200 if action == 'renew' and payment_status == 'done': # Grant or extend access for the user # Update subscription end date in your database # Send confirmation email to user print(f"Subscription renewed for user: {user_id}") elif action == 'expired': # Revoke access for the user # Update subscription status in your database # Send expiration notification to user print(f"Subscription expired for user: {user_id}") # 4. Mark this webhook as processed mark_webhook_as_processed(subscription_id) # 5. Always respond with *ok* return '*ok*', 200 ``` ```ruby # Ruby on Rails webhook handler class SubscriptionWebhooksController < ApplicationController skip_before_action :verify_authenticity_token def webhook # 1. Verify the webhook signature unless verify_webhook_signature(request) render plain: 'Unauthorized', status: :unauthorized return end # 2. Extract data from the payload action = params[:action] subscription_id = params[:subscription_id] user_id = params[:subscription_user_id] payment_status = params[:payment_status] # 3. Use subscription_id to prevent duplicate processing if webhook_already_processed?(subscription_id) render plain: '*ok*', status: :ok return end if action == 'renew' && payment_status == 'done' # Grant or extend access for the user # Update subscription end date in your database # Send confirmation email to user Rails.logger.info("Subscription renewed for user: #{user_id}") elsif action == 'expired' # Revoke access for the user # Update subscription status in your database # Send expiration notification to user Rails.logger.info("Subscription expired for user: #{user_id}") end # 4. Mark this webhook as processed mark_webhook_as_processed(subscription_id) # 5. Always respond with *ok* render plain: '*ok*', status: :ok end end ``` ```csharp // ASP.NET Core webhook handler [ApiController] [Route("webhook")] public class SubscriptionWebhookController : ControllerBase { [HttpPost("subscription")] public async Task<IActionResult> SubscriptionWebhook([FromBody] SubscriptionWebhookPayload payload) { // 1. Verify the webhook signature if (!VerifyWebhookSignature(Request)) { return Unauthorized("Unauthorized"); } // 2. Extract data from the payload var action = payload.Action; var subscriptionId = payload.SubscriptionId; var userId = payload.SubscriptionUserId; var paymentStatus = payload.PaymentStatus; // 3. Use subscription_id to prevent duplicate processing if (IsWebhookAlreadyProcessed(subscriptionId)) { return Ok("*ok*"); } if (action == "renew" && paymentStatus == "done") { // Grant or extend access for the user // Update subscription end date in your database // Send confirmation email to user _logger.LogInformation($"Subscription renewed for user: {userId}"); } else if (action == "expired") { // Revoke access for the user // Update subscription status in your database // Send expiration notification to user _logger.LogInformation($"Subscription expired for user: {userId}"); } // 4. Mark this webhook as processed MarkWebhookAsProcessed(subscriptionId); // 5. Always respond with *ok* return Ok("*ok*"); } } public class SubscriptionWebhookPayload { [JsonProperty("action")] public string Action { get; set; } [JsonProperty("subscription_id")] public string SubscriptionId { get; set; } [JsonProperty("subscription_user_id")] public string SubscriptionUserId { get; set; } [JsonProperty("payment_status")] public string PaymentStatus { get; set; } } ``` ```java // Spring Boot webhook handler @RestController @RequestMapping("/webhook") public class SubscriptionWebhookController { @PostMapping("/subscription") public ResponseEntity<String> subscriptionWebhook(@RequestBody SubscriptionWebhookPayload payload) { // 1. Verify the webhook signature if (!verifyWebhookSignature(request)) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized"); } // 2. Extract data from the payload String action = payload.getAction(); String subscriptionId = payload.getSubscriptionId(); String userId = payload.getSubscriptionUserId(); String paymentStatus = payload.getPaymentStatus(); // 3. Use subscription_id to prevent duplicate processing if (isWebhookAlreadyProcessed(subscriptionId)) { return ResponseEntity.ok("*ok*"); } if ("renew".equals(action) && "done".equals(paymentStatus)) { // Grant or extend access for the user // Update subscription end date in your database // Send confirmation email to user log.info("Subscription renewed for user: {}", userId); } else if ("expired".equals(action)) { // Revoke access for the user // Update subscription status in your database // Send expiration notification to user log.info("Subscription expired for user: {}", userId); } // 4. Mark this webhook as processed markWebhookAsProcessed(subscriptionId); // 5. Always respond with *ok* return ResponseEntity.ok("*ok*"); } } public class SubscriptionWebhookPayload { private String action; private String subscriptionId; private String subscriptionUserId; private String paymentStatus; // Getters and setters public String getAction() { return action; } public void setAction(String action) { this.action = action; } public String getSubscriptionId() { return subscriptionId; } public void setSubscriptionId(String subscriptionId) { this.subscriptionId = subscriptionId; } public String getSubscriptionUserId() { return subscriptionUserId; } public void setSubscriptionUserId(String subscriptionUserId) { this.subscriptionUserId = subscriptionUserId; } public String getPaymentStatus() { return paymentStatus; } public void setPaymentStatus(String paymentStatus) { this.paymentStatus = paymentStatus; } } ``` ```go // Go webhook handler package main import ( "encoding/json" "log" "net/http" ) type SubscriptionWebhookPayload struct { Action string `json:"action"` SubscriptionID string `json:"subscription_id"` SubscriptionUserID string `json:"subscription_user_id"` PaymentStatus string `json:"payment_status"` } func subscriptionWebhookHandler(w http.ResponseWriter, r *http.Request) { // 1. Verify the webhook signature if !verifyWebhookSignature(r) { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } // 2. Extract data from the payload var payload SubscriptionWebhookPayload if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3. Use subscription_id to prevent duplicate processing if isWebhookAlreadyProcessed(payload.SubscriptionID) { w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) return } if payload.Action == "renew" && payload.PaymentStatus == "done" { // Grant or extend access for the user // Update subscription end date in your database // Send confirmation email to user log.Printf("Subscription renewed for user: %s", payload.SubscriptionUserID) } else if payload.Action == "expired" { // Revoke access for the user // Update subscription status in your database // Send expiration notification to user log.Printf("Subscription expired for user: %s", payload.SubscriptionUserID) } // 4. Mark this webhook as processed markWebhookAsProcessed(payload.SubscriptionID) // 5. Always respond with *ok* w.WriteHeader(http.StatusOK) w.Write([]byte("*ok*")) } ``` ```bash # Test webhook with curl (for development/testing) # Test payment notification webhook curl -X POST http://localhost:3000/webhook/subscription \ -H "Content-Type: application/json" \ -d '{ "action": "renew", "subscription_id": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_start_date_ts": 1718131200, "subscription_end_date_ts": 1720723200, "subscription_option_slug": "pro-plan", "subscription_option_duration_ts": 2592000, "subscription_option_value": 5, "subscription_user_id": "user_123", "subscription_user_email": "user@example.com", "payment_url": "https://pay.blockbee.io/subscription/payment/ls25hhRINHptLJPwsqwYNxJOKBItRiq1o", "payment_redirect_url": "https://example.com/payment-successful", "payment_value": 5, "payment_success_token": "sU7EGOlRRxsxJu4zZoYLa69UXrSijzb73eP6nbQQgpJYAfSL3NiI407lpYqsMbR2", "payment_currency": "usd", "payment_is_paid": 1, "payment_paid_amount": 5, "payment_paid_amount_fiat": 4.85, "payment_received_amount": 5, "payment_received_amount_fiat": 4.85, "payment_paid_coin": "btc", "payment_exchange_rate": 0.97, "payment_txid": "0xa1234...,0xa5678...", "payment_address": "0xabc123...", "payment_type": "payment", "payment_status": "done" }' # Test expiration notification webhook curl -X POST http://localhost:3000/webhook/subscription \ -H "Content-Type: application/json" \ -d '{ "action": "expired", "subscription_id": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_start_date_ts": 1718131200, "subscription_end_date_ts": 1720723200, "subscription_option_slug": "pro-plan", "subscription_option_duration_ts": 2592000, "subscription_option_value": 5, "subscription_user_id": "user_123", "subscription_user_email": "user@example.com" }' # Expected response: *ok* ``` ### Best Practices - **Verify Signatures:** Always verify webhook signatures to ensure requests are from BlockBee - **Idempotency:** Use the `subscription_id` to prevent processing the same webhook multiple times - **Respond Quickly:** Always respond with `*ok*` and a `200` status code to prevent BlockBee from resending the webhook - **Asynchronous Processing:** For long-running tasks, process them in a background job after responding to the webhook - **Error Handling:** Log errors but don't let them prevent the webhook response - **Database Updates:** Update your database with the new subscription end date when processing renewal webhooks > **TIP** >**Implementation Guide:** For detailed instructions on how to verify webhook signatures, see our [Verify Webhook Signature guide](/webhooks/verify-webhook-signature). ## Webhook Verification Always verify that webhooks are coming from BlockBee by checking the signature. This prevents malicious requests from impersonating BlockBee. > **WARNING** >**Security:** Never skip signature verification in production. This is crucial for the security of your application. For implementation details, see our [Verify Webhook Signature guide](/webhooks/verify-webhook-signature). ## Webhook Payload Example ```json { "action": "renew", "subscription_id": "I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_url": "https://pay.blockbee.io/subscription/I55hhRINHptLJPwsqwYNxJOKBItRiq1o", "subscription_start_date_ts": 1718131200, "subscription_end_date_ts": 1720723200, "subscription_option_slug": "pro-plan", "subscription_option_duration_ts": 2592000, "subscription_option_value": 5, "subscription_user_id": "user_123", "subscription_user_email": "user@example.com", "payment_url": "https://pay.blockbee.io/subscription/payment/ls25hhRINHptLJPwsqwYNxJOKBItRiq1o", "payment_redirect_url": "https://example.com/payment-successful", "payment_value": 5, "payment_success_token": "sU7EGOlRRxsxJu4zZoYLa69UXrSijzb73eP6nbQQgpJYAfSL3NiI407lpYqsMbR2", "payment_currency": "usd", "payment_is_paid": 1, "payment_paid_amount": 5, "payment_paid_amount_fiat": 4.85, "payment_received_amount": 5, "payment_received_amount_fiat": 4.85, "payment_paid_coin": "btc", "payment_exchange_rate": 0.97, "payment_txid": "0xa1234...,0xa5678...", "payment_address": "0xabc123...", "payment_type": "payment", "payment_status": "done" } ``` --- # Verify Webhook Signatures > Source: https://docs.blockbee.io/webhooks/verify-webhook-signature > Description: Learn how to verify BlockBee webhook signatures to ensure requests are authentic and haven't been tampered with. Complete implementation guide with examples in multiple programming languages. # Verify Webhook Signatures > **WARNING** >**Critical Security Step!** Always verify webhook signatures to ensure requests actually came from BlockBee and haven't been tampered with. This prevents malicious actors from sending fake webhooks to your application. BlockBee uses a **1024-bit RSA SHA256 signature** with a public-key signature scheme to sign every webhook sent to your service. This ensures all data was sent from BlockBee and can be trusted. ## How BlockBee Signature Works ### What Gets Signed - **For GET requests**: The full URL including all query parameters is signed - **For POST requests**: The entire request body is signed ### Signature Details - **Algorithm**: RSA SHA256 with PKCS1v15 padding - **Key Size**: 1024-bit RSA key - **Header**: Signature is sent in the `x-ca-signature` header - **Encoding**: Signature is base64-encoded - **Public Key**: Available at `https://api.blockbee.io/pubkey/` ### Example Signed Data For a GET request, the signed data looks like: ```bash https://yoursite.com/webhook?uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2&address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM&txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c&value_coin=0.05&confirmations=3&pending=0 ``` For a POST request, the signed data is the raw request body: ```bash uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2&address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM&txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c&value_coin=0.05&confirmations=3&pending=0 ``` ## Implementation Examples ```javascript // Node.js verification const crypto = require('crypto'); // BlockBee's public key (you can also fetch from https://api.blockbee.io/pubkey/) const BLOCKBEE_PUBLIC_KEY = `-----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3FT0Ym8b3myVxhQW7ESuuu6lo dGAsUJs4fq+Ey//jm27jQ7HHHDmP1YJO7XE7Jf/0DTEJgcw4EZhJFVwsk6d3+4fy Bsn0tKeyGMiaE6cVkX0cy6Y85o8zgc/CwZKc0uw6d5siAo++xl2zl+RGMXCELQVE ox7pp208zTvown577wIDAQAB -----END PUBLIC KEY-----`; function verifyBlockBeeSignature(req) { try { // Get signature from header const signature_b64 = req.headers['x-ca-signature']; if (!signature_b64) { console.error('Missing x-ca-signature header'); return false; } // Decode signature from base64 const signature = Buffer.from(signature_b64, 'base64'); // Determine what data to verify based on request method let dataToVerify; if (req.method === 'GET') { // For GET requests, sign the full URL dataToVerify = req.protocol + '://' + req.get('host') + req.originalUrl; } else { // For POST requests, sign the raw body dataToVerify = req.rawBody; // You need raw body middleware } // Create verifier and verify signature const verifier = crypto.createVerify('RSA-SHA256'); verifier.update(dataToVerify); const isValid = verifier.verify(BLOCKBEE_PUBLIC_KEY, signature); if (!isValid) { console.error('Invalid signature'); } return isValid; } catch (error) { console.error('Signature verification error:', error); return false; } } // Express middleware to capture raw body function captureRawBody(req, res, next) { req.rawBody = ''; req.on('data', chunk => { req.rawBody += chunk.toString(); }); req.on('end', () => { next(); }); } // Usage in Express app.use('/webhook', captureRawBody); app.post('/webhook', (req, res) => { if (!verifyBlockBeeSignature(req)) { return res.status(401).send('Invalid signature'); } // Process webhook safely console.log('Verified webhook received'); res.status(200).send('*ok*'); }); ``` ```python import base64 from cryptography.hazmat.primitives import hashes from cryptography.hazmat.primitives.asymmetric import padding from cryptography.hazmat.primitives import serialization from cryptography.hazmat.backends import default_backend # BlockBee's public key BLOCKBEE_PUBLIC_KEY = """-----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3FT0Ym8b3myVxhQW7ESuuu6lo dGAsUJs4fq+Ey//jm27jQ7HHHDmP1YJO7XE7Jf/0DTEJgcw4EZhJFVwsk6d3+4fy Bsn0tKeyGMiaE6cVkX0cy6Y85o8zgc/CwZKc0uw6d5siAo++xl2zl+RGMXCELQVE ox7pp208zTvown577wIDAQAB -----END PUBLIC KEY-----""" def verify_blockbee_signature(request): """ Verify BlockBee webhook signature Args: request: Django HttpRequest or Flask request object Returns: bool: True if signature is valid, False otherwise """ try: # Get signature from header signature_b64 = request.headers.get('x-ca-signature') if not signature_b64: print("Missing x-ca-signature header") return False # Determine what data to verify if request.method == 'GET': # For GET requests, sign the full URL data_to_verify = request.build_absolute_uri() else: # For POST requests, sign the raw body if hasattr(request, 'body'): # Django data_to_verify = request.body.decode('utf-8') else: # Flask data_to_verify = request.get_data(as_text=True) # Load public key public_key = serialization.load_pem_public_key( BLOCKBEE_PUBLIC_KEY.encode('utf-8'), backend=default_backend() ) # Decode signature signature = base64.b64decode(signature_b64) # Verify signature public_key.verify( signature, data_to_verify.encode('utf-8'), padding.PKCS1v15(), hashes.SHA256() ) return True except Exception as e: print(f"Signature verification error: {e}") return False # Django usage def blockbee_webhook(request): if not verify_blockbee_signature(request): return HttpResponse('Invalid signature', status=401) # Process webhook safely print("Verified webhook received") return HttpResponse('*ok*') # Flask usage @app.route('/webhook', methods=['GET', 'POST']) def blockbee_webhook(): if not verify_blockbee_signature(request): return 'Invalid signature', 401 # Process webhook safely print("Verified webhook received") return '*ok*' ``` ```php <?php // BlockBee's public key const BLOCKBEE_PUBLIC_KEY = "-----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3FT0Ym8b3myVxhQW7ESuuu6lo dGAsUJs4fq+Ey//jm27jQ7HHHDmP1YJO7XE7Jf/0DTEJgcw4EZhJFVwsk6d3+4fy Bsn0tKeyGMiaE6cVkX0cy6Y85o8zgc/CwZKc0uw6d5siAo++xl2zl+RGMXCELQVE ox7pp208zTvown577wIDAQAB -----END PUBLIC KEY-----"; function verifyBlockBeeSignature() { try { // Get signature from header $signatureHeader = $_SERVER['HTTP_X_CA_SIGNATURE'] ?? null; if (!$signatureHeader) { error_log('Missing x-ca-signature header'); return false; } // Decode signature from base64 $signature = base64_decode($signatureHeader); if ($signature === false) { error_log('Invalid base64 signature'); return false; } // Determine what data to verify if ($_SERVER['REQUEST_METHOD'] === 'GET') { // For GET requests, sign the full URL $dataToVerify = "https://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]"; } else { // For POST requests, sign the raw body $dataToVerify = file_get_contents('php://input'); } // Verify signature $result = openssl_verify($dataToVerify, $signature, BLOCKBEE_PUBLIC_KEY, OPENSSL_ALGO_SHA256); if ($result === 1) { return true; } elseif ($result === 0) { error_log('Invalid signature'); return false; } else { error_log('Signature verification error: ' . openssl_error_string()); return false; } } catch (Exception $e) { error_log('Signature verification exception: ' . $e->getMessage()); return false; } } // Usage if (!verifyBlockBeeSignature()) { http_response_code(401); exit('Invalid signature'); } // Process webhook safely error_log('Verified webhook received'); http_response_code(200); echo '*ok*'; ?> ``` > **TIP** >**Test signature verification!** Make sure to test the signature verification when testing your integration as it's a very important safety feature. ## Security Best Practices 1. **Always verify signatures** - Never skip signature verification in production 2. **Use HTTPS** - Ensure your webhook endpoint uses HTTPS 3. **Implement rate limiting** - Prevent abuse of your webhook endpoint 4. **Log security events** - Log all signature verification failures 5. **Validate webhook data** - Even verified webhooks should have data validation 6. **Use idempotency** - Prevent duplicate processing of webhooks > **SUCCESS** >**Signature Verification Complete!** Your webhook endpoint is now secure and can trust that all requests come from BlockBee. Remember to test thoroughly and monitor for any verification failures. --- # BlockBee's Django Library > Source: https://docs.blockbee.io/libraries/django > Description: Django's implementation of BlockBee's payment gateway ## Requirements * `Python >= 3.0` * `Django >= 2.0` * `Requests >= 2.20` ## Installation ```shell script pip install django-blockbee ``` > **TIP** >**Full Source Code Available:** You can find the complete source code, examples, and contribute to this library on our official GitHub repository: [github.com/blockbee-io/django-blockbee](https://github.com/blockbee-io/django-blockbee) Add to `INSTALLED_APPS`: ```python INSTALLED_APPS = ( 'blockbee', ... ) ``` Run migrations: ```shell script python3 manage.py migrate blockbee ``` Collect static files: ```shell script python3 manage.py collectstatic ``` Add BlockBee's URLs to your project's urls.py file: ```python urlpatterns = [ path('blockbee/', include('blockbee.urls')), ... ] ``` Add your BlockBee API Key (obtained from our [Dashboard](https://dash.blockbee.io/)). ```python BLOCKBEE_API_KEY = 'your_api_key' ``` ## Configuration After the installation you need to set up Providers for each coin you wish to accept. You need to go into your Django Admin and create a new BlockBee ``Provider`` for each coin with your cold wallet address where the funds will be forwarded to. ## Usage ### Creating an Invoice In your order creation view, assuming ``user_order`` is your order object: ##### If you want the address generated: ```python from blockbee import Invoice def order_creation_view(request): ... invoice = Invoice( request=request, order_id=user_order.id, coin='btc', value=user_order.value ) payment_address = invoice.address() if payment_address is not None: # Show the payment address to the user ... else: # Handle request error, check RequestLogs on Admin ``` ##### If you want the `blockbee.models.Request` object: ```python from blockbee import Invoice def order_creation_view(request): ... invoice = Invoice( request=request, # This if your view request. It's meant to create the callback URL order_id=user_order.id, coin='btc', value=user_order.value ) payment_request = invoice.request() if payment_request is not None: # Show the payment address to the user ... else: # Handle request error, check RequestLogs on Admin ``` #### Where: * ``request`` is Django's view HttpRequest object * ``order_id`` is just your order id * ``coin`` is the ticker of the coin you wish to use, any of our [supported coins](https://blockbee.io/cryptocurrencies/). You need to have a ``Provider`` set up for that coin. * ``value`` is an integer of the value of your order * ``apikey`` is the API Key that you got from your BlockBee Dashboard ### Getting notified when the user pays ```python from django.dispatch import receiver from blockbee.signals import payment_complete @receiver(payment_complete) def payment_received(order_id, payment, value): # Implement your logic to mark the order as paid and release the goods to the user ... ``` Where: * ``order_id`` is the id of the order that you provided earlier, used to fetch your order * ``payment`` is an ``blockbee.models.Payment`` object with the payment details, such as TXID, number of confirmations, etc. * ``value`` is the value the user paid > **WARNING** >**Important:** Don't forget to import your signals file. > > On your App's `apps.py` file: > > ```python > class MyAppConfig(AppConfig): > name = 'MyApp' > > def ready(self): > super(MyAppConfig, self).ready() > > # noinspection PyUnresolvedReferences > import MyApp.signals > ``` > > [django docs](https://docs.djangoproject.com/en/5.2/topics/signals/#django.dispatch.receiver) ### Using our provided interface Create a view in ``views.py`` ```python def payment(_r, request_id): try: req = Request.objects.get(id=request_id) coin = req.provider.coin qrcode = get_qrcode(coin, req.address_in) fiat = get_conversion(coin, 'eur', req.value_requested) print(fiat) ctx = { 'req': req, 'qrcode': qrcode, 'fiat': fiat['value_coin'] } return render(_r, 'payment.html', context=ctx) except Request.DoesNotExist: pass return redirect('store:request') ``` In your template HTML ```djangotemplate {% extends 'base.html' %} {% load blockbee_helper %} {% block content %} {% generate_payment_template %} {% endblock %} ``` ### Helpers This library has a couple of helpers to help you get started. They are present in the file ``utils.py``. * ``blockbee.valid_providers()`` is a method that returns a list of tuples of the active providers that you can just feed into the choices of a ``form.ChoiceField`` * ``blockbee.get_order_invoices(order_id)`` returns a list of ``blockbee.models.Request`` objects of your order (you can have multiple objects for the same order if the user mistakenly initiated the payment with another coin or if he mistakenly didn't send the full payment) * ``blockbee.callback_url(_r, params)`` build your callback URL to provide to ``get_request``. Should be used inside a view since ``_r = request`` ### BlockBee Helper This is the helper responsible for the connections to the API itself. All these functions are in the ``blockbee.py`` file. * ``get_info(coin)`` returns the information of all cryptocurrencies or just if ``coin=''`` or a specific cryptocurrency if ``coin='ltc'`` for example. [docs](https://docs.blockbee.io/#operation/info) * ``get_supported_coins()`` returns all the support cryptocurrencies. You can consult them in this [list](https://blockbee.io/fees/). * ``get_logs(coin, callback_url)`` returns all the callback logs related to a request. ``callback_url`` should be the callback provided to our API. [docs](https://docs.blockbee.io/#operation/logs) * ``get_qrcode(coin, address, value, size)`` returns a PNG of a QR Code with the address for payment. [docs](https://docs.blockbee.io/tag/Bitcoin#operation/btcqrcode) * ``get_conversion(origin, to, value)`` returns the converted value in the parameter ``value_coin`` to the currency you wish, FIAT or Cryptocurrency. * ``get_estimate(coin)`` returns the estimation of the blockchain fees for the cryptocurrency specified in the parameter ``coin``. E.g: ``get_estimate('trc20_usdt')`` [docs](https://docs.blockbee.io/#operation/estimate) * ``get_address(coin, params)`` requests a payment address to BlockBee. Params include all the parameters that can be found [here](https://docs.blockbee.io/#operation/create). The parameter ``apikey`` is mandatory. ### How to use the QR code (with address, coin and value) To generate a QR Code you must use ``get_qrcode`` in your view and feed the parameters to your template. To generate a QR Code image you must place content of the API response after ``data:image/png;base64,{{qr_code}}`` so the browser generates the QR Code. ```djangotemplate <img src="data:image/png;base64,{{ qrcode.qr_code }}" alt="Payment QR Code"/> ``` You can also make the QR Code clickable. ```djangotemplate <a href='{{ qrcode.payment_uri }}'> <img src="data:image/png;base64,{{ qrcode.qr_code }}" alt="Payment QR Code"/> </a> ``` You can also add a value to the QR Code setting the ``value`` parameter to the value of your order (e.g ``0.2 LTC``). This may not function correctly in some wallets. **Use at your own risk.** ## What is the Store application? We made the ``store`` application to provide you with code examples on how to implement our service. It also has the code for our suggested UI (both CSS and HTML). ## Help Need help? Contact us @ https://blockbee.io/contacts/ ## Changelog #### 1.0.0 * Initial Release #### 1.0.1 * Minor fixes * UI Improvements #### 1.0.2 * Minor fixes #### 1.0.3 * Minor fixes * Signals now use the value_coin * Removed deprecated fields from the payment model #### 1.0.4 * Minor fixes #### 1.0.5 * Minor fixes #### 1.0.6 * Minor fixes #### 1.0.7 * Minor fixes --- # BlockBee's NodeJS Library > Source: https://docs.blockbee.io/libraries/nodejs > Description: NodeJS's implementation of BlockBee's payment gateway ## Requirements: ``` NodeJS >= 20 ``` ## Installation ```console npm install @blockbee/api ``` > **TIP** >**Full Source Code Available:** You can find the complete source code, examples, and contribute to this library on our official GitHub repository: [github.com/blockbee-io/nodejs-api](https://github.com/blockbee-io/nodejs-api) ## API and utils ### Importing in your project file ```js var BlockBee = require('@blockbee/api') ``` ### Getting service info ```js // Get general service information const info = await BlockBee.getInfo() // Get specific coin information const coinInfo = await BlockBee.getInfo('btc') ``` #### Where: * The first call gets general service information * The second call gets information for a specific coin (e.g. 'btc', 'eth', 'erc20_usdt', ...) > Response contains service information and coin-specific details when a coin parameter is provided. ### Generating a new Address ```js const bb = new BlockBee(coin, myAddress, callbackUrl, params, blockbeeParams, apiKey) const address = await bb.getAddress() ``` #### Where: * `coin` is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...). * `myAddress` is your own crypto address, where your funds will be sent to. It's optional, you can leave it empty (e.g ``''``) if you are setting it up in BlockBee's [dashboard](https://dash.blockbee.io/). * `callbackUrl` is the URL that will be called upon payment. * `params` is any parameter you wish to send to identify the payment, such as `{orderId: 1234}`. * `blockbeeParams` parameters that will be passed to BlockBee. Check our [API Reference](https://docs.blockbee.io/api/create-checkout) for more information. * `apiKey` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * `address` is the newly generated address, to show your customer for payment. #### Response sample: ```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", "minimum_transaction_coin": 0.008, "status": "success" } ``` #### Getting notified when the user pays > Once your customer makes a payment, BlockBee will send a callback to your `callbackUrl`. This callback information is by default in ``GET`` but you can se it to ``POST`` by setting ``post: 1`` in ``blockbeeParams``. The parameters sent by BlockBee in this callback can be consulted here: https://docs.blockbee.io/#operation/confirmedcallbackget ### Checking the logs of a request ```js const bb = new BlockBee(coin, myAddress, callbackUrl, params, blockbeeParams, apiKey) const data = await bb.checkLogs() ``` #### Response sample: ```json { "status": "success", "callback_url": "https://example.com/?order_id=1235", "address_in": "0x58e90D31530A5566dA97e34205730323873eb88B", "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d", "notify_pending": false, "notify_confirmations": 1, "priority": "default", "callbacks": [] } ``` All the `data` returned in the response can be checked here: https://docs.blockbee.io/#operation/logs ### Generating a QR code ```js const bb = new BlockBee(coin, myAddress, callbackUrl, params, blockbeeParams, apiKey) const qrCode = await bb.getQrcode(value, size) ``` #### Where: * ``value`` is the value requested to the user in the coin to which the request was done. **Optional**, can be empty if you don't wish to add the value to the QR Code. * ``size`` Size of the QR Code image in pixels. Optional, leave empty to use the default size of 512. > Response is an object with `qr_code` (base64 encoded image data) and `payment_uri` (the value encoded in the QR), see https://docs.blockbee.io/#operation/qrcode for more information. #### Response sample: ```json { "status": "success", "qr_code": "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", "payment_uri": "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB" } ``` #### Usage ```jsx <img src={`data:image/png;base64,${qr_code}`}/> ``` ### Estimating transaction fees ```js const fees = await BlockBee.getEstimate(coin, apiKey, addresses, priority) ``` #### Where: * ``coin`` is the coin you wish to check, from BlockBee's supported currencies (e.g `btc`, `eth`, `erc20_usdt`, ...) * ``apiKey`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``addresses`` The number of addresses to forward the funds to. Optional, defaults to 1. * ``priority`` Confirmation priority, (check [this](/kb/developers/api/what-is-the-priority-parameter) article to learn more about it). Optional, defaults to ``default``. > Response is an object with ``estimated_cost`` and ``estimated_cost_usd``, see https://docs.blockbee.io/#operation/estimate for more information. #### Response sample: ```json { "status": "success", "estimated_cost": "0.00637010", "estimated_cost_currency": { "AED": "0.03", "AUD": "0.01", "BGN": "0.01", "BRL": "0.04" } } ``` ### Converting between coins and fiat ```js const conversion = await BlockBee.getConvert(coin, value, from, apiKey) ``` #### Where: * ``coin`` the target currency to convert to, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...) * ``value`` value to convert in `from`. * ``from`` currency to convert from, FIAT or crypto. * ``apiKey`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). > Response is an object with ``value_coin`` and ``exchange_rate``, see https://docs.blockbee.io/#operation/convert for more information. #### Response sample: ```json { "status": "success", "value_coin": "241.126", "exchange_rate": "0.803753" } ``` ### Getting supported coins ```js const supportedCoins = await BlockBee.getSupportedCoins(apiKey) ``` #### Where: * ``apiKey`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). > Response is an array with all supported coins. #### Response sample: ```json { "btc": { "coin": "Bitcoin", "logo": "https://api.cryptapi.io/media/token_logos/btc.png", "ticker": "btc", "minimum_transaction": 8000, "minimum_transaction_coin": "0.00008000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00002518" }, "bch": { "coin": "Bitcoin Cash", "logo": "https://api.cryptapi.io/media/token_logos/bch.png", "ticker": "bch", "minimum_transaction": 50000, "minimum_transaction_coin": "0.00050000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00000305" } } ``` ## Checkout ### Checkout Payments #### Requesting Payment ```js const paymentRequest = await BlockBee.paymentRequest(redirectUrl, notifyUrl, value, apiKey, params, bbParams) ``` #### Where: * ``redirectUrl`` URL in your platform, where the user will be redirected to following the payment. Should be able to process the payment using the `success_token`, if you wish to use this URL to confirm payment. * ``notifyUrl`` URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn. * ``value`` amount in currency set in Payment Settings you want to receive from the user. * ``apiKey`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``params`` is any parameter you wish to send to identify the payment, such as `{order_id: 1234}`. * ``bbParams`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create). #### Getting notified when the user completes the Payment > When receiving payments, you have the option to receive them in either the ``notify_url`` or the ``redirect_url``, but adding the ``redirect_url`` is required (refer to our documentation at https://docs.blockbee.io/#operation/paymentipn). #### Payment samples: ```json { "status": "success", "success_token": "G4asA2xwEr0UeY2IZqlZjX3IYrNofmnIAkzHPAoxmpmlYP9ZLTvQUolKN0X27Z0B", "payment_url": "https://pay.blockbee.io/payment/OcRrZGsKQFGsoi0asqZkr97WbitMxFMb/", "payment_id": "OcRrZGsKQFGsoi0asqZkr97WbitMxFMb" } ``` #### Payment Logs Fetch Payment information and IPN logs. ```javascript const logs = await BlockBee.paymentLogs(token, apiKey); ``` #### Where: * ```token``` is the `payment_id` returned by the payment creation endpoint. #### Response sample: ```json { "status": "success", "is_paid": false, "is_pending": false, "is_expired": false, "is_partial": false, "payment_data": [ { "value": "0.000137", "value_paid": "0", "value_outstanding": "0.000137", "exchange_rate": "0.0000137489", "coin": "btc", "txid": [] } ], "notifications": [] } ``` ### Checkout Deposits #### Requesting Deposit ```js const deposit = await BlockBee.depositRequest(notifyUrl, apiKey, params, bbParams) ``` #### Where: * ``notifyUrl`` URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn. * ``apiKey`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``params`` is any parameter you wish to send to identify the payment, such as `{order_id: 1234}`. * ``bbParams`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/deposit). #### Response sample: ```json { "status": "success", "payment_url": "https://pay.blockbee.io/deposit/jv12du8IWqS96WVDjZK2J285WOBOBycc/", "payment_id": "jv12du8IWqS96WVDjZK2J285WOBOBycc" } ``` #### Deposit Logs Fetch Deposit information and IPN logs. ```javascript const logs = await BlockBee.depositLogs(token, apiKey); ``` #### Where: * ```token``` is the `payment_id` returned by the deposit creation endpoint. #### Response sample: ```json { "status": "success", "deposits": [], "total_deposited": "0", "currency": "USDT", "notifications": [] } ``` ## Payouts ### Create Payout / Payout Request Use this function to create [Payouts](https://docs.blockbee.io/#tag/Payouts). ```javascript const coin = 'polygon_pol' const requests = { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.5, '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 } const createPayout = await BlockBee.createPayout(coin, requests, apiKey, process); ``` #### Where: * ``coin`` The cryptocurrency you want to request the Payout in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``requests`` Address(es) together with the amount that must be sent. * ``process`` If the Payout Requests will be sent right away. Defaults to `false`. **Note**: if `true` will instantly queue the payouts to be sent to the destination addresses. #### Response sample: If `process` is `false`. ```json { "status": "success", "request_ids": [ 103227, 103228 ] } ``` If `process` is `true`. ```json { "status": "success", "queued": true } ``` ### List Payouts / Payout Requests List all Payouts or Payout Requests in your account. **Note:** If `requests` is `true` it will fetch a Payout Requests list. ```javascript const payoutList = await BlockBee.listPayouts(coin, status, page, apiKey, requests); ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``status`` The status of the Payout / Payout Request. Possible statuses are: * Payout Request: [`all`, `pending`, `rejected`, `processing`, `done`] * Payout: [`created`, `processing`, `done`, `error`] * ``page`` This endpoint is paginated and will show only `50` items per page. Defaults to `1`. * ``requests`` If `true` will fetch Payout Requests, otherwise will fetch Payouts. Defaults to `false`. #### Response sample: ```json { "status": "success", "payouts": [ { "id": 2460, "status": "Done", "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_pol", "timestamp": "13/03/2024 17:48:39" } ], "num_pages": 1 } ``` ### Get Payout Wallet Gets your Payout Wallet for the specified `coin`. Can algo get the balance. ```javascript const wallet = await BlockBee.getPayoutWallet(coin, apiKey, balance) ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``balance`` If `true` will also fetch the balance of the address. #### Response sample: ```json { "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "balance": "2.7" } ``` ### Create Payout with Payout Request ID(s) With this function you can create a Payout in the `created` status by providing an array with the Payout Requests `ID`. ```javascript const ids = [52211, 52212] const payout = await BlockBee.createPayoutByIds(apiKey, ids) ``` #### Where: * ``ids`` its an array with the Payout Requests `ID`. #### Response sample: ```json { "status": "success", "payout_info": { "id": 2461, "status": "Created", "from": "", "requests": { "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000", "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000" }, "total_requested": "0.5", "total_with_fee": "0.505", "total_fiat": "", "fee": "0.005", "coin": "bep20_usdt", "txid": "", "timestamp": "05/03/2024 15:00:00" } } ``` ### Process Payout by ID By default, a Payout when created will be in `created` state. With this function you may finish it using its `ID`. ```javascript const payout = await BlockBee.processPayout(apiKey, id) ``` #### Where: * ``id`` Its the `ID` of the Payout you wish to fulfill. #### Response sample: ```json { "status": "success", "queued": true } ``` ### Check the Payout status Will return all important information regarding a Payout, specially its status. ```javascript const id = 51621 const status = await BlockBee.checkPayoutStatus(apiKey, id) ``` #### Where: * ``id`` Its the `ID` of the Payout you wish to check. #### Response sample: ```json { "status": "success", "payout_info": { "id": 2463, "status": "Done", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.500000000000000000", "0x18B211A1Ba5880C7d62C250B6441C2400d588589": "0.100000000000000000" }, "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_pol", "txid": "0xf9aa1618a7e460f8c68b6a02369b5058282c53a4ee23f967abef0d35203f328c", "timestamp": "13/03/2024 18:10:35" } } ``` ## Help Need help? Contact us @ https://blockbee.io/contacts/ ## Changelog #### 1.0.0 * Initial Release #### 1.0.2 * Version Bump #### 1.0.3 * Minor fixes #### 1.0.4 * Minor fixes #### 1.1.0 * Added Payouts * Minor bugfixes #### 1.1.1 * Minor bugfixes #### 2.0.0 * Automated Payouts * Support to BlockBee Checkout page * Various improvements #### 2.0.1 * Minor fixes #### 2.1.0 * Minor bugfixes * Improve error handling #### 2.1.1 * Minor improvements ### Breaking Changes #### 2.0.0 * `createPayout` parameters were changed and will require you to update your code. --- # BlockBee's PHP Library > Source: https://docs.blockbee.io/libraries/php > Description: PHP implementation of BlockBee's payment gateway # BlockBee's PHP Library Official PHP library of BlockBee ## Requirements * `PHP >= 7.2.0` * `ext-curl` * `ext-json` ## Installation ```shell composer require blockbee/php-blockbee ``` > **TIP** >**Full Source Code Available:** You can find the complete source code, examples, and contribute to this library on our official GitHub repository: [github.com/blockbee-io/php-blockbee](https://github.com/blockbee-io/php-blockbee) ## API and utils ### Generating a new Address ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $my_address = 'TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF'; # Address by default is set in BlockBee Dashboard, yet if you enable the "Address Override" permission when creating the API Key you can set it here. $callback = 'https://example.com/callback/'; $parameters = [ 'payment_id' => 12345 ]; $blockbee_params = [ 'convert' => 1 # You can also add other parameters found in the /create/ documentation https://docs.blockbee.io/#operation/create ]; $api_key = '<your-api-key>'; $bb = new BlockBee\BlockBee($coin, $my_address, $callback, $parameters, $blockbee_params, $api_key); $payment_address = $bb->get_address(); ``` #### Where: * ``$coin`` is the coin you wish to use, from BlockBee's supported currencies (e.g `'btc', 'eth', 'erc20_usdt', ...`) * ``$my_address`` is your own crypto address, where your funds will be sent to. If you already set your address in our [Dashboard](https://dash.blockbee.io/) you can leave this empty. * ``$callback`` is the URL that will be called upon payment * ``$parameters`` is any parameter you wish to send to identify the payment, such as `['order_id' => 1234]` * ``$blockbee_params`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create) * ``$payment_address`` is the newly generated address, to show your customer for payment * ``$api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). > **TIP** >All the params you can provide to `$blockbee_params` can be found in our [API Reference](/api/create-payment-address) for this endpoint. #### Response sample: ``` { "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", "minimum_transaction_coin": 0.008, "status": "success" } ``` > **TIP** >**Getting notified when the user completes the Payment:** Once your customer makes a payment, BlockBee will send a webhook to your `callback`. This webhook information is by default in ``GET`` but you can set it to ``POST`` by setting ``post => 1`` in ``$blockbee_params``. The parameters sent by BlockBee in this webhook can be consulted [here](/webhooks/custom-payment-flow-webhooks) ### Getting notified when the user pays The URL you provided earlier will be called when a user pays, for easier processing of the request we've added the ``process_callback`` helper ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $payment_data = BlockBee\BlockBee::process_callback($_GET); ``` The `$payment_data` will be an array with the following keys: `address_in` - the address generated by our service, where the funds were received `address_out` - your address, where funds were sent `txid_in` - the received TXID `txid_out` - the sent TXID or null, in the case of a pending TX `confirmations` - number of confirmations, or 0 in case of pending TX `value` - the value that your customer paid `value_coin` - the value that your customer paid, in the main coin denomination (e.g `BTC`) `value_forwarded` - the value we forwarded to you, after our fee `value_forwarded_coin` - the value we forwarded to you, after our fee, in the main coin denomination (e.g `BTC`) `coin` - the coin the payment was made in (e.g: `'btc', 'eth', 'erc20_usdt', ...`) `pending` - whether the transaction is pending, if `false` means it's confirmed plus, any values set on `$params` when requesting the address, like the order ID.   From here you just need to check if the value matches your order's value. ### Checking the logs of a request ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $my_address = 'TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF'; # Address by default is set in BlockBee Dashboard, yet if you enable the "Address Override" permission when creating the API Key you can set it here. $callback = 'https://example.com/callback/'; $parameters = [ 'payment_id' => 12345 ]; $blockbee_params = [ 'convert' => 1 # You can also add other parameters found in the /create/ documentation https://docs.blockbee.io/#operation/create ]; $api_key = '<your-api-key>'; $bb = new BlockBee\BlockBee($coin, $my_address, $callback, $parameters, $blockbee_params, $api_key); $data = $bb->check_logs(); ``` > **TIP** >Same parameters as before, the `$data` returned can be checked in our [API Reference](/api/get-payment-logs). #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["callback_url"]=>string(37) "https://example.com?payment_id=123112" ["address_in"]=>string(42) "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB" ["address_out"]=>string(42) "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d" ["notify_pending"]=>bool(true) ["notify_confirmations"]=>int(1) ["priority"]=>string(7) "default" ["callbacks"]=>array(0) { } } ``` ### Generating a QR code ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $my_address = 'TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF'; # Address by default is set in BlockBee Dashboard, yet if you enable the "Address Override" permission when creating the API Key you can set it here. $callback = 'https://example.com/callback/'; $parameters = [ 'payment_id' => 12345 ]; $blockbee_params = [ 'convert' => 1 # You can also add other parameters found in the /create/ documentation https://docs.blockbee.io/#operation/create ]; $api_key = '<your-api-key>'; $bb = new BlockBee\BlockBee($coin, $my_address, $callback, $parameters, $blockbee_params, $api_key); $qrcode = $bb->get_qrcode($value, $size); ``` #### Where: * ``$value`` Value to request the user, in the main coin (BTC, ETH, etc). Optional, pass `false` to not add a value to the QR. * ``$size`` Size of the QR Code image in pixels. Optional, pass `false` to use the default size of 512. > **TIP** >Response is an object with `qr_code` (base64 encoded image data) and `payment_uri` (the value encoded in the QR), see https://docs.blockbee.io/#operation/qrcode for more information. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["qr_code"]=>string(18700) "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" ["payment_uri"]=>string(42) "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB" } ``` #### Usage ```html <img src='data:image/png;base64,<?php echo $qrcode->qr_code; ?>'/> ``` ### Getting service/coin information ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is // Get general service information $info = BlockBee\BlockBee::get_info(); // Get specific coin information $coin_info = BlockBee\BlockBee::get_info('btc', true); ``` #### Where: * The first call gets general service information * The second call gets information for a specific coin (e.g. 'btc', 'eth', 'erc20_usdt', ...) * The second parameter (optional, defaults to `false`) determines whether to include additional details > **TIP** >Response contains service information and coin-specific details when a coin parameter is provided. ### Estimating transaction fees ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $fees = BlockBee\BlockBee::get_estimate($coin, $addresses, $priority); ``` #### Where: * ``$coin`` is the coin you wish to check, from BlockBee's supported currencies (e.g `'btc', 'eth', 'erc20_usdt', ...`) * ``$addresses`` The number of addresses to forward the funds to. Optional, defaults to 1. * ``$priority`` Confirmation priority, needs to be one of `['fast', 'default', 'economic']`. Optional, defaults to `default`. > **TIP** >Response is an object with `estimated_cost` and `estimated_cost_usd`, see https://docs.blockbee.io/#operation/estimate for more information. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["estimated_cost"]=>string(11) "0.000496344" ["estimated_cost_currency"]=> object(stdClass) { ["AED"]=>string(4) "1.12" ["AUD"]=>string(4) "0.46" ["BGN"]=>string(4) "0.55" # ... remaining FIAT currencies } } ``` ### Converting between cryptocurrencies and FIAT ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $conversion = BlockBee\BlockBee::get_convert($coin, $value, $from); ``` #### Where: * ``$coin`` the target currency to convert to, from BlockBee's supported currencies (e.g `'btc', 'eth', 'erc20_usdt', ...`) * ``$value`` Value to convert in `from`. * ``$from`` Currency to convert from, FIAT or crypto. > **TIP** >Response is an object with `value_coin` and `exchange_rate`, see https://docs.blockbee.io/#operation/convert for more information. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["value_coin"]=>string(1) "3" ["exchange_rate"]=>string(8) "0.999467" } ``` ### Getting supported coins ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coins = BlockBee\BlockBee::get_supported_coins(); ``` > **TIP** >Response is an array with all supported coins. #### Response sample: ```php array(65) { [0]=>string(3) "btc" [1]=>string(3) "bch" [2]=>string(3) "ltc" [3]=>string(4) "doge" [4]=>string(11) "bep20_1inch" [5]=>string(9) "bep20_ada" # ...remaining supported cryptocurrencies or tokens } ``` ## Checkout ### Checkout Payments #### Requesting Payment ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $bb = new BlockBee\Checkout($api_key, $parameters, $blockbee_params); $payment_address = $bb->payment_request($redirect_url, $notify_url, $value); ``` #### Where: * ``$api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``$parameters`` is any parameter you wish to send to identify the payment, such as `['order_id' => 1234]` * ``$blockbee_params`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/payment) * ``$redirect_url`` URL in your platform, where the user will be redirected to following the payment. Should be able to process the payment using the `success_token`. * ``$notify_url`` URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn. * ``$value`` amount in currency set in Payment Settings you want to receive from the user. > **TIP** >All the params you can provide to `$blockbee_params` can be found in our [API Reference](/api/create-checkout) for this endpoint. #### Response sample: ```php array(2) { ["status"]=>string(7) "success" ["success_token"]=>string(64) "eQQqUwGJXqyAEGPNBOE4KeoKvMmbmhkaCz0QHMoa7fI43KYnQ2DEGQT8gAmV4ELt" ["payment_url"]=>string(65) "https://pay.blockbee.io/payment/19TCsSAPTdrmLDfY7awdA5csfPvbk5Ij/" ["payment_id"]=>string(32) "19TCsSAPTdrmLDfY7awdA5csfPvbk5Ij" } ``` > **TIP** >**Getting notified when the user completes the Payment:** When receiving payments, you have the option to receive them in either the ``notify_url`` or the ``redirect_url``, but adding the ``redirect_url`` is required, refer to our [documentation](/webhooks/checkout-payments-webhook). #### Payment Logs Fetch Payment information and IPN logs. ```php require 'vendor/autoload.php'; // Where your vendor directory is $logs = \BlockBee\Checkout::payment_logs($token, $api_key); ``` #### Where: * ```token``` is the `payment_id` returned by the payment creation endpoint. #### Response sample: ```php object(stdClass)#4 (7) { ["status"]=>string(7) "success" ["is_paid"]=>bool(false) ["is_pending"]=>+bool(false) ["is_expired"]=>bool(false) ["is_partial"]=>bool(false) ["payment_data"]=> array(10) { [0]=>object(stdClass) { ["value"]=>string(1) "5" ["value_paid"]=>string(1) "0" ["value_outstanding"]=>string(1) "5" ["exchange_rate"]=>string(1) "1" ["coin"]=>string(10) "bep20_usdt" ["txid"]=> array(0) { } } # ... other payment options } ["notifications"]=>array(0) { # IPNs will appear here } } ``` ### Checkout Deposits #### Requesting Deposit ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $bb = new BlockBee\Checkout($api_key, $parameters, $blockbee_params); $payment_address = $bb->deposit_request($notify_url); ``` #### Where: * ``$api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``$parameters`` is any parameter you wish to send to identify the payment, such as `['order_id' => 1234]` * ``$blockbee_params`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/deposit) * ``$notify_url`` URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn. > **TIP** >All the params you can provide to `$blockbee_params` can be found in our [API Reference](/api/create-deposit) for this endpoint. #### Response sample: ```php array(1) { ["payment_url"]=> object(stdClass) { ["status"]=>string(7) "success" ["payment_url"]=>string(65) "https://pay.blockbee.io/deposit/8yHRn1dKn3WrtwccVpsBUCceMXSRbCki/" ["payment_id"]=>string(32) "8yHRn1dKn3WrtwccVpsBUCceMXSRbCki" } } ``` > **TIP** >**Getting notified when the user completes the Payment:** When receiving deposits, you must provide a ``notify_url`` where our system will send an IPN every time a user makes a deposit, refer to our [documentation](/webhooks/checkout-deposits-webhook). #### Deposit Logs Fetch Deposit information and IPN logs. ```php require 'vendor/autoload.php'; // Where your vendor directory is $logs = \BlockBee\Checkout::deposit_logs($token, $api_key); ``` #### Where: * ```token``` is the `payment_id` returned by the deposit creation endpoint. #### Response sample: ```php array(1) { ["payment_url"]=> object(stdClass) { ["status"]=>string(7) "success" ["payment_url"]=>string(65) "https://pay.blockbee.io/deposit/8yHRn1dKn3WrtwccVpsBUCceMXSRbCki/" ["payment_id"]=>string(32) "8yHRn1dKn3WrtwccVpsBUCceMXSRbCki" } } object(stdClass) { ["status"]=>string(7) "success" ["deposits"]=>array(0) {} ["total_deposited"]=>string(1) "0" ["currency"]=>string(4) "USDT" ["notifications"]=>array(0) {} } ``` ## Payouts ### Create Payout / Payout Request Use this function to create [Payouts](https://docs.blockbee.io/#tag/Payouts). ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $requests = [ '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.2, '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.3, ] $process = false // default $create_payout = BlockBee\BlockBee::create_payout($coin, $requests, $api_key, $process); ``` #### Where: * ``$coin`` The cryptocurrency you want to request the Payout in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``$requests`` Address(es) together with the amount that must be sent. * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$process`` If the Payout Requests will be sent right away. Defaults to `false`. **Note**: if `true` will instantly queue the payouts to be sent to the destination addresses. #### Response sample: ```php # If $process=true object(stdClass) { ["status"]=>string(7) "success" ["payout_info"]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["status"]=>string(7) "Created" ["from"]=>string(0) "" ["requests"]=>object(stdClass) { ["0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d"]=>string(20) "4.000000000000000000" } ["total_requested"]=>string(1) "4" ["total_with_fee"]=>string(4) "4.04" ["total_fiat"]=>string(0) "" ["fee"]=>string(4) "0.04" ["coin"]=>string(10) "bep20_usdt" ["txid"]=>string(0) "" # Once the Payout is fulfilled will have a txid. ["timestamp"]=>string(19) "05/03/2024 15:10:00" } ["queued"]=>bool(true) } # If $process=false object(stdClass) { ["status"]=> string(7) "success" ["request_ids"]=> array(2) { [0]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" [1]=>string(36) "d9925105-ea5f-4661-8d01-505096212ac5" } } ``` ### List Payouts / Payout Requests List all Payouts or Payout Requests in your account. **Note:** If `$requests` is `true` it will fetch a Payout Requests list. ```php <?php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $list_payouts = BlockBee\BlockBee::list_payouts($coin, $status, $page, $api_key, $requests); ``` #### Where: * ``$coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``$status`` The status of the Payout / Payout Request. Possible statuses are: * Payout Request: [`all`, `pending`, `rejected`, `processing`, `done`] * Payout: [`created`, `processing`, `done`, `error`] * ``$page`` This endpoint is paginated and will show only `50` items per page. Defaults to `1`. * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$requests`` If `true` will fetch Payout Requests, otherwise will fetch Payouts. Defaults to `false`. #### Response sample: ```php # If $requests is false object(stdClass) { ["status"]=>string(7) "success" ["payouts"]=>array(50) { [0]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["status"]=>string(4) "Done" ["total_requested"]=>string(3) "0.5" ["total_with_fee"]=>string(5) "0.505" ["fee"]=>string(5) "0.005" ["coin"]=>string(10) "bep20_usdt" ["timestamp"]=>string(19) "13/03/2024 14:26:50" } # ... Remaining 49 Payouts } ["num_pages"]=>int(2) } # If #requests is true object(stdClass) { ["status"]=>string(7) "success" ["payout_requests"]=>array(50) { [0]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["coin"]=>string(10) "bep20_usdt" ["address"]=>string(42) "0x18B211A1Ba5880C7d62C250B6441C2400d588589" ["value"]=>string(3) "0.3" ["status"]=>string(7) "Pending" ["timestamp"]=>string(19) "13/03/2024 14:27:42" } } ["num_pages"]=>int(2) } ``` ### Get Payout Wallet Gets your Payout Wallet for the specified `coin`. Can algo get the balance. ```php require 'vendor/autoload.php'; // Where your vendor directory is $coin = 'trc20_usdt'; $wallet = BlockBee\BlockBee::get_payout_wallet($coin, $api_key, $balance) ``` #### Where: * ``$coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$balance`` If `true` will also fetch the balance of the address. #### Response sample: ```php object(stdClass) { ["address"]=>string(42) "0x18B211A1Ba5880C7d62C250B6441C2400d588589" ["balance"]=>string(20) "3.72" # To receive this $balance must be true } ``` ### Create Payout with Payout Request ID(s) With this function you can create a Payout in the `created` status by providing an array with the Payout Requests `ID`. ```php require 'vendor/autoload.php'; // Where your vendor directory is $ids = [52216, 52215] $payout = BlockBee\BlockBee::create_payout_by_ids($api_key, $ids) ``` #### Where: * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$ids`` its an array with the Payout Requests `ID`. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["payout_info"]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["status"]=>string(7) "Created" ["from"]=>string(0) "" ["requests"]=>object(stdClass) { ["0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d"]=>string(20) "4.000000000000000000" } ["total_requested"]=>string(1) "4" ["total_with_fee"]=>string(4) "4.04" ["total_fiat"]=>string(0) "" ["fee"]=>string(4) "0.04" ["coin"]=>string(10) "bep20_usdt" ["txid"]=>string(0) "" # Once the Payout is fulfilled will have a txid. ["timestamp"]=>string(19) "05/03/2024 15:10:00" } } ``` ### Process Payout by ID By default, a Payout when created will be in `created` state. With this function you may finish it using its `ID`. ```php $id = 51621 $wallet = BlockBee\BlockBee::process_payout($api_key, $id) ``` #### Where: * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$id`` Its the `ID` of the Payout you wish to fulfill. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["payout_info"]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["status"]=>string(7) "Created" ["from"]=>string(0) "" ["requests"]=>object(stdClass) { ["0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d"]=>string(20) "4.000000000000000000" } ["total_requested"]=>string(1) "4" ["total_with_fee"]=>string(4) "4.04" ["total_fiat"]=>string(0) "" ["fee"]=>string(4) "0.04" ["coin"]=>string(10) "bep20_usdt" ["txid"]=>string(0) "" # Once the Payout is fulfilled will have a txid. ["timestamp"]=>string(19) "05/03/2024 15:10:00" } ["queued"]=>bool(true) } ``` ### Check the Payout status Will return all important information regarding a Payout, specially its status. ```php $id = 51621 $status = BlockBee\BlockBee::check_payout_status($api_key, $id) ``` #### Where: * ``$api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``$id`` Its the `ID` of the Payout you wish to check. #### Response sample: ```php object(stdClass) { ["status"]=>string(7) "success" ["payout_info"]=>object(stdClass) { ["id"]=>string(36) "3825d29b-7a8f-47da-8623-e99850674247" ["status"]=>string(4) "Done" ["from"]=>string(42) "0x18B211A1Ba5880C7d62C250B6441C2400d588589" ["requests"]=>object(stdClass) { ["0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d"]=>string(20) "0.200000000000000000" ["0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF"]=>string(20) "0.300000000000000000" } ["total_requested"]=>string(3) "0.5" ["total_with_fee"]=>string(5) "0.505" ["total_fiat"]=>string(0) "" ["fee"]=>string(5) "0.005" ["coin"]=>string(10) "bep20_usdt" ["txid"]=>string(66) "0x958d4ffbbfaf321fbb0b4a4af31f8976cc69c162d7f741ff5702bd0927dfe2e8" ["timestamp"]=>string(19) "05/03/2024 15:00:00" } } ``` ## Changelog #### 1.0.0 * Initial release. #### 1.0.1 * Minor bugfixes. #### 1.1.0 * Added Payouts * Minor bugfixes #### 1.1.1 * Minor bugfixes #### 1.1.2 * Minor bugfixes #### 2.0.0 * Automated Payouts * Support to BlockBee Checkout page * Various improvements #### 2.0.1 * Minor bugfixes #### 2.1.0 * Minor bugfixes * Improve error handling #### 2.1.1 * Minor bugfixes #### 2.1.2 * Minor improvements ### Breaking Changes #### 2.0.0 * `create_payout` parameters were changed and will require you to update your code. --- # BlockBee's Python Library > Source: https://docs.blockbee.io/libraries/python > Description: Python implementation of BlockBee's payment gateway ## Requirements * `Python >= 3.0` * `Requests >= 2.20` ## Installation ```shell script pip install python-blockbee ``` > **TIP** >**Full Source Code Available:** You can find the complete source code, examples, and contribute to this library on our official GitHub repository: [github.com/blockbee-io/python-blockbee](https://github.com/blockbee-io/python-blockbee) ## API and utils ### Importing in your project file ```python from blockbee import BlockBeeHelper, BlockBeeCheckoutHelper ``` ### Getting coin information ```python from blockbee import BlockBeeHelper # Get specific coin information coin_info = BlockBeeHelper.get_info('btc') ``` #### Where: * The parameter is a specific coin you want information about (e.g. 'btc', 'eth', 'erc20_usdt', ...) > **TIP** >Response contains detailed information about the specified coin. ### Generating a new Address ```python from blockbee import BlockBeeHelper bb = BlockBeeHelper(coin, own_address, callback, parameters, bb_params, api_key) address = bb.get_address()['address_in'] ``` #### Where: * ``coin`` is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...). * ``own_address`` is your own crypto address, where your funds will be sent to. * ``callback`` is the URL that will be called upon payment. * ``params`` is any parameter you wish to send to identify the payment, such as `{orderId: 1234}`. * ``bb_params`` parameters that will be passed to BlockBee. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``address`` is the newly generated address, to show your customer for payment. > **TIP** >All the params you can provide to `bb_params` can be found in our [API Reference](/api/create-payment-address) for this endpoint. #### Response sample: ```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", "minimum_transaction_coin": 0.008, "status": "success" } ``` > **TIP** >**Getting notified when the user completes the Payment:** Once your customer makes a payment, BlockBee will send a webhook to your `callbackUrl`. This webhook information is by default in ``GET`` but you can se it to ``POST`` by setting ``post: 1`` in ``blockbeeParams``. The parameters sent by BlockBee in this webhook can be consulted [here](/webhooks/custom-payment-flow-webhooks) ### Checking the logs of a request ```python from blockbee import BlockBeeHelper bb = BlockBeeHelper(coin, own_address, callback, parameters, bb_params, api_key) data = bb.get_logs() ``` > **TIP** >Same parameters as before, the `data` returned can be checked in our [API Reference](/api/get-payment-logs). #### Response sample: ```json { "status": "success", "callback_url": "https://example.com/?order_id=1235", "address_in": "0x58e90D31530A5566dA97e34205730323873eb88B", "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d", "notify_pending": false, "notify_confirmations": 1, "priority": "default", "callbacks": [] } ``` ### Generating a QR code ```python from blockbee import BlockBeeHelper bb = BlockBeeHelper(coin, own_address, callback, parameters, bb_params, api_key) qr_code = bb.get_qrcode(value, size) ``` #### Where: * ``value`` is the value requested to the user in the coin to which the request was done. **Optional**, can be empty if you don't wish to add the value to the QR Code. * ``size`` Size of the QR Code image in pixels. Optional, leave empty to use the default size of 512. > **TIP** >Response is an object with `qr_code` (base64 encoded image data) and `payment_uri` (the value encoded in the QR), see https://docs.blockbee.io/#operation/qrcode for more information. #### Response sample: ```json { "status": "success", "qr_code": "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", "payment_uri": "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB" } ``` #### Usage ```html <img src={`data:image/png;base64,{{qr_code}}`}/> ``` ### Estimating transaction fees ```python from blockbee import BlockBeeHelper bb = BlockBeeHelper(coin, own_address, callback_url, params, bb_params, api_key) fees = bb.get_estimate(coin, api_key=api_key, addresses=addresses, priority=priority) ``` #### Where: * ``coin`` is the coin you wish to check, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...) * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``addresses`` The number of addresses to forward the funds to. Optional, defaults to 1. * ``priority`` Confirmation priority, (check [this](/kb/developers/api/what-is-the-priority-parameter) article to learn more about it). Optional, defaults to ``default``. > **TIP** >Response is an object with ``estimated_cost`` and ``estimated_cost_usd``, check this endpoint [API Reference](/api/estimate-fees) for more information. #### Response sample: ```json { "status": "success", "estimated_cost": "0.00637010", "estimated_cost_currency": { "AED": "0.03", "AUD": "0.01", "BGN": "0.01", "BRL": "0.04" } } ``` ### Converting between coins and fiat ```python from blockbee import BlockBeeHelper bb = BlockBeeHelper(coin, own_address, callback_url, params, bb_params, api_key) conversion = bb.get_conversion(from_coin, value) ``` #### Where: * ``from_coin`` currency to convert from, FIAT or crypto. * ``value`` value to convert in `from_coin`. > **TIP** >Response is an object with ``value_coin`` and ``exchange_rate``, check this endpoint [API Reference](/api/convert-price-by-ticker) for more information. #### Response sample: ```json { "status": "success", "value_coin": "241.126", "exchange_rate": "0.803753" } ``` ### Getting supported coins ```python from blockbee import BlockBeeHelper supportedCoins = BlockBeeHelper.get_supported_coins() ``` > **TIP** >Response is an array with all supported coins. #### Response sample: ```json { "btc": { "coin": "Bitcoin", "logo": "https://api.cryptapi.io/media/token_logos/btc.png", "ticker": "btc", "minimum_transaction": 8000, "minimum_transaction_coin": "0.00008000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00002518" }, "bch": { "coin": "Bitcoin Cash", "logo": "https://api.cryptapi.io/media/token_logos/bch.png", "ticker": "bch", "minimum_transaction": 50000, "minimum_transaction_coin": "0.00050000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00000305" } } ``` ## Checkout ### Checkout Payments #### Requesting Payment ```python from blockbee import BlockBeeCheckoutHelper bb = BlockBeeCheckoutHelper(api_key, params, bb_params) payment_page = bb.payment_request(redirect_url, value) ``` #### Where: * ``api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``params`` is any parameter you wish to send to identify the payment, such as `{'order_id': 1234}`. * ``bb_params`` parameters that will be passed to BlockBee. * ``redirect_url`` URL in your platform, where the user will be redirected to following the payment. Should be able to process the payment using the `success_token`. * ``value`` amount in currency set in Payment Settings you want to receive from the user. > **TIP** >All the params you can provide to `bb_params` can be found in our [API Reference](/api/create-checkout) for this endpoint. #### Payment samples: ```json { "status": "success", "success_token": "G4asA2xwEr0UeY2IZqlZjX3IYrNofmnIAkzHPAoxmpmlYP9ZLTvQUolKN0X27Z0B", "payment_url": "https://pay.blockbee.io/payment/OcRrZGsKQFGsoi0asqZkr97WbitMxFMb/", "payment_id": "OcRrZGsKQFGsoi0asqZkr97WbitMxFMb" } ``` > **TIP** >**Getting notified when the user completes the Payment:** When receiving payments, you have the option to receive them in either the ``notify_url`` or the ``redirect_url``, but adding the ``redirect_url`` is required, refer to our [documentation](/webhooks/checkout-payments-webhook). #### Payment Logs Fetch Payment information and IPN logs. ```python from blockbee import BlockBeeCheckoutHelper logs = BlockBeeCheckoutHelper.payment_logs(token, api_key) ``` #### Where: * ```token``` is the `payment_id` returned by the payment creation endpoint. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). #### Response sample: ```json { "status": "success", "is_paid": false, "is_pending": false, "is_expired": false, "is_partial": false, "payment_data": [ { "value": "0.000137", "value_paid": "0", "value_outstanding": "0.000137", "exchange_rate": "0.0000137489", "coin": "btc", "txid": [] } ], "notifications": [] } ``` ### Checkout Deposits #### Requesting Deposit ```python from blockbee import BlockBeeCheckoutHelper bb = BlockBeeCheckoutHelper(api_key, params, bb_params) deposit_page = bb.deposit_request(notify_url) ``` #### Where: * ``api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``params`` is any parameter you wish to send to identify the payment, such as `{'order_id': 1234}`. * ``bb_params`` parameters that will be passed to BlockBee. * ``notify_url`` URL in your platform, where the webhook will be sent notifying that a deposit was done. Parameters are available [here](/webhooks/checkout-payments-webhook). > **TIP** >All the params you can provide to `bb_params` can be found in our [API Reference](/api/create-deposit) for this endpoint. #### Response sample: ```json { "status": "success", "payment_url": "https://pay.blockbee.io/deposit/jv12du8IWqS96WVDjZK2J285WOBOBycc/", "payment_id": "jv12du8IWqS96WVDjZK2J285WOBOBycc" } ``` > **TIP** >**Getting notified when the user completes the Payment:** When receiving payments, you have the option to receive them in either the ``notify_url`` or the ``redirect_url``, but adding the ``redirect_url`` is required, refer to our [documentation](/webhooks/checkout-deposits-webhook). #### Deposit Logs Fetch Deposit information and IPN logs. ```python from blockbee import BlockBeeCheckoutHelper logs = BlockBeeCheckoutHelper.deposit_logs(token, api_key) ``` #### Where: * ```token``` is the `payment_id` returned by the deposit creation endpoint. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). #### Response sample: ```json { "status": "success", "deposits": [], "total_deposited": "0", "currency": "USDT", "notifications": [] } ``` ## Payouts ### Create Payout / Payout Request Use this function to create [Payouts](https://docs.blockbee.io/#tag/Payouts). ```python from blockbee import BlockBeeHelper coin = 'polygon_matic' requests = { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d': 0.5, '0x18B211A1Ba5880C7d62C250B6441C2400d588589': 0.1 } create_payout = BlockBeeHelper.create_payout(coin, requests, api_key=api_key, process=process) ``` #### Where: * ``coin`` The cryptocurrency you want to request the Payout in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``requests`` Address(es) together with the amount that must be sent. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``process`` If the Payout Requests will be sent right away. Defaults to `False`. **Note**: if `True` will instantly queue the payouts to be sent to the destination addresses. #### Response sample: If `process` is `false`. ```json { "status": "success", "request_ids": [ "42d5245e-0a29-402a-9a7e-355e38f1d81d", "080a546e-4045-4c73-870c-4d9ec08c9cab" ] } ``` If `process` is `true`. ```json { "status": "success", "payout_info": { "id": "88e5eacc-d5a5-4b8a-8133-e23136151b7c", "status": "Pending Payment", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.5", "0x18B211A1Ba5880C7d62C250B6441C2400d588589": "0.1" }, "total_requested": "0.6", "total_with_fee": "0.603", "error": "None", "blockchain_fee": 0, "fee": "0.003", "coin": "bep20_usdt", "txid": "", "timestamp": "23/04/2024 11:13:49" }, "queued": true } ``` ### List Payouts / Payout Requests List all Payouts or Payout Requests in your account. **Note:** If `payout_request` is `True` it will fetch a Payout Requests list. ```python from blockbee import BlockBeeHelper list_payouts = BlockBeeHelper.list_payouts(coin, status=status, page=page, api_key=api_key, payout_request=payout_request) ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``status`` The status of the Payout / Payout Request. Possible statuses are: * Payout Request: [`all`, `pending`, `rejected`, `processing`, `done`] * Payout: [`created`, `processing`, `done`, `error`] * ``page`` This endpoint is paginated and will show only `50` items per page. Defaults to `1`. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``payout_request`` If `True` will fetch Payout Requests, otherwise will fetch Payouts. Defaults to `False`. #### Response sample: ```json { "status": "success", "payouts": [ { "id": "88e5eacc-d5a5-4b8a-8133-e23136151b7c", "status": "Done", "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_matic", "timestamp": "13/03/2024 17:48:39" } ], "num_pages": 1 } ``` ### Get Payout Wallet Gets your Payout Wallet for the specified `coin`. Can algo get the balance. ```python from blockbee import BlockBeeHelper wallet = BlockBeeHelper.get_payout_wallet(coin, api_key=api_key, balance=balance) ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``balance`` If `True` will also fetch the balance of the address. #### Response sample: ```json { "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "balance": "2.7" } ``` ### Create Payout with Payout Request ID(s) With this function you can create a Payout in the `created` status by providing an array with the Payout Requests `ID`. ```python from blockbee import BlockBeeHelper ids = [52211, 52212] payout = BlockBeeHelper.create_payout_by_ids(api_key=api_key, payout_ids=payout_ids) ``` #### Where: * ``payout_ids`` its an array with the Payout Requests `ID`. #### Response sample: ```json { "status": "success", "payout_info": { "id": "88e5eacc-d5a5-4b8a-8133-e23136151b7c", "status": "Created", "from": "", "requests": { "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000", "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000" }, "total_requested": "0.5", "total_with_fee": "0.505", "total_fiat": "", "fee": "0.005", "coin": "bep20_usdt", "txid": "", "timestamp": "05/03/2024 15:00:00" } } ``` ### Process Payout by ID By default, a Payout when created will be in `created` state. With this function you may finish it using its `ID`. ```python from blockbee import BlockBeeHelper payout = BlockBeeHelper.process_payout(api_key=api_key, payout_id=payout_id) ``` #### Where: * ``payout_id`` Its the `ID` of the Payout you wish to fulfill. #### Response sample: ```json { "status": "success", "queued": true } ``` ### Check the Payout status Will return all important information regarding a Payout, specially its status. ```python from blockbee import BlockBeeHelper payout_id = 51621 status = BlockBeeHelper.check_payout_status(api_key=api_key, payout_id=payout_id) ``` #### Where: * ``payout_id`` Its the `ID` of the Payout you wish to check. #### Response sample: ```json { "status": "success", "payout_info": { "id": "88e5eacc-d5a5-4b8a-8133-e23136151b7c", "status": "Done", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.500000000000000000", "0x18B211A1Ba5880C7d62C250B6441C2400d588589": "0.100000000000000000" }, "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_matic", "txid": "0xf9aa1618a7e460f8c68b6a02369b5058282c53a4ee23f967abef0d35203f328c", "timestamp": "13/03/2024 18:10:35" } } ``` ## Changelog #### 1.0.0 * Initial Release #### 1.0.1 * Minor fixes #### 1.0.2 * Minor fixes #### 1.0.3 * Fix import * Minor fixes #### 1.1.0 * Added Payouts * Minor bugfixes #### 1.1.1 * Minor bugfixes #### 2.0.0 * Automated Payouts * Support to BlockBee Checkout page * Various improvements #### 2.0.1 * Minor bugfixes #### 2.1.0 * Minor bugfixes * Improve error handling #### 2.1.1 * Minor improvements ### Breaking Changes #### 2.0.0 * `create_payout` parameters were changed and will require you to update your code. --- # BlockBee's Ruby Library > Source: https://docs.blockbee.io/libraries/ruby > Description: Ruby implementation of BlockBee's payment gateway ## Requirements ``` Ruby >= 3 ``` ## Installation Install the gem and add to the application's Gemfile by executing: ``` bundle add blockbee ``` If bundler is not being used to manage dependencies, install the gem by executing: ``` gem install blockbee ``` [RubyGem Page](https://rubygems.org/gems/blockbee/) ## API and utils ### Importing in your project file ```ruby require 'blockbee' ``` ### Get information (service of regarding a cryptocurrency) ```ruby require 'blockbee' info = BlockBee::API.get_info(coin, prices) # or if you wish to get full BlockBee service information info = BlockBee::API.get_info(nil, prices) ``` #### Where * ``coin`` is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...). * ``prices`` by default `0`. If `1` will return the prices of the cryptocurrencies converted to all supported FIAT currencies. ### Generating a new Address ```ruby require 'blockbee' blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params) address = blockbee_helper.get_address # or address['address_in'] if you just wish the address string ``` #### Where: * ``coin`` is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...). * ``callback`` is the URL that will be called upon payment. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``own_address`` (optional) is your own crypto address, where your funds will be sent to. * ``parameters`` (optional) is any parameter you wish to send to identify the payment, such as `{orderId: 1234}`. * ``bb_params`` (optional) parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create). #### Response sample: ```json { "status": "success", "address_in": "0xe10818d4037B7C427109dFbCFC2c8757c0352FE8", "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d", "callback_url": "https://webhook.site/ef8e2859-12a9-4028-8a94-51582e83dd05?order_id=13435", "minimum_transaction_coin": "1.00000000", "priority": "default", "multi_token": true } ``` ### Getting notified when the user pays > Once your customer makes a payment, BlockBee will send a callback to your `callbackUrl`. This callback information is by default in ``GET`` but you can se it to ``POST`` by setting ``post => 1`` in ``bb_params``. The parameters sent by BlockBee in this callback can be consulted here: https://docs.blockbee.io/#operation/confirmedcallbackget ### Checking the logs of a request ```ruby require 'blockbee' blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params) logs = blockbee_helper.get_logs ``` > Same parameters as before, the ```data``` returned can b e checked here: https://docs.blockbee.io/#operation/logs #### Response sample: ```json { "status": "success", "callback_url": "https://example.com/?order_id=1235", "address_in": "0x58e90D31530A5566dA97e34205730323873eb88B", "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d", "notify_pending": false, "notify_confirmations": 1, "priority": "default", "callbacks": [] } ``` ### Generating a QR code ```ruby require 'blockbee' blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params) qrcode = blockbee_helper.get_qrcode(value: value, size: size) ``` #### Where: * ``value`` is the value requested to the user in the coin to which the request was done. **Optional**, can be empty if you don't wish to add the value to the QR Code. * ``size`` Size of the QR Code image in pixels. Optional, leave empty to use the default size of 300. > Response is an object with `qr_code` (base64 encoded image data) and `payment_uri` (the value encoded in the QR), see https://docs.blockbee.io/#operation/qrcode for more information. #### Response sample: ```json { "status": "success", "qr_code": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2HxkiAAAYeklEQVR4nO3daZQdZZkH8Od5q+quvXenO3tCQtg3WQLDOiwi4FEGRA96RhkRlEUd9cw5Ojif/DTOHEcF4YAwntFRhBEHBPWoKAECGNnXSICQBEL23m/fvkvV+8yHut3pEPoSaop6qjv/3wcOSbrurVv3/vutW8/7vMUiQgCgx2jvAMD+DiEEUIYQAihDCAGUIYQAyhBCAGUIIYAyhBBAmdvk35g5sf2IS4S5BxFe5nTPEu8Ri3ceRYwvM9qjRXiWBJ49MU1eJkZCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlDWrE05HvQ9YvRw33Q4kU1iL9mjxvmsxVkqbbBJhn2fihxMjIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMoQQgBlUYr1Tej2ekajXvieTmrbcJs8UYQdSPMbPZ149xkjIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMpYruhPuZ9Ltdu4y6NF66lNZsVk9Q7dZGwkBlCGEAMoQQgBlCCGAMoQQQBlCCKAMIQRQhhACKEMIAZQ1K9bHWERWr0cnc6vgNL/MmUh9efhkjidGQgBlCCGAMoQQQBlCCKAMIQRQhhACKEMIAZRFaepNs2QaNONtEdZtOFbvqY33oWbiYtYYCQGUIYQAyhBCAGUIIYAyhBBAGUIIoAwhBFCGEAIoa1asn85MbF1NtxYegXpFOALsWDI3fsZICKAMIQRQhhACKEMIAZQhhADKEEIAZQghgDKEEEBZlGJ9EzEWvhMryMa4Ane8dX/1lQ1wBCKIUN/HSAigDCEEUIYQAihDCAGUIYQAyhBCAGUIIYCymOuEqZXMms2JLbOdTAEt3lJtjHXYeMV7MCPsM0ZCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMr2l2J9vOItIiezzHMyNxKPMMFA/QbX6guNYyQEUIYQAihDCAGUIYQAyhBCAGUIIYAyhBBAGSdT2IlXMh26EUQ7MjGW49K8Wm4yTb3qtU0s/gsw8yCEAMoQQgBlCCGAMoQQQBlCCKAMIQRQhhACKItSrE8z3fKuet05AvVVw5PpkI79iWKEkRBAGUIIoAwhBFCGEAIoQwgBlCGEAMoQQgBlzeqEAJAAjIQAyhBCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlP0fDDJ0PYOZxyEAAAAASUVORK5CYII=", "payment_uri": "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB" } ``` #### Usage ```html.erb <img src={"data:image/png;base64,#{qr_code}"}/> ``` ### Estimating transaction fees ```ruby require 'blockbee' estimation = BlockBee::API.get_estimate(coin, addresses, priority) ``` #### Where: * ``coin`` is the coin you wish to check, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...) * ``addresses`` The number of addresses to forward the funds to. Optional, defaults to 1. * ``priority`` Confirmation priority, (check [this](/kb/developers/api/what-is-the-priority-parameter) article to learn more about it). Optional, defaults to ``default``. > Response is an object with ``estimated_cost`` and ``estimated_cost_usd``, see https://docs.blockbee.io/#operation/estimate for more information. #### Response sample: ```json { "status": "success", "estimated_cost": "0.00637010", "estimated_cost_currency": { "AED": "0.03", "AUD": "0.01", "BGN": "0.01", "BRL": "0.04" } } ``` ### Converting between coins and fiat ```ruby require 'blockbee' blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params) conversion = blockbee_helper.get_conversion(from_coin, value) ``` #### Where: * ``value`` value to convert in `from`. * ``from_coin`` currency to convert from, FIAT or crypto. > Response is an object with ``value_coin`` and ``exchange_rate``, see https://docs.blockbee.io/#operation/convert for more information. #### Response sample: ```json { "status": "success", "value_coin": "241.126", "exchange_rate": "0.803753" } ``` ### Getting supported coins ```ruby require 'blockbee' supported_coins = BlockBee::API.get_supported_coins ``` > Response is an array with all supported coins. #### Response sample: ```json { "btc": { "coin": "Bitcoin", "logo": "https://api.cryptapi.io/media/token_logos/btc.png", "ticker": "btc", "minimum_transaction": 8000, "minimum_transaction_coin": "0.00008000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00002518" }, "bch": { "coin": "Bitcoin Cash", "logo": "https://api.cryptapi.io/media/token_logos/bch.png", "ticker": "bch", "minimum_transaction": 50000, "minimum_transaction_coin": "0.00050000", "minimum_fee": 546, "minimum_fee_coin": "0.00000546", "fee_percent": "1.000", "network_fee_estimation": "0.00000305" } } ``` ## Checkout ### Requesting Payment ```ruby require 'blockbee' blockbee_helper = BlockBee::Checkout.new(notify_url: NOTIFY_URL, api_key: API_KEY, parameters: { 'order_id': 2022 }, bb_params: { 'post' => 1 }) payment_page = blockbee_helper.payment_request(redirect_url, value) ``` #### Where: * ``api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``parameters`` is any parameter you wish to send to identify the payment, such as `{'order_id': 1234}`. * ``bb_params`` parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create). * ``redirect_url`` URL in your platform, where the user will be redirected to following the payment. Should be able to process the payment using the `success_token`. * ``notify_url`` URL in your platform, where the IPN will be sent notifying that a payment was completed. Parameters are available here: https://docs.blockbee.io/#operation/paymentipn. * ``value`` amount in currency set in Payment Settings you want to receive from the user. #### Getting notified when the user completes the Payment > When receiving payments, you have the option to receive them in either the ``notify_url`` or the ``redirect_url``, but adding the ``redirect_url`` is required (refer to our documentation at https://docs.blockbee.io/#operation/paymentipn). #### Payment samples: ```json { "status": "success", "success_token": "G4asA2xwEr0UeY2IZqlZjX3IYrNofmnIAkzHPAoxmpmlYP9ZLTvQUolKN0X27Z0B", "payment_url": "https://pay.blockbee.io/payment/OcRrZGsKQFGsoi0asqZkr97WbitMxFMb/", "payment_id": "OcRrZGsKQFGsoi0asqZkr97WbitMxFMb" } ``` ### Payment Logs Fetch Payment information and IPN logs. ```ruby require 'blockbee' logs = BlockBee::Checkout.payment_logs(token, api_key) ``` #### Where: * ```token``` is the `payment_id` returned by the payment creation endpoint. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). #### Response sample: ```json { "status": "success", "is_paid": false, "is_pending": false, "is_expired": false, "is_partial": false, "payment_data": [ { "value": "0.000137", "value_paid": "0", "value_outstanding": "0.000137", "exchange_rate": "0.0000137489", "coin": "btc", "txid": [] } ], "notifications": [] } ``` ### Requesting Deposit ```ruby require 'blockbee' blockbee_helper = BlockBee::Checkout.new(notify_url: NOTIFY_URL, api_key: API_KEY, parameters: { 'order_id': 2022 }, bb_params: { 'post' => 1 }) deposit_page = blockbee_helper.deposit_request ``` #### Where: * ``api_key`` is the API Key provided by our [Dashboard](https://dash.blockbee.io/). * ``parameters`` is any parameter you wish to send to identify the payment, such as `{'order_id': 1234}`. * ``bb_params`` parameters that will be passed to BlockBee (check which extra parameters are available here: https://docs.blockbee.io/#operation/deposit). * ``notify_url`` URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn. #### Response sample: ```json { "status": "success", "payment_url": "https://pay.blockbee.io/deposit/jv12du8IWqS96WVDjZK2J285WOBOBycc/", "payment_id": "jv12du8IWqS96WVDjZK2J285WOBOBycc" } ``` ### Deposit Logs Fetch Deposit information and IPN logs. ```ruby require 'blockbee' logs = BlockBee::Checkout.deposit_logs(token, api_key) ``` #### Where: * ```token``` is the `payment_id` returned by the deposit creation endpoint. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). #### Response sample: ```json { "status": "success", "deposits": [], "total_deposited": "0", "currency": "USDT", "notifications": [] } ``` ## Payouts ### Create Payout / Payout Request Use this function to create [Payouts](https://docs.blockbee.io/#tag/Payouts). ```ruby require 'blockbee' coin = 'polygon_matic' requests = { '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.5, '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.1 } create_payout = BlockBee::API.create_payout(coin, payout_requests, api_key, process) ``` #### Where: * ``coin`` The cryptocurrency you want to request the Payout in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``requests`` Address(es) together with the amount that must be sent. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``process`` If the Payout Requests will be sent right away. Defaults to `False`. **Note**: if `True` will instantly queue the payouts to be sent to the destination addresses. #### Response sample: If `process` is `false`. ```json { "status": "success", "request_ids": [ "3825d29b-7a8f-47da-8623-e99850674247", "d9925105-ea5f-4661-8d01-505096212ac5" ] } ``` If `process` is `true`. ```json { "status": "success", "payout_info": { "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27", "status": "Created", "from": "", "requests": { "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000", "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000" }, "total_requested": "0.5", "total_with_fee": "0.505", "total_fiat": "", "fee": "0.005", "coin": "bep20_usdt", "txid": "", "timestamp": "05/03/2024 15:00:00" }, "queued": true } ``` ### List Payouts / Payout Requests List all Payouts or Payout Requests in your account. **Note:** If `requests` is `True` it will fetch a Payout Requests list. ```ruby require 'blockbee' list_payouts = BlockBee::API.list_payouts(coin, status, page, api_key, payout_request) ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``status`` The status of the Payout / Payout Request. Possible statuses are: * Payout Request: [`all`, `pending`, `rejected`, `processing`, `done`] * Payout: [`created`, `processing`, `done`, `error`] * ``page`` This endpoint is paginated and will show only `50` items per page. Defaults to `1`. * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``payout_request`` If `True` will fetch Payout Requests, otherwise will fetch Payouts. Defaults to `False`. #### Response sample: ```json { "status": "success", "payouts": [ { "id": "3825d29b-7a8f-47da-8623-e99850674247", "status": "Done", "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_matic", "timestamp": "13/03/2024 17:48:39" } ], "num_pages": 1 } ``` ### Get Payout Wallet Gets your Payout Wallet for the specified `coin`. Can algo get the balance. ```ruby require 'blockbee' wallet = BlockBee::API.get_payout_wallet(coin, api_key, balance) ``` #### Where: * ``coin`` The cryptocurrency you want to request the lists in (e.g `btc`, `eth`, `erc20_usdt`, ...). * ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/). * ``balance`` If `True` will also fetch the balance of the address. #### Response sample: ```json { "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "balance": "2.7" } ``` ### Create Payout with Payout Request ID(s) With this function you can create a Payout in the `created` status by providing an array with the Payout Requests `ID`. ```ruby require 'blockbee' payout_ids = [52211, 52212] payout = BlockBee::API.create_payout_by_ids(api_key, payout_ids) ``` #### Where: * ``payout_ids`` its an array with the Payout Requests `ID`. #### Response sample: ```json { "status": "success", "payout_info": { "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27", "status": "Created", "from": "", "requests": { "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000", "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000" }, "total_requested": "0.5", "total_with_fee": "0.505", "total_fiat": "", "fee": "0.005", "coin": "bep20_usdt", "txid": "", "timestamp": "05/03/2024 15:00:00" } } ``` ### Process Payout by ID By default, a Payout when created will be in `created` state. With this function you may finish it using its `ID`. ```ruby require 'blockbee' payout = BlockBee::API.process_payout(api_key, payout_ids) ``` #### Where: * ``payout_ids`` Its the `ID` (or multiple `ID`) of the Payout you wish to fulfill. #### Response sample: ```json { "status": "success", "payout_info": { "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27", "status": "Created", "from": "", "requests": { "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000", "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000" }, "total_requested": "0.5", "total_with_fee": "0.505", "total_fiat": "", "fee": "0.005", "coin": "bep20_usdt", "txid": "", "timestamp": "05/03/2024 15:00:00" }, "queued": true } ``` ### Check the Payout status Will return all important information regarding a Payout, specially its status. ```ruby require 'blockbee' payout_id = 51621 status = BlockBee::API.check_payout_status(api_key, payout_id) ``` #### Where: * ``payout_id`` Its the `ID` of the Payout you wish to check. #### Response sample: ```json { "status": "success", "payout_info": { "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27", "status": "Done", "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589", "requests": { "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.500000000000000000", "0x18B211A1Ba5880C7d62C250B6441C2400d588589": "0.100000000000000000" }, "total_requested": "0.6", "total_with_fee": "0.606", "total_fiat": "", "fee": "0.006", "coin": "polygon_matic", "txid": "0xf9aa1618a7e460f8c68b6a02369b5058282c53a4ee23f967abef0d35203f328c", "timestamp": "13/03/2024 18:10:35" } } ``` ## Testing ### Option 1: Using .env file (Recommended) 1. Copy the example environment file: ```bash cp .env.example .env ``` 2. Edit `.env` with your actual API credentials: ```bash # Required: Your BlockBee API Key from https://dash.blockbee.io/ BLOCKBEE_API_KEY=your-actual-api-key-here # Required: Callback URL for payment notifications BLOCKBEE_CALLBACK_URL=https://your-domain.com/webhook ``` 3. Install dependencies and run tests: ```bash bundle install bundle exec rake test ``` ### Option 2: Using environment variables Alternatively, you can set environment variables directly: ```bash export BLOCKBEE_API_KEY="your-api-key-here" export BLOCKBEE_CALLBACK_URL="https://your-domain.com/webhook" bundle exec rake test ``` **Note:** If no API key is provided, only basic tests (like version check) will run. The `.env` file is automatically ignored by git to keep your credentials secure. ## Help Need help? Contact us @ https://blockbee.io/contacts/ --- # What is the difference between API Key V1 and V2? > Source: https://docs.blockbee.io/kb/account-settings/what-is-the-difference-between-api-key-v1-and-v2 > Description: Understand the key differences between API Key V1 and V2, including purpose, security features, and when to upgrade. # What is the difference between API Key V1 and V2? With our Self-Custodial Wallet for Automated Payouts we introduced the API Key V2. If you're wondering whether you should upgrade your API Key V1 to V2, you should understand their main differences. ## Purpose and Use ### API Key V1 API Key V1 is straightforward, mainly for **receiving transactions** within BlockBee. It's a basic key that gives you access to our API, perfect for straightforward payment receiving. ### API Key V2 API Key V2 is about going beyond receiving. If you're looking to **automate sending payments** out to multiple addresses, V2 is designed for you. It's ideal for users managing platforms or services requiring regular fund distribution. ## Security and Recovery ### API Key V1 API Key V1 is secure yet simple. If you need to reset it, there's no risk of losing funds since it doesn't directly handle your money, just access to the API. ### API Key V2 API Key V2 ups the security with **advanced cryptography**, safeguarding your ability to control funds directly. And with the **recovery key feature**, you have a safety net in case you lose your main key, ensuring you can always regain access without losing funds. ## Upgrading Considerations > **INFO** >**Upgrade to API Key V2 if** automated payouts are essential for your operations, benefiting from the added security and flexibility it offers. > > **Stay with API Key V1 if** you do not wish to use our automated payouts feature. ## Comparison Table {% styledTable variant="striped" %} | Feature | API Key V1 | API Key V2 | |---------|------------|------------| | **Primary Use** | Receiving payments | Receiving + Automated payouts | | **Security Level** | Standard | Advanced cryptography | | **Recovery Options** | Simple reset | Recovery key feature | | **Fund Control** | No direct control | Direct fund control | | **Best For** | Basic payment receiving | Platforms with automated distributions | {% /styledTable %} --- # What is the Multi Token Parameter? > Source: https://docs.blockbee.io/kb/developers/api/what-is-the-multi-token-parameter > Description: Learn how the multi_token parameter allows customers to pay with any supported token on compatible networks. # What is the Multi Token Parameter? The `multi_token` parameter is only available for TRC-20, BEP-20 and ERC-20 networks. It's also an optional parameter, meaning that you don't need to set it while making a request. Its default value is `0`. This parameter allows the same `address_in` to receive payments in any token supported by our system. ## Important Considerations When setting this parameter you should make sure your wallet address (`address_out`) supports the tokens you expect your clients to pay with. **BlockBee cannot reverse any transaction or payment of a token unsupported by your wallet.** This parameter also means your clients can pay on any token supported by our system, even tokens with very different prices, so your system should check the `coin` field and make the appropriate price conversions. ### Example Scenario If you wish to receive 1000 USDT (or equivalent) and your client sends 1000 DOGE, your system should be able to handle that scenario when processing the callback. ## Related Documentation For more information about the fields and parameters mentioned: - [Create Payment Address - multi_token parameter](/api/create-payment-address#multi_token) - [Custom Payment Flow Webhooks - coin field](/webhooks/custom-payment-flow-webhooks) --- # What is the Priority Parameter? > Source: https://docs.blockbee.io/kb/developers/api/what-is-the-priority-parameter > Description: Learn how to use the priority parameter to control transaction speed and network fees across different cryptocurrencies. # What is the Priority Parameter? The priority parameter is available for Bitcoin, Ethereum, ERC-20 and Litecoin. It's available both in the create and estimate endpoint. Like the name hints, it's meant to make the transactions faster, though the higher the priority, the higher the network fee. Each cryptocurrency/network have their sets of priorities. ## Bitcoin With Bitcoin this represents confirmation targets, which means it's calculated based on current network fees to be confirmed within X number of blocks: | Priority | Blocks | |----------|--------| | fast | 10 | | default | 25 | | economic | 75 | | x-economic | 125 | | xx-economic | 200 | | xxx-economic | 300 | | xxxx-economic | 500 | | xxxxx-economic | 1000 | ## Ethereum With Ethereum, these values are based on gas price estimation: | Priority | Gas Price | |----------|-----------| | fast | 120% | | default | 100% | | economic | 95% | | x-economic | 90% | | xx-economic | 85% | | xxx-economic | 80% | | xxxx-economic | 75% | ## ERC-20 Tokens Like with Ethereum, with ERC-20 Tokens the values are based on gas price estimation: | Priority | Gas Price | |----------|-----------| | fast | 120% | | default | 100% | | economic | 95% | | x-economic | 90% | | xx-economic | 85% | | xxx-economic | 80% | | xxxx-economic | 75% | ## Litecoin Like with Bitcoin, these represent confirmation targets, which means it's calculated based on current network fees to be confirmed within X number of blocks: | Priority | Blocks | |----------|--------| | fast | 10 | | default | 25 | | economic | 50 | --- # How much are your transaction fees? > Source: https://docs.blockbee.io/kb/fees/how-much-are-your-transaction-fees > Description: Learn about BlockBee's transaction fees, volume-based discounts, minimum fees, and how the final fee is calculated. # How much are your transaction fees? Our base fee for all cryptocurrencies is **1%**, which can go down to **0.25%** based on volumes transacted in the last 30 days. The volume calculation is issued every day at 00:00 UTC. You can check our [calculator at the fees page](https://blockbee.io/fees/) to see how your volume affects your fee rate. ## Minimum Fees and Transaction Values We also have a **minimum fee** and a **minimum transaction value** that vary depending on the cryptocurrency selected. You can check our [cryptocurrencies page](https://blockbee.io/cryptocurrencies/) to see the minimums for each supported cryptocurrency. ### What is the minimum transaction value? The minimum transaction value means that transactions below that threshold will be disregarded. This was implemented to prevent spam attacks on our system with useless transactions. ## Fee Calculation The final fee is calculated as the **maximum value** between: - The percentage fee (based on your volume tier) - The minimum fee (specific to each cryptocurrency) **Formula:** `Final Fee = max(Percentage Fee, Minimum Fee)` This ensures that while volume-based discounts are applied, the service remains sustainable for processing smaller transactions. --- # How to Reduce Blockchain Fees > Source: https://docs.blockbee.io/kb/fees/how-to-reduce-blockchain-fees > Description: Discover ways to reduce blockchain fees by choosing cheaper blockchains and leveraging BlockBee's Prepaid Fees feature to save up to 50%. # How to Reduce Blockchain Fees You can reduce blockchain fees in two ways: ## 1. Choose a Cheaper Blockchain Use our blockchain fee estimation tool to identify and select a more cost-effective blockchain for your transactions. ## 2. Leverage Prepaid Fees Take advantage of our **Prepaid Fees** feature, which can help you save up to **50%** on blockchain fees. ## How Do Prepaid BlockBee Fees Work? By default, BlockBee charges a fee per transaction, taking up to 1% of the transacted amount (check our [fees page](https://blockbee.io/fees/)). Additionally, blockchain fees are paid to the blockchain to forward both our fee and your payment to your designated address. When you opt for **Prepaid Fees**, BlockBee no longer needs to deduct the fee from each transaction. This eliminates one transaction from the process, significantly reducing blockchain fees and saving you up to 50%. Learn how to use the [Prepaid BlockBee Fees](/kb/tutorials/dashboard/how-to-save-on-blockchain-fees-with-prepaid-fees). --- # Do I need an API Key? > Source: https://docs.blockbee.io/kb/get-started/do-i-need-an-api-key > Description: Understand why an API key is required to use BlockBee's services and how to generate one. # Do I need an API Key? Yes. To use our service you need an API Key ([learn how to generate one](/kb/tutorials/dashboard/how-to-generate-a-new-api-key)) which you can generate in our dashboard after registration. --- # Do I Need to Register? > Source: https://docs.blockbee.io/kb/get-started/do-i-need-to-register > Description: Learn about BlockBee's registration requirements and how to get started with an API key. # Do I Need to Register? Yes. You need to create an account in [BlockBee Dashboard](https://dash.blockbee.io/) and use our API Key in your website. --- # How does BlockBee service work? > Source: https://docs.blockbee.io/kb/get-started/how-does-blockbee-service-work > Description: Visual explanation of how BlockBee's cryptocurrency payment service works from start to finish. # How does BlockBee service work? ![How BlockBee Works](/kb/how-it-works.png) --- # How to Integrate BlockBee > Source: https://docs.blockbee.io/kb/get-started/how-to-integrate-blockbee > Description: Learn the different ways to integrate BlockBee into your platform with our comprehensive documentation and libraries. # How to Integrate BlockBee Integrating BlockBee into your platform is straightforward. We provide comprehensive documentation, plugins, and libraries in various programming languages to streamline the process for you. ## Choose Your Integration Method BlockBee offers multiple integration options depending on your platform and needs: ### 1. E-commerce Plugins If you're running an online store, we have ready-to-use plugins for popular e-commerce platforms: - **[WooCommerce](/get-started/woocommerce)** - For WordPress stores - **[PrestaShop](/get-started/prestashop)** - For PrestaShop stores - **[Magento](/get-started/magento)** - For Magento stores - **[OpenCart](/get-started/opencart)** - For OpenCart stores - **[Odoo](/get-started/odoo)** - For Odoo ERP systems These plugins handle all the integration work for you - just install, configure, and start accepting cryptocurrency payments! ### 2. Custom Payment Flow For custom applications or platforms not listed above, integrate BlockBee's API directly to build your own payment experience: **[Custom Payment Flow Guide](/get-started/custom-payment-flow)** - Build a fully customized cryptocurrency payment experience with complete control over the user interface and flow. This guide covers: 1. **Creating payment addresses** - Generate unique addresses for customers 2. **Displaying payment information** - Show QR codes and payment details 3. **Handling webhooks** - Process payment notifications and confirmations **Estimated time:** 30-45 minutes for a basic implementation ### 3. Pre-built Payment Solutions If you need a quick solution without coding: - **[Payment Links](/get-started/payment-links)** - Generate shareable payment links - **[POS (Point of Sale)](/get-started/pos)** - Use our mobile app for in-person payments - **[Telegram Bot](/get-started/telegram-bot)** - Accept payments through Telegram ### 4. Additional Features Once integrated, you can also explore: - **[Checkout Payments](/get-started/checkout-payments)** - Accept one-time payments with our hosted checkout - **[Checkout Deposits](/get-started/checkout-deposits)** - Accept deposits with a minimum amount - **[Subscriptions](/get-started/subscriptions)** - Set up recurring cryptocurrency payments - **[Payouts](/get-started/payouts)** - Send bulk cryptocurrency payments ## Need Help? - **Documentation:** All integration guides include code examples in multiple languages - **Libraries:** We provide official libraries for [Node.js](/libraries/nodejs), [PHP](/libraries/php), and [Python](/libraries/python) - **Support:** Check our [Knowledge Base](/kb/get-started/how-does-blockbee-service-work) for common questions Start with the integration method that best fits your platform and needs! --- # Is KYC Verification Required? > Source: https://docs.blockbee.io/kb/get-started/is-kyc-verification-required > Description: Learn about BlockBee's KYC requirements and the different verification tiers based on transaction volumes. # Is KYC Verification Required? Yes, KYC verification is required for certain transaction volumes on BlockBee. Specifically, KYC verification is mandatory for transactions exceeding $1000. ## KYC Tiers BlockBee has different KYC tiers based on transaction volumes: - **No KYC**: Up to $1000 volumes. - **Partial KYC**: This tier is necessary for volumes up to $500,000. It requires only ID verification. - **Full KYC**: This tier is required for unlimited transaction volumes, with no upper limit. By adhering to these KYC requirements, BlockBee ensures the security and compliance of all transactions on its platform. --- # Considerations to take before paying with an exchange > Source: https://docs.blockbee.io/kb/payments/considerations-to-take-before-paying-with-an-exchange > Description: Important guidelines for using cryptocurrency exchanges to pay BlockBee Checkout orders, including how to handle withdrawal fees. # Considerations to take before paying with an exchange When fulfilling a BlockBee Checkout order, you must send the exact amount requested. Some exchanges deduct their withdrawal fee from the amount you send to the BlockBee address, which can result in an unfilled order and BlockBee Checkout requesting the remaining amount. ## Best Practices > **WARNING** >If you still wish to use an exchange to send payments to BlockBee Checkout, ensure you **add the exchange withdrawal fee to the sent amount**. You can usually find the fee displayed before requesting the withdrawal. This will help avoid any issues with unpaid orders. ### Why This Matters - **Exact amount required**: BlockBee expects the precise amount shown in the checkout - **Exchange fees**: Most exchanges subtract their fee from your sent amount - **Underpayment issues**: Sending less than requested creates an unfulfilled order - **Solution**: Always add the exchange's withdrawal fee to ensure the full amount reaches BlockBee --- # How to calculate the minimum when using multiple addresses > Source: https://docs.blockbee.io/kb/payments/how-to-calculate-the-minimum-when-using-multiple-addresses > Description: Learn how to calculate minimum transaction values when using BlockBee's multi-address feature to send funds to up to 20 different addresses. # How to calculate the minimum when using multiple addresses BlockBee supports multi-addresses. This means that we can send your funds up to 20 different addresses. Though the higher the number of addresses, higher the minimum of the transaction. ## Formula The minimum is calculated using this formula: ``` 1 + (N - 1) / 3 ``` where **N** is the number of output addresses. ## Example Calculation Say you want to use 2 addresses. You do the calculation like this: ``` 1 + (2 - 1) / 3 = 1.33 ``` This is a percentual value that you should add to the minimum transaction that you can find in our [cryptocurrencies page](https://blockbee.io/cryptocurrencies/). For example, with Bitcoin it should be like this: ``` 0.00008 × 1.33 = 0.0001064 BTC ``` ## Important Notes > **WARNING** >If the percentage that you want to send is too small, say like 1%, it may fail in some cryptocurrencies due to the **dust threshold** (the minimum possible to transact in those blockchains). These are: > - **BTC & BCH**: 546 satoshi > - **LTC**: 5460 litoshi > **WARNING** >**Warning**: If you proceed with a transaction lower than the minimum, BlockBee will ignore the transaction and we won't be able to recover the funds. ## Minimum Value Tables ### Bitcoin {% styledTable variant="striped" %} | Num. of addrs | Multiplier | Min. Value | |--------------|------------|------------| | 1 | 1 | 0.00008 BTC | | 2 | 1.33 | 0.0001064 BTC | | 3 | 1.67 | 0.0001336 BTC | | 4 | 2 | 0.00016 BTC | | 5 | 2.33 | 0.0001864 BTC | | 6 | 2.67 | 0.0002136 BTC | | 7 | 3 | 0.00024 BTC | | 8 | 3.33 | 0.0002664 BTC | | 9 | 3.67 | 0.0002936 BTC | | 10 | 4 | 0.00032 BTC | {% /styledTable %} ### Ethereum {% styledTable variant="striped" %} | Num. of addrs | Multiplier | Min. Value | |--------------|------------|------------| | 1 | 1 | 0.00150000 ETH | | 2 | 1.33 | 0.001995 ETH | | 3 | 1.67 | 0.002505 ETH | | 4 | 2 | 0.003 ETH | | 5 | 2.33 | 0.003495 ETH | | 6 | 2.67 | 0.004005 ETH | | 7 | 3 | 0.0045 ETH | | 8 | 3.33 | 0.004995 ETH | | 9 | 3.67 | 0.005505 ETH | | 10 | 4 | 0.006 ETH | {% /styledTable %} ### TRC-20 - USDT {% styledTable variant="striped" %} | Num. of addrs | Multiplier | Min. Value | |--------------|------------|------------| | 1 | 1 | 10 USDT | | 2 | 1.33 | 13.3 USDT | | 3 | 1.67 | 16.7 USDT | | 4 | 2 | 20 USDT | | 5 | 2.33 | 23.3 USDT | | 6 | 2.67 | 26.7 USDT | | 7 | 3 | 30 USDT | | 8 | 3.33 | 33.3 USDT | | 9 | 3.67 | 36.7 USDT | | 10 | 4 | 40 USDT | {% /styledTable %} --- # I think I got billed more than needed, why? > Source: https://docs.blockbee.io/kb/payments/i-think-i-got-billed-more-than-needed-why > Description: Understand how BlockBee's fees and blockchain fees are calculated and what to do if you think you were charged incorrectly. # I think I got billed more than needed, why? Our fees are applied always automatically, according to the volumes and the category. Besides our fees, merchants also bear the blockchain fees. You can estimate blockchain fees using our [estimation tool](https://blockbee.io/fees/). If you still think the fees you are paying are not right, contact us and our team will sort out any doubt or concern you might have. --- # What are the statuses of a transaction? > Source: https://docs.blockbee.io/kb/payments/what-are-the-statuses-of-a-transaction > Description: Learn about the different transaction statuses in BlockBee: Received, Pending, Sent, and Done. # What are the statuses of a transaction? When consulting transactions in the "logs" endpoint or in the Dashboard, the following statuses apply: ## Transaction Statuses **Received**: Funds have been received in the specified address. **Pending**: The transaction has been detected but not yet confirmed by the blockchain. **Sent**: Funds have been received in the system's address and forwarded to the provided address. **Done**: Funds have been received, forwarded, and your systems have responded with an *ok* message to the system's callback. --- # Which platforms is the PoS (Point of Sale) App available? > Source: https://docs.blockbee.io/kb/pos/which-platforms-is-the-pos-app-available > Description: Learn about the availability of BlockBee's Point of Sale application across different platforms including Android, web, and iOS. # Which platforms is the PoS (Point of Sale) App available? Our POS (Point of Sale) application is available via [website](https://pos.blockbee.io/). It's compatible with both smartphones and tablets. ## Available Platforms - **Web**: Accessible via web browser - **Compatible Devices**: Smartphones and tablets ## Future Availability > **INFO** >An **iOS version** will be available in the future. --- # How to check my Self-Custodial Wallet > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-check-my-self-custodial-wallet > Description: Learn how to access and view your Self-Custodial Wallet addresses and balances in BlockBee Dashboard after upgrading to API Key V2. # How to check my Self-Custodial Wallet With the introduction of our Automated Payouts, and after you [upgrade to the API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2), you will now have access to your Self-Custodial Wallet. ## How does it work? Your Self-Custodial Wallet will be hosted by BlockBee, meaning it can be used by our API to send funds to various addresses. But **BlockBee will not have access to the funds**. ### Security Architecture By integrating **Threshold Signature Scheme (TSS) cryptography**, we believe we've struck an optimal balance in ensuring security. Your Self-Custodial Wallet is encrypted in our servers using Threshold Signature Scheme (TSS) cryptography, meaning BlockBee alone cannot decrypt the wallet. It will be needed either your **API Key V2** or your **Recovery Key** to do it so. > **INFO** >You will also be able to receive payments within BlockBee using your Self-Custodial Wallet. ## Prerequisites > **WARNING** >To check your addresses or balance, you must first [upgrade your API Key V1 to API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2). Without API Key V2, the Self-Custodial Wallet features will not be accessible. ## How to Check Your Self-Custodial Wallet ### Step 1: Access Self-Custodial Wallet Being in BlockBee Dashboard, click **Self-Custodial Wallet**. ![How to check Self-Custodial Wallet - Step 1](/kb/tutorials/dashboard/check-self-custodial-wallet-1.png) ### Step 2: View Addresses and Balances Finally, you will see a list of all our supported tokens. You can click on them to see your wallet address and the balance. ![How to check Self-Custodial Wallet - Step 2](/kb/tutorials/dashboard/check-self-custodial-wallet-2.png) ## What You Can See In the Self-Custodial Wallet view, you'll be able to: - **View all supported cryptocurrencies and tokens** - **Check wallet addresses** for each cryptocurrency - **Monitor balances** across all supported tokens - **Access wallet information** for receiving and sending payments ## Key Features {% styledTable variant="striped" %} | Feature | Description | |---------|-------------| | **TSS Encryption** | Wallet encrypted with Threshold Signature Scheme for maximum security | | **No BlockBee Access** | Only you can access funds using API Key V2 or Recovery Key | | **Multi-Token Support** | Support for all BlockBee-supported cryptocurrencies and tokens | | **API Integration** | Seamlessly integrated with Automated Payouts | | **Payment Gateway** | Receive payments directly to your Self-Custodial Wallet | {% /styledTable %} ## Next Steps Now that you can access your Self-Custodial Wallet, you can: - [Create payouts](/kb/tutorials/dashboard/how-to-create-a-payout) to distribute funds automatically - Receive payments through the BlockBee - Monitor your cryptocurrency balances in real-time - Use the wallet for multi-address payment distribution > **SUCCESS** >**Remember:** Your Self-Custodial Wallet is secured by your API Key V2 and Recovery Key. Keep both keys safe to maintain access to your funds. --- # How to create a Payout > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-create-a-payout > Description: Learn how to send multiple transactions with a single blockchain transaction using BlockBee's Payout feature for Ethereum, Binance Smart Chain, Polygon, and Tron. # How to create a Payout BlockBee's Payouts allow you to send multiple transactions with a single transaction in your Wallet. This service is only available for Ethereum, Binance Smart Chain, Polygon and Tron. Create payout requests, select the ones you wish to pay and send the Payout. > **INFO** >Before creating a payout, ensure you have [upgraded to API Key V2](/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2) and have access to your [Self-Custodial Wallet](/kb/tutorials/dashboard/how-to-check-my-self-custodial-wallet). ## Supported Blockchains Payouts are currently available for: - Ethereum (ERC-20 tokens) - Binance Smart Chain (BEP-20 tokens) - Polygon (MATIC tokens) - Tron (TRC-20 tokens) ## Step 1: Access the Create Button In the BlockBee Dashboard, click the **Create** button to start creating a new payout. ![How to create a Payout - Step 1](/kb/tutorials/dashboard/create-payout-1.png) ## Step 2: Navigate to Payout Requests Select the **Payout Requests** tab to view all available payout requests that can be processed. ![How to create a Payout - Step 2](/kb/tutorials/dashboard/create-payout-2.png) ## Step 3: Select Requests to Pay Choose the payout requests you wish to include in this payout transaction. Then click **Create Payout**. > **WARNING** >**Important:** All selected payout requests must be for the same cryptocurrency. You cannot mix different cryptocurrencies in a single payout transaction. ![How to create a Payout - Step 3](/kb/tutorials/dashboard/create-payout-3.png) ## Step 4: Process the Payout Finally, you will need to process the payout using one of these methods: - **API Key V2**: Use your API Key V2 to authorize the transaction - **Connect Wallet**: Connect your wallet directly to sign the transaction > **INFO** >**Note:** If you're processing TRC-20 tokens on the Tron network, you'll need to have the TronLink browser extension installed to complete the transaction. After processing, you'll see the transaction ID and the status will change to **Done**. ![How to create a Payout - Step 4](/kb/tutorials/dashboard/create-payout-4.png) ## Payout Complete! Your payout has been successfully created and processed. All selected recipients will receive their payments in a single blockchain transaction, saving you time and reducing individual transaction costs. > **SUCCESS** >**Efficiency Tip:** Batch multiple payout requests together to minimize blockchain fees and streamline your payment operations. ## Next Steps - Monitor your payout transactions in the Dashboard - View transaction details on the blockchain explorer - Create additional payout requests as needed - Check your [Self-Custodial Wallet](/kb/tutorials/dashboard/how-to-check-my-self-custodial-wallet) balance --- # How to create a POS (Point of Sale) User > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-create-a-pos-user > Description: Learn how to create dedicated POS users for your employees to access the BlockBee Point of Sale app without sharing your main account credentials. # How to create a POS (Point of Sale) User To access our PoS App, it's necessary to create a new PoS user. This login is solely for the purpose of making requests within the PoS App and cannot be used to access your main account. This setup is designed to ensure that your employees can configure the PoS app on their devices without requiring access to your main account credentials. > **INFO** >Before creating a POS user, ensure you have [created a Profile](/kb/tutorials/dashboard/how-to-create-a-profile) and selected it in your dashboard. ## Step 1: Access Profile Settings First in the Dashboard select the **"Profile Settings"**. ![How to create a POS user - Step 1](/kb/tutorials/dashboard/create-pos-user-1.png) ## Step 2: Navigate to POS Users Being in your Settings (with a profile selected), click **Point of Sale (PoS) Users**. ![How to create a POS user - Step 2](/kb/tutorials/dashboard/create-pos-user-2.png) ## Step 3: Add New User In the following screen you will need to click **Add User**. ![How to create a POS user - Step 3](/kb/tutorials/dashboard/create-pos-user-3.png) ## Step 4: Configure User Details To create a user you will need to insert a username and a password. ### Username Insert the username here. This will be added at the end of your account e-mail like the following example: ``` example@blockbee.io_insertedusername ``` ### Password Insert the user password here. Must be unique and will be used only to login as this user. ### Confirm Password Confirm the inserted password. Finally, to finish creating the POS User click **Create POS User**. ![How to create a POS user - Step 4](/kb/tutorials/dashboard/create-pos-user-4.png) ## Using the POS User Your POS user is now created! Employees can use the generated credentials (email with username suffix and password) to log into the [BlockBee POS App](/kb/pos/which-platforms-is-the-pos-app-available) without accessing your main account. > **SUCCESS** >**Security Tip:** Each employee should have their own POS user for better tracking and security management. --- # How to create a Profile? > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-create-a-profile > Description: Step-by-step guide to creating a new Profile in your BlockBee Dashboard to manage multiple companies and their transactions separately. # How to create a Profile? When you create your BlockBee account, the first step is to create a new Profile. You can have **multiple companies per account** and each Profile has its own transactions and settings. This means you can use your BlockBee account to manage multiple Profiles if needed. > **INFO** >By default, if you complete the Onboarding process you will have already created a Profile. If you skipped the Onboarding process or just wish to create a new Profile, you can follow this tutorial. ## Step 1: Access Profile Menu To create a Profile, click the button on the top left of the Dashboard. It can say either **Selected All** or your current **Profile name**, and then click **+ New Profile**. ![How to create a profile - Step 1](/kb/tutorials/dashboard/how-create-profile-1.png) ## Step 2: Fill in Profile Details In the following form, type the name of your Profile, and click **Create Profile**. ![How to create a profile - Step 2](/kb/tutorials/dashboard/how-create-profile-2.png) Your new Profile is now created and ready to use! Each Profile maintains separate transactions and settings, allowing you to efficiently manage multiple businesses or projects from a single BlockBee account. --- # How to generate a new API Key > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-generate-a-new-api-key > Description: Step-by-step guide to creating an API Key in BlockBee Dashboard for making requests to the BlockBee API. # How to generate a new API Key If you want to make requests to our API, you will need an API Key to send in the `apikey` parameter. Creating one is rather simple, but before you will need to [create a Profile](/kb/tutorials/dashboard/how-to-create-a-profile). > **INFO** >To learn more about the differences between API Key versions, check out our [API Key V1 vs V2 comparison](/kb/account-settings/what-is-the-difference-between-api-key-v1-and-v2). ## Step 1: Navigate to Settings While in the BlockBee's Dashboard, click **Settings**. ![How to generate API Key - Step 1](/kb/tutorials/dashboard/generate-api-key-1.png) ## Step 2: Access API Key Section In the Settings area, under the Profile Settings section, click **API Key**. ![How to generate API Key - Step 2](/kb/tutorials/dashboard/generate-api-key-2.png) ## Step 3: Configure Permissions Creating an API Key is straightforward. Simply select the permissions you want to enable. Currently, there is one permission available: **Address Override**: Lets you specify your wallet address directly in the API request using the `address` parameter. If you don't need this feature, you can leave it disabled. To create the API Key, click **Create API Key** and enter the OTP code to complete the process. ![How to generate API Key - Step 3](/kb/tutorials/dashboard/generate-api-key-3.png) ## Step 4: Save Your API Key After the previous step, a pop-up will show with your API Key. In this step you only need to copy the API Key and store it in a safe place. > **WARNING** >**Important:** BlockBee does not store your API Keys, so if you lose your API Key, you will need to generate a new one using the **Generate new API Key** button. ![How to generate API Key - Step 4](/kb/tutorials/dashboard/generate-api-key-4.png) ## Using Your API Key Your API Key is now ready to use! You can include it in your API requests using the `apikey` parameter or as a header. > **SUCCESS** >**Security Tip:** Keep your API Key secure and never expose it in client-side code or public repositories. Treat it like a password. --- # How to Save on Blockchain Fees with Prepaid BlockBee Fees > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-save-on-blockchain-fees-with-prepaid-fees > Description: Learn how to reduce blockchain fees by up to 50% using BlockBee's Prepaid Fees feature by prepaying service fees with credits. # How to Save on Blockchain Fees with Prepaid BlockBee Fees Prepaid BlockBee Fees is a feature that allows you to prepay BlockBee's service fees using credits. This eliminates the need for an additional transaction to cover fees, reducing blockchain fees by up to 50%. It's a cost-effective solution to make your cryptocurrency transactions more efficient. ## Why Use Prepaid BlockBee Fees? - **Save up to 50% on Blockchain Fees**: By eliminating the need for extra transactions, you significantly cut costs - **Flexible and Profile-Specific Credit Deposits**: Credits can be deposited anytime and are tied to specific Profiles in your BlockBee account - **Optional Feature**: You're not required to use prepaid fees, but they offer an excellent way to save on costs ## How It Works ### For Native Token Transactions (e.g., BTC, ETH) - Blockchain fees are deducted from the transaction amount - BlockBee's service fee is covered by your prepaid balance ### For Token Transactions (e.g., USDT, USDC) - Both BlockBee's service fee and blockchain fees are deducted from your prepaid balance (since being a token we are required to send funds to pay for the blockchain fees), ensuring the full transaction amount is sent to the recipient > **INFO** >If your prepaid balance runs out, the system reverts to the default process, where fees are deducted directly from the transaction. ## How to Deposit Prepaid Credits Follow these steps to start saving on fees: ### Step 1: Go to the BlockBee Dashboard Log in to your BlockBee account and navigate to the dashboard. ### Step 2: Select the Profile Choose the Profile where you want to deposit credits. Each Profile has its own credit balance. ![How to deposit prepaid credits - Step 2](/kb/tutorials/dashboard/deposit-prepaid-credits-2.png) ### Step 3: Click the "Deposit Credits" Button Locate and click the **Deposit Credits** button in your Profile settings. ![How to deposit prepaid credits - Step 3](/kb/tutorials/dashboard/deposit-prepaid-credits-3.png) ### Step 4: Read the Pop-Up Instructions Carefully A pop-up will appear explaining the process. Review the information and confirm by clicking **Deposit Credits** again. ![How to deposit prepaid credits - Step 4](/kb/tutorials/dashboard/deposit-prepaid-credits-4.png) ### Step 5: Complete the Deposit You'll be redirected to a new page where you can: - Choose your preferred cryptocurrency for the deposit - Complete the transaction to add credits to your prepaid balance ![How to deposit prepaid credits - Step 5](/kb/tutorials/dashboard/deposit-prepaid-credits-5.png) ## Important Notes > **WARNING** >**No Refunds for Unused Credits:** Plan your purchases carefully, as unused credits cannot be refunded. > **SUCCESS** >**Optional Feature:** Prepaid fees are entirely optional and designed to provide a cost-saving alternative. ## Start Saving Today By using Prepaid BlockBee Fees, you can save significantly on both service fees and blockchain fees, making your transactions more cost-effective. Start saving today! For any questions or assistance, feel free to reach out to our support team. ## Related Articles - [How much are your transaction fees?](/kb/fees/how-much-are-your-transaction-fees) - [How to reduce blockchain fees](/kb/fees/how-to-reduce-blockchain-fees) - [How to create a Profile](/kb/tutorials/dashboard/how-to-create-a-profile) --- # How to set the Payment Settings of your Profile > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile > Description: Learn how to configure payment settings for your Profile including business logo, accepted cryptocurrencies, confirmations, and fee surcharges. # How to set the Payment Settings of your Profile In this article, we will guide you through setting up your Payment Settings. The Payment Settings will be valid in all BlockBee's services where you're using this Company's API Key (PoS, Checkout, etc…). Be aware that our e-commerce plug-ins won't be using these settings. ## Step 1: Select Profile and Access Settings Before starting the process, you must ensure you have the right Profile selected. If you have not yet [created a Profile](/kb/tutorials/dashboard/how-to-create-a-profile), you will need to do so before proceeding to the settings. If you have **Selected All**, these options will not show. Then you must select the **Settings** button. ![How to set payment settings - Step 1](/kb/tutorials/dashboard/payment-settings-1.png) ## Step 2: Navigate to Checkout/PoS Settings If you have any Profile selected, the options related to the selected Profile will appear. Then, select **Checkout/PoS Settings**. ![How to set payment settings - Step 2](/kb/tutorials/dashboard/payment-settings-2.png) ## Step 3: Configure Payment Settings In the Payment Settings section you will find the following settings: ### Basic Information **Business Logo**: Upload the logo for your business/company that you would like to use in our services. **Business Name**: Enter the name of your business or company that you would like to display. ### Currency and Cryptocurrency Settings **Currency for Exchange Rate Calculation**: This can be either a FIAT currency or a cryptocurrency (e.g., USDt) used for conversions within BlockBee services. For instance, in the POS App or Checkout, this currency will serve as the base value for converting to your selected cryptocurrencies. **Choose cryptocurrencies to accept**: Select the cryptocurrencies to use in our service. It is possible for you to re-order them as you need. ### Confirmation Settings **Blockchain confirmation number**: Set the number of network confirmations needed to mark a payment as paid. Higher the number, the slower the payment confirmation will be. > **WARNING** >**Important:** Setting it to 0 will mark the payment as paid almost instantly, but it might be unsafe since network hasn't confirmed it yet. Use it at your own risk. ### Payment Tolerance **Payment Tolerance (%)**: Percentage tolerance to prevent rejecting payments that are slightly incomplete. For example, if set to 5% and the requested amount is $100 USDT, payments of $95 USDT or more will be accepted as complete and a webhook will be sent. > **INFO** >**Note:** The webhook will contain the actual amount paid by the user, not the requested payment value. ### Service Fees **Payment Service Fee Surcharge**: If enabled, BlockBee's service fee will be added on top of the order total and charged to the customer. **Payment Blockchain Fee Surcharge**: When enabled, the estimated blockchain fee required to forward funds will be added to the total. ## Save Your Settings When you're done configuring all settings, click click **Save**. ![How to set payment settings - Step 3](/kb/tutorials/dashboard/payment-settings-3.png) Your payment settings are now configured and will apply to all BlockBee services using this Profile's API Key! --- # How to set up the addresses? > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-set-up-the-addresses > Description: Learn how to configure your wallet addresses in BlockBee Dashboard to receive cryptocurrency payments across multiple blockchains and tokens. # How to set up the addresses? To get started with BlockBee, it's crucial to set up your wallet addresses to receive payments. You can do this by defining your addresses in the API call or through the dashboard. > **INFO** >To simplify the process, addresses on blockchains that support tokens will also work with all supported tokens. You can find the full list of supported cryptocurrencies on [this page](https://blockbee.io/cryptocurrencies/). > **WARNING** >**Important:** It's essential to select the correct address when making transactions, as **lost funds cannot be recovered**. Double-check that you have selected the appropriate address before proceeding with any transactions. ## Step 1: Navigate to Settings First you need to go to your **Settings**. ![How to set up addresses - Step 1](/kb/tutorials/dashboard/how-to-setup-addresses-1.png) ## Step 2: Access Wallet Addresses Then you must select **Set your wallet addresses**. ![How to set up addresses - Step 2](/kb/tutorials/dashboard/how-to-setup-addresses-2.png) ## Step 3: Choose Blockchain Each block contains the addresses respective to each blockchain. To set up your wallet address on the desired blockchain, click **SET YOUR ADDRESSES**. ![How to set up addresses - Step 3](/kb/tutorials/dashboard/how-to-setup-addresses-3.png) ## Step 4: Add Your Address You will need to fetch your cryptocurrency address from your wallet or exchange, and then paste it in **Address 1**, and then click **SAVE**. If you wish to add more addresses, you will need to click **ADD ANOTHER +**, and set the percentages (percentage sum must be 100%, otherwise form will fail saving). ![How to set up addresses - Step 4](/kb/tutorials/dashboard/how-to-setup-addresses-4.png) ## Multi-Address Setup When using multiple addresses: - Click **ADD ANOTHER +** to add additional addresses - Assign a percentage to each address - Ensure all percentages sum to **100%** - The system will automatically distribute payments according to these percentages Your wallet addresses are now configured and ready to receive payments! --- # How to set up your exchange address automatically > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-set-up-your-exchange-address-automatically > Description: Learn how to automatically configure your exchange address in BlockBee for seamless cryptocurrency conversions. # How to set up your exchange address automatically To ensure successful cryptocurrency conversions on the exchange, make sure to set your exchange address exclusively. This applies only when you use addresses configured directly in the Dashboard and follow the specified setup method outlined above. > **INFO** >Before following this guide, make sure you have already [configured your exchange](/kb/tutorials/dashboard/setting-up-crypto-exchange-using-binance) (e.g., Binance) in BlockBee. ## Step 1: Access Profile Settings In the BlockBee's Dashboard, select your Profile settings. If you don't have already a Profile, you must [create one](/kb/tutorials/dashboard/how-to-create-a-profile). Then select the **Settings**. ![How to set up exchange address automatically - Step 1](/kb/tutorials/dashboard/exchange-address-auto-1.png) ## Step 2: Navigate to Wallet Addresses While in the Settings, under the Profile Settings section, choose **Set Your Wallet Addresses**. ![How to set up exchange address automatically - Step 2](/kb/tutorials/dashboard/exchange-address-auto-2.png) ## Step 3: Select Blockchain Choose the blockchain/network which you wish to set the address for, and click the button **Set Your Addresses**. ![How to set up exchange address automatically - Step 3](/kb/tutorials/dashboard/exchange-address-auto-3.png) ## Step 4: Update From Exchange After that you need to click the **Update Address From Configured Exchange** button. A pop-up will appear with a list of exchanges you have configured, and you must select the one you wish to use. ![How to set up exchange address automatically - Step 4](/kb/tutorials/dashboard/exchange-address-auto-4.png) ## Important Notes > **WARNING** >**Important:** Any address you had saved before will be **replaced** by the deposit address of your exchange. Your exchange address is now automatically configured! This ensures that when using [exchange automation rules](/kb/tutorials/dashboard/setting-up-exchange-automation-rules), your cryptocurrencies will be properly deposited and converted on your exchange. --- # How to upgrade to API Key V2? > Source: https://docs.blockbee.io/kb/tutorials/dashboard/how-to-upgrade-to-api-key-v2 > Description: Step-by-step guide to upgrading from API Key V1 to V2 for accessing BlockBee's Self-Custodial Wallet and Automated Payouts features. # How to upgrade to API Key V2? By default all API Keys created are an API Key V1, meaning that if you want to have an API Key V2 you must upgrade first. If you wish to start using our Automated Payouts feature right away, the process to create the API Key V2 is as follows: Create an API Key V1, upgrade to API Key V2. > **INFO** >Learn more about the differences between API Key versions in our [API Key V1 vs V2 comparison](/kb/account-settings/what-is-the-difference-between-api-key-v1-and-v2). ## Important Notice > **WARNING** >**Critical:** Even though it's a simple process, **your maximum attention is required**. The Recovery Key is essential for accessing your funds. Losing both the API Key V2 and Recovery Key will result in permanent loss of funds. ## Part 1: Creating API Key V1 ### Step 1: Navigate to Profile Settings In the BlockBee's Dashboard, click **"Profile Settings"**. ![Upgrade to API Key V2 - Step 1](/kb/tutorials/dashboard/upgrade-api-key-v2-1.png) ### Step 2: Access API Key Section Being in your Company settings, select **API Key**. ![Upgrade to API Key V2 - Step 2](/kb/tutorials/dashboard/upgrade-api-key-v2-2.png) ### Step 3: Configure API Key Permissions Creating an API Key is rather simple. You just need to select the permissions you wish to enable. Right now we only have one, which is **Address Override**, which allows you to set your wallet address right in the API request using the `address` parameter. If you don't wish to do this, you may leave it disabled. To actually create an API Key you will need to press **CREATE API KEY** and fill the OTP code. ![Upgrade to API Key V2 - Step 3](/kb/tutorials/dashboard/upgrade-api-key-v2-3.png) ### Step 4: Save Your API Key V1 After the previous step, a pop-up will show with your API Key. In this step you only need to copy the API Key and store it in a safe place. > **WARNING** >**Important:** BlockBee does not store your API Keys, so if you lose your API Key, you will need to generate a new one using the **Generate new API Key** button. ![Upgrade to API Key V2 - Step 4](/kb/tutorials/dashboard/upgrade-api-key-v2-4.png) ## Part 2: Upgrading to API Key V2 ### Step 5: Initiate Upgrade After generating the API Key V1, you should click the **"Upgrade to API Key Version 2 (V2)"** button (if you don't see it contact us). ![Upgrade to API Key V2 - Step 5](/kb/tutorials/dashboard/upgrade-api-key-v2-5.png) ### Step 6: Save API Key V2 and Recovery Key After authenticating you will be shown a modal with both your **API Key V2** and your **Recovery Key**. > **WARNING** >**Critical Information:** > > The Recovery Key can be used both to: > - Access the funds in your Self-Custodial Wallet > - Reset the API Key V2 in case you lose it > > **Losing both will cause a permanent loss of funds**, since BlockBee will be unable to decrypt your Self-Custodial Wallet. > > It's imperative you copy both keys and store them in a safe place. **Treat them as the seed phrase of your Wallet.** After storing the keys securely you will need to click **I confirm I copied the API Key**. ![Upgrade to API Key V2 - Step 6](/kb/tutorials/dashboard/upgrade-api-key-v2-6.png) ### Step 7: Confirm Recovery Key Finally you will be prompted to confirm the Recovery Key to make sure that you actually copied it. ![Upgrade to API Key V2 - Step 7](/kb/tutorials/dashboard/upgrade-api-key-v2-7.png) ## Upgrade Complete! Congratulations! You've successfully upgraded to API Key V2. You can now use the Self-Custodial Wallet and Automated Payouts features. > **SUCCESS** >**Remember:** Store your API Key V2 and Recovery Key in separate, secure locations. Consider using a password manager or secure vault for storage. ## Next Steps Now that you have API Key V2, you can: - [Create payouts](/kb/tutorials/dashboard/how-to-create-a-payout) to send multiple transactions - [Check your Self-Custodial Wallet](/kb/tutorials/dashboard/how-to-check-my-self-custodial-wallet) balances - Use advanced features requiring V2 authentication --- # How to enable exchanging your funds with SwapBee > Source: https://docs.blockbee.io/kb/tutorials/dashboard/setting-up-exchange-automation-rules > Description: Learn how to enable SwapBee and create automation rules to exchange incoming funds automatically. # How to enable exchanging your funds with SwapBee To exchange incoming funds automatically, enable **SwapBee** first and then configure your **Automation Rules**. ## Step 1: Open Providers In the left sidebar, go to **Exchanges** and click **Providers**. ![Select Providers](/kb/tutorials/dashboard/exchange-automation-rules-1.png) ## Step 2: Enable SwapBee On the Exchanges page, find **SwapBee** and click **Enable**. > **INFO** >SwapBee must be enabled before automation rules can be applied. ![Enable SwapBee](/kb/tutorials/dashboard/exchange-automation-rules-2.png) ## Step 3: Open Automation Rules After enabling SwapBee, click **Automation Rules**. ![Open Automation Rules](/kb/tutorials/dashboard/exchange-automation-rules-3.png) ## Step 4: Add an automation rule Click **Add Rule**. ![Click Add Rule](/kb/tutorials/dashboard/exchange-automation-rules-4.png) In the pop-up, select: 1. **From Coin**: the coin you receive 2. **To Coin**: the coin you want to exchange into ![Set rules](/kb/tutorials/dashboard/exchange-automation-rules-5.png) > **INFO** >The available **To Coin** options depend on the selected **From Coin**. Click **Add Rule** to include it in the list. Repeat this process if you want to create more rules. ## Step 5: Save your rules Drag and drop rules to set priority. Rules at the top are applied first. When you are done, click **Save**. ![Save rules](/kb/tutorials/dashboard/exchange-automation-rules-6.png) > **WARNING** >Conversions are best effort. If no quote is available at processing time, funds are forwarded in the original asset to your configured address. Your funds exchange automation is now enabled with SwapBee. --- # How to set up our Magento Extension > Source: https://docs.blockbee.io/kb/tutorials/plugins/how-to-set-up-magento-extension > Description: Step-by-step guide to installing and configuring the BlockBee Magento extension to accept cryptocurrency payments in your Magento store. # How to set up our Magento Extension First you need to install our Magento Extension in your Magento Store. ## Prerequisites > **INFO** >Before configuring the BlockBee extension, ensure you have: > - Magento installed with admin access > - Installed the BlockBee Magento Extension > - A BlockBee [API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) > - [Wallet addresses configured](/kb/tutorials/dashboard/how-to-set-up-the-addresses) in your BlockBee Dashboard ## Configuration Steps ### Step 1: Access Stores Menu After all is set, go to the Magento Administration area and click **Stores**. ![How to set up Magento Extension - Step 1](/kb/tutorials/plugins/setup-magento-1.png) ### Step 2: Open Configuration In the menu click **Configuration**. ![How to set up Magento Extension - Step 2](/kb/tutorials/plugins/setup-magento-2.png) ### Step 3: Expand SALES Menu Click **SALES** to show a dropdown menu. ![How to set up Magento Extension - Step 3](/kb/tutorials/plugins/setup-magento-3.png) ### Step 4: Navigate to Payment Methods Then, click **Payment Methods**. ![How to set up Magento Extension - Step 4](/kb/tutorials/plugins/setup-magento-4.png) ### Step 5: Locate BlockBee Section In the Payment Methods page scroll to the BlockBee area, where you will set up our extension. ![How to set up Magento Extension - Step 5](/kb/tutorials/plugins/setup-magento-5.png) ### Step 6: Enable the Extension It's important to enable the extension setting the **Enable** option to "Yes". Feel free to set up the remaining settings as you wish. ![How to set up Magento Extension - Step 6](/kb/tutorials/plugins/setup-magento-6.png) ### Step 7: Configure API Key and Cryptocurrencies Paste your API Key that you got from BlockBee Dashboard and select the cryptocurrencies you want to accept (CTRL + click on Windows and CMD + Click on MacOS, to accept multiple currencies). Make sure you also did set the address in the Dashboard otherwise the extension will throw errors in the payment. > **WARNING** >**Important:** Ensure your wallet addresses are configured in the BlockBee Dashboard for each cryptocurrency you select, otherwise the extension will throw errors during payment processing. ### Step 8: Save Configuration Finally, **Save** the settings and your Magento Store is now ready to accept cryptocurrencies. ## Configuration Complete! Congratulations! Your Magento store is now ready to accept cryptocurrency payments through BlockBee. Customers will be able to select crypto as a payment method during checkout. > **SUCCESS** >**Remember:** Ensure your wallet addresses are properly configured in the BlockBee Dashboard for each cryptocurrency you've selected. ## Next Steps - Test the checkout process to ensure everything works correctly - Configure [payment settings](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) in your BlockBee Dashboard - Set up [exchange automation](/kb/tutorials/dashboard/setting-up-exchange-automation-rules) if needed - Monitor your transactions in the BlockBee Dashboard ## Related Articles - [How to generate a new API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to set up the addresses](/kb/tutorials/dashboard/how-to-set-up-the-addresses) - [How to set the Payment Settings of your Profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) --- # How to set up our OpenCart Extension > Source: https://docs.blockbee.io/kb/tutorials/plugins/how-to-set-up-opencart-extension > Description: Step-by-step guide to installing and configuring the BlockBee OpenCart extension for OpenCart 3 and OpenCart 4 to accept cryptocurrency payments. # How to set up our OpenCart Extension In this article we will explain how to set up BlockBee's OpenCart Extension in your OpenCart Store. First you will need to create and set up your account in our BlockBee Dashboard. After setting up your BlockBee account, you will need to install the extension in your OpenCart Store. Currently, our OpenCart Extension supports both OpenCart 3 and OpenCart 4. You will need to download the right file for your version from here. > **INFO** >Make sure the name of your file looks like this: **blockbee.ocmod.zip** ## Prerequisites Before installing the BlockBee extension, ensure you have: - OpenCart 3 or OpenCart 4 installed with admin access - Downloaded the correct BlockBee OpenCart Extension for your version - A BlockBee [API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [Wallet addresses configured](/kb/tutorials/dashboard/how-to-set-up-the-addresses) in your BlockBee Dashboard ## Installation Steps ### Step 1: Access Extensions Installer Having the right file for your OpenCart Store, you will need to log-in into your administration area to install the extension. While in the administration area, click **Extensions** to open a dropdown, and then click **Installer**. ![How to set up OpenCart Extension - Step 1](/kb/tutorials/plugins/setup-opencart-1.png) ### Step 2: Locate Upload Button After clicking Installer, click the **upload button**. In OpenCart 3 and OpenCart 4 the upload button is in different places, check the image below to see their location. ![How to set up OpenCart Extension - Step 2](/kb/tutorials/plugins/setup-opencart-2.png) ### Step 3: Upload Extension File Clicking this button will open a pop-up. Upload the file to install the extension and wait for the process to complete. > **WARNING** >**Note:** In OpenCart 4 you will need to install the extension here by clicking in the green button in Action area. Finally, click **Extensions**. ![How to set up OpenCart Extension - Step 3](/kb/tutorials/plugins/setup-opencart-3.png) ### Step 4: Enable BlockBee Extension Inside Extensions, select **Payments** in Extension Type and then in the list select the BlockBee Extension. Finally, click in the green button to finish the installation and, to change the extension settings, click the blue button with a pencil inside. ![How to set up OpenCart Extension - Step 4](/kb/tutorials/plugins/setup-opencart-4.png) ### Step 5: Enable Status In the settings area, it's very important to set the **Status** (highlighted in the image below) to **Enabled**, otherwise the extension won't work. The remaining settings you can customize to fit your needs. ![How to set up OpenCart Extension - Step 5](/kb/tutorials/plugins/setup-opencart-5.png) ### Step 6: Configure API Key and Cryptocurrencies If you scroll a bit, you will see more settings which are very crucial for the extension. First, you need to paste the API Key you got from our dashboard in the **API Key** field. You will also need to select the cryptocurrencies you want to accept (to select multiple cryptocurrencies CTRL + click on Windows / CMD + click on Mac). > **WARNING** >**Important:** Don't forget to set up the addresses in the dashboard, otherwise the extension won't work. ![How to set up OpenCart Extension - Step 6](/kb/tutorials/plugins/setup-opencart-6.png) ### Step 7: Save Configuration After all done you can **save** the settings and your OpenCart Store is now ready to accept cryptocurrency payments. ![How to set up OpenCart Extension - Step 7](/kb/tutorials/plugins/setup-opencart-7.png) ## Configuration Complete! Congratulations! Your OpenCart store is now ready to accept cryptocurrency payments through BlockBee. Customers will be able to select crypto as a payment method during checkout. > **SUCCESS** >**Remember:** Ensure your wallet addresses are properly configured in the BlockBee Dashboard for each cryptocurrency you've selected. ## Next Steps - Test the checkout process to ensure everything works correctly - Configure [payment settings](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) in your BlockBee Dashboard - Set up [exchange automation](/kb/tutorials/dashboard/setting-up-exchange-automation-rules) if needed - Monitor your transactions in the BlockBee Dashboard ## Related Articles - [How to generate a new API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to set up the addresses](/kb/tutorials/dashboard/how-to-set-up-the-addresses) - [How to set the Payment Settings of your Profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) --- # How to set up our PrestaShop Module > Source: https://docs.blockbee.io/kb/tutorials/plugins/how-to-set-up-prestashop-module > Description: Step-by-step guide to installing and configuring the BlockBee PrestaShop module to accept cryptocurrency payments in your PrestaShop store. # How to set up our PrestaShop Module Our PrestaShop Module allows you to get paid in all our supported cryptocurrencies in your PrestaShop Store, with a simple set-up. First you need to create an account. In this page we will guide you throughout the configuration and installation of our official PrestaShop Module. ## Prerequisites > **INFO** >Before installing the BlockBee module, ensure you have: > - A PrestaShop store with admin access > - Downloaded the BlockBee PrestaShop Module > - A BlockBee [API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) > - [Wallet addresses configured](/kb/tutorials/dashboard/how-to-set-up-the-addresses) in your BlockBee Dashboard ## Installation Steps ### Step 1: Access Modules Menu Download our PrestaShop Module and access your PrestaShop store's admin area. Click on **Modules** to open a dropdown menu. ![How to set up PrestaShop Module - Step 1](/kb/tutorials/plugins/setup-prestashop-1.png) ### Step 2: Open Module Manager In the dropdown menu click **Module Manager**. ![How to set up PrestaShop Module - Step 2](/kb/tutorials/plugins/setup-prestashop-2.png) ### Step 3: Upload Module After clicking Module Manager you will enter a new screen where you must click **Upload a module**. ![How to set up PrestaShop Module - Step 3](/kb/tutorials/plugins/setup-prestashop-3.png) ### Step 4: Select Module File You can either drop the zip file in the modal's red area or click **select file** to pick from your file system. ![How to set up PrestaShop Module - Step 4](/kb/tutorials/plugins/setup-prestashop-4.png) ### Step 5: Configure Module Once the installation is completed, click **Configure**. ![How to set up PrestaShop Module - Step 5](/kb/tutorials/plugins/setup-prestashop-5.png) ### Step 6: Activate the Module First, you need to activate the Module. You can configure the rest of the settings to fit your needs. ![How to set up PrestaShop Module - Step 6](/kb/tutorials/plugins/setup-prestashop-6.png) ### Step 7: Configure API Key and Cryptocurrencies Scroll down the settings page so you can see the remaining fields that are mandatory to set up. **API Keys**: Paste the API Key you obtained from your BlockBee Dashboard. **Select cryptocurrencies**: Select the cryptocurrencies you want to accept in your PrestaShop Store. > **INFO** >**Tip:** You may use **CTRL + Mouse click** on Windows or **Command + Mouse click** on Mac to select multiple cryptocurrencies. ![How to set up PrestaShop Module - Step 7](/kb/tutorials/plugins/setup-prestashop-7.png) ### Step 8: Set Up Cronjob Here you can define your Cronjob Nonce, though one is already defined by default for you. The automatic conversion and automatic order cancelation need a defined Cronjob to function. For that you must set-up a Cronjob that calls the provided link every 5 minutes. If you aren't sure how this works, contact your hosting provider. > **WARNING** >**Important:** The Cronjob is required for automatic conversion and order cancellation features to work properly. Make sure to set it up to run every 5 minutes. ![How to set up PrestaShop Module - Step 8](/kb/tutorials/plugins/setup-prestashop-8.png) ### Step 9: Save Settings Finally check again your settings and make sure you hit **Save** before closing the page. ## Configuration Complete! Congratulations! Your PrestaShop store is now ready to accept cryptocurrency payments through BlockBee. Customers will be able to select crypto as a payment method during checkout. > **SUCCESS** >**Remember:** Ensure your wallet addresses are properly configured in the BlockBee Dashboard for each cryptocurrency you've selected, and verify that your Cronjob is running correctly. ## Next Steps - Test the checkout process to ensure everything works correctly - Verify that the Cronjob is running every 5 minutes - Configure [payment settings](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) in your BlockBee Dashboard - Set up [exchange automation](/kb/tutorials/dashboard/setting-up-exchange-automation-rules) if needed - Monitor your transactions in the BlockBee Dashboard ## Related Articles - [How to generate a new API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to set up the addresses](/kb/tutorials/dashboard/how-to-set-up-the-addresses) - [How to set the Payment Settings of your Profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) --- # How to set up our WooCommerce Plugin > Source: https://docs.blockbee.io/kb/tutorials/plugins/how-to-set-up-woocommerce-plugin > Description: Step-by-step guide to installing and configuring the BlockBee WooCommerce plugin to accept cryptocurrency payments directly on your store. # How to set up our WooCommerce Plugin The BlockBee plugin extends WooCommerce, allowing you to get paid in crypto directly on your Store, with a simple setup and no sign-ups required. In this page we will guide you throughout the configuration and installation of our official WooCommerce Plugin. ## Prerequisites > **INFO** >Before installing the BlockBee plugin, ensure you have: > - WooCommerce installed and activated on your WordPress site > - A BlockBee [API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) > - [Wallet addresses configured](/kb/tutorials/dashboard/how-to-set-up-the-addresses) in your BlockBee Dashboard ## Installation Steps ### Step 1: Navigate to Plugins First you need to have WooCommerce installed. Then you go to **Plugins**. ![How to set up WooCommerce Plugin - Step 1](/kb/tutorials/plugins/setup-woocommerce-1.png) ### Step 2: Add New Plugin In the Plugins page click the **Add New** button. ![How to set up WooCommerce Plugin - Step 2](/kb/tutorials/plugins/setup-woocommerce-2.png) ### Step 3: Search and Install Type "BlockBee" in the search input and when our plug-in appears in the search result, click **Install Now**. Then just wait for WordPress to finish installing it. ![How to set up WooCommerce Plugin - Step 3](/kb/tutorials/plugins/setup-woocommerce-3.png) ### Step 4: Activate the Plugin When WordPress finishes installing BlockBee plug-in, click **Activate**. ![How to set up WooCommerce Plugin - Step 4](/kb/tutorials/plugins/setup-woocommerce-4.png) ### Step 5: Access WooCommerce Settings Then go to **WooCommerce** and click the **Settings** link. ![How to set up WooCommerce Plugin - Step 5](/kb/tutorials/plugins/setup-woocommerce-5.png) ### Step 6: Navigate to Payments In the WooCommerce Settings page click on the **Payments** tab. ![How to set up WooCommerce Plugin - Step 6](/kb/tutorials/plugins/setup-woocommerce-6.png) ### Step 7: Finish Setup Here you will have to scroll to "BlockBee Cryptocurrency Payment Gateway" and click **Finish set up**. This action will take you into the plugin settings where you will finish the configuration. ![How to set up WooCommerce Plugin - Step 7](/kb/tutorials/plugins/setup-woocommerce-7.png) ### Step 8: Configure API Key Make sure the checkbox is selected to enable BlockBee plugin and that you get a valid API Key from our dashboard and paste it in the **API Key** field. This is mandatory, failing to do so will result in the plug-in to error out when trying to make an order. You can also play around the settings a bit to make our WooCommerce plug-in fit your needs. > **WARNING** >**Important:** The API Key is mandatory. Without a valid API Key, the plugin will fail when customers try to make orders. ![How to set up WooCommerce Plugin - Step 8](/kb/tutorials/plugins/setup-woocommerce-8.png) ### Step 9: Select Cryptocurrencies Finally you must select the cryptocurrencies you want to accept in your WooCommerce store. You must make sure your wallet addresses are set in the dashboard, otherwise the plug-in will fail to make orders. > **INFO** >**Tip:** You can select multiple cryptocurrencies with **CTRL + click** on Windows, or **CMD + click** on Mac. ## Configuration Complete! Congratulations! Your WooCommerce store is now ready to accept cryptocurrency payments through BlockBee. Customers will be able to select crypto as a payment method during checkout. > **SUCCESS** >**Remember:** Ensure your wallet addresses are properly configured in the BlockBee Dashboard for each cryptocurrency you've selected. ## Next Steps - Test the checkout process to ensure everything works correctly - Configure [payment settings](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) in your BlockBee Dashboard - Set up [exchange automation](/kb/tutorials/dashboard/setting-up-exchange-automation-rules) if needed - Monitor your transactions in the BlockBee Dashboard ## Related Articles - [How to generate a new API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to set up the addresses](/kb/tutorials/dashboard/how-to-set-up-the-addresses) - [How to set the Payment Settings of your Profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) --- # How to handle subscriptions using BlockBee Telegram Bot > Source: https://docs.blockbee.io/kb/tutorials/telegram-bot/how-to-handle-subscriptions-using-blockbee-telegram-bot > Description: Learn how to monetize your Telegram channel by setting up automated subscriptions with BlockBee Bot, including user management and payment processing. # How to handle subscriptions using BlockBee Telegram Bot BlockBee Bot was specifically designed to assist you in monetizing the content of your Telegram channels. By using this bot, you can easily create subscriptions for your user base, enabling you to generate revenue. With BlockBee Bot, you have the flexibility to set up various pricing options for different date ranges. ## Automated User Management One of the key advantages of using our bot is its automated user management system. Once a user subscribes, the bot will generate an exclusive invitation link that can only be used once. This ensures that only subscribed individuals gain access to your Telegram channel. Additionally, when a subscription period comes to an end, the bot will automatically remove the user from your channel, ensuring that only active subscribers remain. With BlockBee Bot, managing and monetising your Telegram channel has never been easier. Let us handle the technicalities while you focus on delivering valuable content to your subscribers. ## How to use it? ### Create your Telegram Bot To create your own bot, you will need to use the BotFather. Follow these steps to get started: 1. Access the BotFather by clicking [here](https://t.me/BotFather) 2. Once you're in the BotFather chat, type the command `/start` to initiate the conversation 3. Next, type `/newbot` to start the process of creating a new bot 4. The BotFather will then prompt you to choose a name for your bot. Remember that the bot's name must end with the word "bot" (e.g., TestBot or MyAwesomeBot) 5. After providing a suitable name, the BotFather will generate a bot token for you. This token is essential for accessing and controlling your bot's functionalities (do not share the token with anyone, this token will be inserted into BlockBee Bot) ![Create project in BlockBee Bot](/kb/tutorials/telegram/handle-subscriptions-telegram-1.png) ### Create your project in BlockBee Bot To start using BlockBee Bot you must access it and then use the `/start` command (in some platforms, Telegram makes the Start as a button on the bottom). Then you must click the button **Create new project**. ![Insert Telegram Bot token](/kb/tutorials/telegram/handle-subscriptions-telegram-2.png) BlockBee Bot will then prompt you to insert your Telegram Bot token and then hit "send". ![Add bot as administrator](/kb/tutorials/telegram/handle-subscriptions-telegram-3.png) > **WARNING** >**Important:** Do not forget to set up your BlockBee API Key ([learn how to obtain one](/kb/tutorials/dashboard/how-to-generate-a-new-api-key)), by inserting again the `/start` command and clicking the button **Update API Key**. The process will be similar to setting up your Telegram Bot token. Make sure your API Key is valid otherwise your bot will throw errors when generating payments. ![Manage projects](/kb/tutorials/telegram/handle-subscriptions-telegram-4.png) ### Set up your project to start receiving payments using BlockBee Bot Before proceeding with the following steps, it is important to add your bot to your Telegram Channel as an administrator. The process of adding a bot as an administrator may vary depending on the platform you are using. Ensure that you have completed this step correctly, as the following steps will not function properly without it. To proceed, send the `/start` command again and then click on **Manage projects**. From the list that appears, select your bot's name. If you don't see your bot's name in the list, try reconfiguring your Telegram Bot. ![Manage projects](/kb/tutorials/telegram/handle-subscriptions-telegram-5.png) Select the Telegram Channel from the list below that you would like to manage. Ensure that you have added your Bot as an administrator to the channel you wish to manage before proceeding. ![Select Telegram Channel](/kb/tutorials/telegram/handle-subscriptions-telegram-6.png) After selecting your Telegram Channel, the management options will be displayed. To begin, you will need to set up the subscription price for the desired time periods. You can do this by clicking on the **Subscriptions** button. ![Channel management options](/kb/tutorials/telegram/handle-subscriptions-telegram-7.png) Once you click the **Subscriptions** button, a list of options for different time periods will be displayed. Here, you can set up the subscription price for the desired time period that you wish to accept. Upon clicking one of the available options, the BlockBee Bot will prompt you to enter the amount you want to charge in FIAT currency to your customers. BlockBee uses this amount to generate a payment address in the cryptocurrency your customer selects. ![Set subscription price](/kb/tutorials/telegram/handle-subscriptions-telegram-8.png) > **INFO** >**Note:** The amount charged will be in the FIAT currency that you have configured in your BlockBee Dashboard. ![Set subscription price](/kb/tutorials/telegram/handle-subscriptions-telegram-9.png) Upon selecting one of the options, the BlockBee Bot will prompt you to enter the amount you wish to charge in FIAT currency. Finally, you will need to select the **Activate BlockBee_bot in this group** option to activate the bot in the channel you have chosen. ## Your Bot is Ready! Congratulations! Your BlockBee Telegram Bot is now configured and ready to accept subscriptions. Users can now subscribe to your channel by making cryptocurrency payments, and the bot will automatically manage access to your content. > **SUCCESS** >**Pro Tip:** Regularly monitor your subscriptions and adjust pricing based on your content value and audience engagement. ## Related Articles - [How to generate a new API Key](/kb/tutorials/dashboard/how-to-generate-a-new-api-key) - [How to set the Payment Settings of your Profile](/kb/tutorials/dashboard/how-to-set-the-payment-settings-of-your-profile) ---