BconGlobal
BconGlobal
Login
How to Start Accepting Crypto Payments with the Bcon “New Address” API

Accepting cryptocurrency on your website may sound complicated. But with a payment gateway like Bcon, the process becomes structured and predictable. Before getting started, it’s important to choose a reliable wallet to receive your funds. If you’re not sure which option is best for your needs, you can refer to our guide on how to choose the best crypto wallet.

In this article, you will learn:

  • How the gateway works
  • How payments are identified
  • What you need before connecting your website
  • How the New Address API function works
  • How to correctly use all parameters
  • The difference between BTC and EVM chains
  • How invoice expiration works

How the Bcon Crypto Payment Gateway Works

Before writing code, you must understand the logic.

A crypto payment gateway does 4 main things:

  1. Creates a unique payment address for an invoice
  2. Monitors the blockchain
  3. Detects incoming transactions
  4. Sends a callback (notification) to your website

When a customer places an order:

  • Your website creates an invoice via API
  • The gateway generates a crypto address
  • The customer sends crypto to that address
  • The gateway detects the payment
  • The gateway sends a callback to your server
  • You mark the order as paid

That’s it.

2. What You Need Before Connecting

To connect your website to Bcon, you need:

A wallet to receive funds

This is YOUR wallet.
This is where you want to receive crypto. ( Metamask, Trustwallet, Exodus or any another )

The setup depends on blockchain type:

  • For Bitcoin → you provide an xpub
  • For EVM chains (Ethereum, BSC) and others SOL, TRX → you provide a regular wallet address

We will explain the difference below.

A Callback URL

This is a URL on your server.

Example:

https://yourstore.com/callback.php

When payment status changes, Bcon will send a POST request to this URL.

Without callback, your website will not know that payment happened.

API Key

For each blockchain store created in Bcon panel, you receive a separate API key.

Important:

  • Bitcoin → its own API key
  • Ethereum → its own API key
  • Binance → its own API key
  • Tron → its own API key

You must send it in header:

Authorization: Bearer YOUR_API_KEY

3. Bitcoin vs EVM Chains vs Tron, Solana – Important Difference

This is VERY important for understanding how payments are identified.

Bitcoin (BTC)

Bitcoin uses xpub (extended public key).

Important:

  • xpub does NOT give access to funds
  • It can only generate addresses
  • It is safe to give to gateway

How it works:

For every invoice:

  • Bcon generates a NEW BTC address from your xpub
  • Each invoice has its own unique address

Example:

Invoice 1 → Address A
Invoice 2 → Address B
Invoice 3 → Address C

This makes identification VERY easy.

If 0.005 BTC arrives to Address B →
System knows → this is Invoice 2.

Ethereum, BSC (EVM chains) and Tron, Solana

EVM chains and tron, solana do NOT use xpub.

Option 1 — One Wallet for Multiple Invoices

How it works

All customers send payments to the same wallet address.

If multiple invoices with the same amount are created at the same time, the system cannot determine which invoice the payment belongs to.

Example:

  • Invoice #101 → 100 USDT
  • Invoice #102 → 100 USDT

Both customers receive the same wallet address.

If a payment of 100 USDT arrives, the system cannot identify which invoice should be closed.

How the problem is solved

The system automatically adjusts the amount for additional invoices by adding small decimal values.

Example:

  • Invoice #101 → 100.00 USDT
  • Invoice #102 → 100.01 USDT
  • Invoice #103 → 100.02 USDT

Now the system can identify the correct invoice by the exact payment amount.

The customer must send the exact amount shown in the invoice.

If the customer sends:

  • less,
  • more,
  • or a rounded amount,

the system may not be able to immediately determine which invoice was paid.

How it works

You configure several wallet addresses.

Example:

  • Wallet 1
  • Wallet 2
  • Wallet 3
  • Wallet 4
  • Wallet 5

Each new invoice is assigned to the next available wallet in rotation.

If 5 invoices are created simultaneously:

InvoiceWallet
#101Wallet 1
#102Wallet 2
#103Wallet 3
#104Wallet 4
#105Wallet 5

Now, even if the payment amount differs slightly from the invoice amount, the system still knows which invoice belongs to which wallet.

After payment

When:

  • the invoice is paid,
  • or the payment time expires,

the system clears monitoring for that wallet and the address becomes available for reuse.

What happens if there are more invoices than wallets

Example:

  • 5 wallets
  • 20 simultaneous invoices

Once all wallets are occupied, the system starts reusing addresses.

At that point, the unique decimal amount mechanism from Option 1 is automatically enabled for invoices sharing the same wallet.

WalletInvoiceAmount
Wallet 1#101100.00
Wallet 1#106100.01

In Simple Terms

  • One wallet → easier setup, but a higher chance of payment identification conflicts.
  • Multiple wallets → more reliable payment detection and fewer cases requiring modified amounts.
  • More wallets → more simultaneous invoices can be processed without using unique decimal amounts.

Which Option Should You Choose?

One wallet is suitable if:

  • you have a low number of simultaneous payments;
  • invoice amounts are usually different;
  • you want the simplest possible setup.

Multiple wallets are recommended if:

  • you process many simultaneous invoices;
  • identical invoice amounts occur frequently;
  • reliable automatic payment detection is important;
  • you want to minimize unidentified payments.
Invoices handling Logic

4. Using the “New Address” API

Endpoint:

POST https://external-api.bcon.global/api/v2/address

Example in PHP:

