Hosted checkout and redirects

Every invoice comes with a hosted checkout page. You send your customer to it, they pay, and they come back to your site. You do not build a payment form, show addresses, or track confirmations.

The integration in three steps

1. Create an invoice on your server and include where the customer should return to.

   cURL

   curl -X POST "https://api.ctpeway.com/v1/invoices" \
     -H "Authorization: Bearer $CTPEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-1042" \
     -d '{
       "price": { "currency": "USD", "amount": "49.99" },
       "options": [
         { "asset": "USDT", "network": "bsc" },
         { "asset": "USDT", "network": "tron" },
         { "asset": "ETH", "network": "ethereum" }
       ],
       "description": "Order 1042",
       "order_id": "order-1042",
       "success_url": "https://shop.example/orders/1042/thanks",
       "cancel_url": "https://shop.example/cart"
     }'

   Node SDK

   const invoice = await ctpeway.invoices.create({
     price: { currency: 'USD', amount: '49.99' },
     options: [
       { asset: 'USDT', network: 'bsc' },
       { asset: 'USDT', network: 'tron' },
       { asset: 'ETH', network: 'ethereum' },
     ],
     description: 'Order 1042',
     order_id: 'order-1042',
     success_url: 'https://shop.example/orders/1042/thanks',
     cancel_url: 'https://shop.example/cart',
   });

2. Redirect the customer to the invoice’s checkout_url. Store the invoice id with the order first.

3. Fulfil the order when you receive the invoice.paid webhook. See Webhooks.

See POST/v1/invoices for every field you can send.

The redirect is not proof of payment

A customer arriving at your success_url does not mean the invoice is paid. Anyone can open that URL. Decide that an order is paid only from the invoice.paid webhook, or by retrieving the invoice from your server and checking that its status is paid.

What the customer sees

The page is public and needs no login. It is built for phones first.

1. Choose how to pay. Your business name, what is being paid for, and the amount. The options you accept are listed as an asset on a network, grouped by asset, each with its crypto amount. If the invoice has only one option, this step is skipped.

2. Pay. Two ways, side by side, with a countdown that shows how long the quoted rate holds:

   • Pay with wallet connects the payer’s wallet and opens a transaction that is already filled in. See Pay with wallet.
   • Send manually shows a QR code, the address and the exact amount, each with a copy button, and one warning, such as “Send only USDT on BNB Smart Chain to this address.”

   The amount shown is the amount to send. A quoted amount is rounded up to a few decimals so that it is easy to read and type, and sending exactly the amount shown pays the invoice in full.

3. Confirming. As soon as a payment is seen, the page says “Payment detected” and shows the amount received, the confirmation progress and a link to a block explorer. The payer can close the page; the link keeps working.

4. Paid. A receipt with the amount, the transaction and the time, and a button back to your site.

The page updates by itself. The payer never has to reload it.

Other states

Situation	What the payer sees
The quote expired and nothing was sent	“This quote expired”, with a button to get a new rate. The address stays the same, and the invoice stays open until its own expiry.
Underpaid	The amount received, the amount still due, and the same address and QR code for the rest.
Overpaid	Paid, with a note that you have been told about the extra amount.
Paid after the invoice expired	Payment received and passed to you for review. See Late payments.
Invoice canceled or already paid	A clear final state, with no address.
Test invoice	A banner, Test invoice — no real funds, the test network’s name on every label, and a faucet link.

The payer always sees Paid once their payment is confirmed. Whether the funds have reached your master wallet yet is your business only, and is never shown on the checkout page. See Settlement and the platform fee.

Redirect URLs

Field	When it is used
success_url	The button back to your site after the invoice is paid.
cancel_url	The way back to your site when the customer leaves without paying.

Rules:

• In live mode, the hostname of each URL must be a domain you have verified. The checkout only ever sends a customer to a verified domain, so nobody can use your checkout pages to redirect people elsewhere. See Domain verification.
• In test mode, localhost and hostnames ending in .test are accepted too.

Put your own order reference in the URL, as in the example, so that your page knows which order the customer is returning from. Then look the invoice up on your server.

What you can put on the page

Field	Shown to the payer
description	Yes, as what is being paid for.
order_id	Yes.
metadata	No. It is returned to you in the API and in events.
customer_email	No. It is for your own records, and cTpeWay sends no email to it.

Your business name comes from your account.

Not in the first release

• Your own logo and accent colour on the checkout page.
• A version of the checkout that is embedded in your own page.
• Languages other than English.