Blockchain API for E-Commerce Payments

A blockchain API for e-commerce is a REST interface that lets an online shop create payment addresses, detect incoming crypto payments, and send refunds or payouts without running its own blockchain nodes. The shop talks to the API over HTTPS and gets webhooks when a payment arrives. Keys and confirmation rules stay under the shop’s control.

How does a web shop accept crypto payments through an API?

Give each order its own deposit address, watch it with a webhook, and mark the order as paid when the confirmed amount matches. The flow has five steps:

1. Create an address for the order with POST /api/v2/{blockchain}/addresses.
2. Register a webhook for that address with POST /api/v2/{blockchain}/webhooks, and put your order ID into the reference field.
3. Show the customer the address, the amount and an expiry time.
4. When the webhook arrives, verify the X-Signature header and check the amount and token on the chain.
5. Release the goods after the number of confirmations you decided on.

One address per order removes guesswork: any payment to that address belongs to that order. The payment webhooks guide shows the receiver code, and the Laravel tutorial shows the same flow in a PHP framework.

What should the order record store?

Store enough data to decide on your own whether a payment is complete. The webhook tells you that something happened. Your order record tells you what should have happened.

Field	Purpose
Order ID	Also sent as the webhook reference, so you can match the event
Network and token	The chain and contract the customer must use
Deposit address	The address created for this order
Expected amount	Converted from the shop price when the invoice was issued
Invoice expiry	Time after which the price is no longer valid
Required confirmations	The rule you chose for this network and order size
Status	Pending, partially paid, paid, expired or refunded

With these fields, the webhook handler is a short comparison. Look up the order by reference, check that network and token match, add the amount to what was received so far, and update the status. A payment of the wrong token to the right address is a normal case that the handler must catch, because an address can receive any token on its network.

How many confirmations should a shop wait for?

It depends on the network and on the value of the order. The Bitcoin developer documentation on payment processing says that a transaction with zero confirmations should not be trusted without risk analysis, and that software handling high-value transactions should wait for at least six confirmations, which takes about an hour. On TRON, a block is solidified once at least 19 of the 27 Super Representatives have built on it, which the TRON consensus documentation puts at about one minute under normal conditions.

Choose a rule per network and per order size, write it down, and apply it in code. A low-value digital item may ship after one confirmation. A high-value physical item should wait longer.

What should you do about price changes?

Fix the price in your own currency, convert it when you issue the invoice, and let the invoice expire. The Bitcoin documentation notes that exchange rates vary, that invoices pegged to fiat must expire, and that most payment systems expire invoices after 10 to 20 minutes. A shorter window lowers the exchange-rate risk and raises the chance that a customer pays late.

Decide in advance what happens to a late or partial payment. Most shops refund it, or ask the customer to pay the difference to the same address.

How do refunds and payouts work?

Send them as ordinary transactions from an address you control. Use POST /api/v2/{blockchain}/transactions for the native coin and the token endpoints, such as transactions/erc20, transactions/bep20 or transactions/trc20, for tokens. A refund needs the customer’s return address, which you must ask for separately because the sender of a payment is not always the wallet that should get the money back, for example when the payment came from an exchange.

Keep the funds of an order address short-lived. Move incoming payments to a wallet you hold offline and use the order addresses only for collecting. Our security tips explain how to store the keys.

How do you control network fees?

Plan for fees on the sending side. Moving tokens off an order address costs gas on EVM networks and Energy or Bandwidth on TRON, and the order address needs enough of the native coin for that. On TRON, sponsoring or renting energy lowers the cost of TRC-20 transfers. Our documentation on TronFuel and the deprecated Paymaster explains the current option. TronFuel is a separate service with its own documentation.

How do you test the integration before launch?

Use the testnets. Add the header X-Network: testnet to any request and the same call runs on a test network without real funds. Test a full order, an underpayment, an overpayment, a late payment and a webhook that fails to reach your server. Failed webhooks are not retried automatically. They appear in GET /webhooks/notifications/failed and can be re-sent, so your shop should check that list.

Do you need to verify your customers?

That depends on your jurisdiction and your business model, and the API does not decide it for you. Chaingateway is non-custodial. Read our article on KYC for crypto payments before you decide which checks apply to your shop.