define("BCON_APIKEY", "YOUR_API_KEY");

$curl = curl_init();
curl_setopt_array($curl, array(
 CURLOPT_URL => 'https://external-api.bcon.global/api/v2/address',
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_CUSTOMREQUEST => 'POST',
 CURLOPT_HTTPHEADER => array(
   'Accept: application/json',
   'Content-Type: application/json',
   'Authorization: Bearer '.BCON_APIKEY
 ),
 CURLOPT_POSTFIELDS => json_encode([
   "payment_currency" => "USDC",
   "origin_amount" => "15",
   "origin_currency" => "USD",
   "external_id" => "A1001",
   "chain" => "ethereum"
 ]),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

5. Understanding All Parameters

Let’s explain everything clearly.

Required Parameters

1. payment_currency

Token ticker.

Examples:

BTC

USDT

USDC

This defines what customer will pay in.

2. origin_amount

Amount in fiat currency.

Example: 15

3. origin_currency

Fiat currency code.

Examples:

  • USD
  • EUR
  • UAH

If your product price is $15:

origin_currency = USD

origin_amount = 15

System converts automatically to token amount.

Example result:

0.00032 BTC

Automatic Conversion Logic

If you use:

  • payment_currency
  • origin_amount
  • origin_currency

System calculates crypto amount based on market rate.

Optional Parameters

payment_amount

This overrides conversion.

Use it when:

  • You want exact crypto amount
  • You do not want auto conversion

Example:

“payment_currency” => “BTC”,

“payment_amount” => “0.01”

Now origin_amount is ignored. Invoice will be EXACTLY 0.01 BTC.

external_id

Very important. This is your invoice number.

Example:

“external_id” => “A1001”

Rules:

  • Must be unique per store
  • Max length 8 characters
  • Returned in callback

When callback arrives:

Instead of searching by amount, you search by external_id.

chain

Defines blockchain.

Available:

  • bitcoin
  • ethereum
  • binance
  • solana
  • tron

Example:

“chain” => “bitcoin”

Must match payment_currency.

6. Practical Examples

Example 1 – Auto Conversion (USD → BTC)

You sell product for $100.

"payment_currency" => "BTC",
"origin_amount" => "100",
"origin_currency" => "USD",
"external_id" => "B2001",
"chain" => "bitcoin"

System calculates:

0.0021 BTC

Customer pays BTC.

Example 2 – Fixed Crypto Amount

You want fixed 50 USDT.

"payment_currency" => "USDT",
"payment_amount" => "50",
"external_id" => "C3001",
"chain" => "tron"

No conversion used.

Example 3 – Two EVM Invoices Same Amount

Two invoices:

50 USD

50 USD

System may generate:

Invoice 1 → 50.00 USDT
Invoice 2 → 50.01 USDT

Customer must send exact value.

7. How Callback Works

When the payment status changes, the Bcon system sends a POST request to your callback URL.

This request contains important information about the transaction. Your server must read this data and update the order status in your database.

The callback will return the following fields:

  • Status — the transaction status
    • confirmed = 2
    • partially_confirmed = 1
    • unconfirmed = 0
  • Addr — the receiving address where the payment was sent
  • Value — the received payment amount
  • Txid — the transaction ID in the blockchain

External_id — the value you specified when creating the invoice (used for tracking)

Example Callback JSON

{
 "status": 2,
 "addr": "0x1234abcd...",
 "value": "15000000",
 "txid": "0x98fa76bc54...",
 "external_id": "A1001"
}

What the Status Means

  • 0 (unconfirmed) → Transaction detected but not confirmed yet
  • 1 (partially_confirmed) → Transaction has some confirmations
  • 2 (confirmed) → Transaction is fully confirmed and payment is final

In most cases, you should mark the order as paid only when status = 2.

Important Technical Notes

1️⃣ Callback Success Rule

A callback is considered successful only when your server returns:

HTTP 200 status

If your server does not return HTTP 200, the system may retry sending the callback.

2️⃣ BTC Balance Units

For Bitcoin payments:

  • The Value field is returned in satoshis, not BTC.

Reminder:

1 BTC = 100,000,000 satoshis

Example:

If Value = 50000000
That means:

0.5 BTC

For EVM chains (Ethereum, BSC, Tron), the value follows the blockchain’s native smallest unit rules.

Simple PHP Example to Handle Callback

$data = json_decode(file_get_contents("php://input"), true);
$status = $data['status'];
$external_id = $data['external_id'];
if ($status == 2) {
   // Mark order as paid in database
}

8. Best Practices

✔ Always use external_id
✔ Always verify callback
✔ Always require exact payment
✔ Always use separate API key per chain
✔ Do not expose private keys
✔ For BTC – use xpub only when considering how to set up crypto payments, it is crucial to understand the various payment processors available and their fees. Additionally, ensure that your platform is compliant with local regulations regarding cryptocurrency transactions. This will help in building trust with your customers while also safeguarding your business.

9. Summary

Using the New Address function from Bcon allows you to:

  • Automatically generate payment addresses
  • Automatically calculate crypto amounts
  • Automatically track payments
  • Automatically receive callbacks

Key differences:

Bitcoin:

  • Uses xpub
  • Generates unique address per invoice
  • Perfect identification

EVM:

  • One wallet address
  • Amount differentiation used
  • Exact payment required

If you understand:

  • origin_amount
  • origin_currency
  • payment_currency
  • payment_amount
  • external_id
  • chain

Then you fully control invoice creation logic.