Quickstart

In this guide you create an invoice in test mode, pay it with a simulated payment, and receive the webhook that tells your server it was paid. No real funds and no faucet are needed.

You need a cTpeWay account and, for the SDK examples, Node.js 20.16 or newer.

1. Get a test API key

   Sign in to the dashboard. New accounts start in Test mode; the Test / Live switch is in the top bar.

   Go to Developers → API keys and create a secret key. The key is shown once, so copy it now. A test key starts with ctp_test_sk_.

   Put it in an environment variable. Do not paste it into source code.

   export CTPEWAY_API_KEY="ctp_test_sk_..."

2. Install the SDK

   Skip this step if you use cURL.

   npm install @ctpeway/sdk

3. Create an invoice

   An invoice says what is owed and which assets on which networks you accept. This one asks for 10.00 USD, payable in USDT on the BNB Smart Chain test network.

   cURL

   curl -X POST "https://api.ctpeway.com/v1/invoices" \
     -H "Authorization: Bearer $CTPEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: quickstart-order-1" \
     -d '{
       "price": { "currency": "USD", "amount": "10.00" },
       "options": [{ "asset": "USDT", "network": "bsc-testnet" }],
       "description": "Quickstart order",
       "order_id": "order-1"
     }'

   Node SDK

   import { CtpeWay } from '@ctpeway/sdk';
   
   const ctpeway = new CtpeWay(process.env.CTPEWAY_API_KEY!);
   
   const invoice = await ctpeway.invoices.create({
     price: { currency: 'USD', amount: '10.00' },
     options: [{ asset: 'USDT', network: 'bsc-testnet' }],
     description: 'Quickstart order',
     order_id: 'order-1',
   });
   
   console.log(invoice.id, invoice.checkout_url);

   The response is the invoice. Two fields matter now: its id, and checkout_url, the page where your customer pays.

   Each option names an asset and a network. bsc-testnet is a network slug: GET/v1/networks lists the slugs your key can use, and GET/v1/assets lists the assets on them. If you leave options out, the invoice accepts every asset you have enabled.

   See POST/v1/invoices for every field.

4. Open the checkout page

   Open checkout_url in a browser. This is what your customer sees: the amount, the asset on its network, an address with a QR code, and a banner that says Test invoice — no real funds. If the page asks how you want to pay, choose USDT on the BNB Smart Chain test network.

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

   Leave the page open. It updates by itself when the payment arrives.

5. Simulate the payment

   In test mode you can create a payment without sending anything on a network.

   cURL

   curl -X POST "https://api.ctpeway.com/v1/test/invoices/{id}/simulate_payment" \
     -H "Authorization: Bearer $CTPEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "outcome": "paid" }'

   Node SDK

   await ctpeway.test.invoices.simulatePayment(invoice.id, { outcome: 'paid' });
   
   const paid = await ctpeway.invoices.retrieve(invoice.id);
   console.log(paid.status); // 'paid'

   Replace {id} with the invoice’s id. The checkout page moves to Paid, and the invoice’s status is now paid.

   You can also do this without code: open the invoice in the dashboard and choose Simulate payment. To pay with real test coins instead, see Testing.

6. Receive the webhook

   Your server should not poll for payment. cTpeWay sends it an event.

   In the dashboard, go to Developers → Webhooks and add an endpoint with the URL of your server, subscribed to invoice.paid. Copy the signing secret (whsec_...), which is also shown once. Then verify each delivery before you trust it:

   import { CtpeWay } from '@ctpeway/sdk';
   import express from 'express';
   
   const app = express();
   
   // The signature covers the raw bytes of the body, so this route must not parse JSON first.
   app.post('/webhooks/ctpeway', express.raw({ type: 'application/json' }), (req, res) => {
     const event = CtpeWay.webhooks.constructEvent(
       req.body,
       req.headers['ctpeway-signature'],
       process.env.CTPEWAY_WEBHOOK_SECRET!,
     );
   
     if (event.type === 'invoice.paid') {
       console.log(`Invoice ${event.data.object.id} is paid. Fulfil the order.`);
     }
     res.json({ received: true });
   });

   Simulate another payment on a new invoice and watch the event arrive. The dashboard shows every delivery, with the response your server gave, under Developers → Webhooks.

What you built

• An invoice created from your server, with a hosted checkout page.
• A payment, and the invoice moving from open to paid.
• A verified invoice.paid webhook, which is the signal to fulfil an order.

Next steps

• Invoices: underpaid, overpaid, expired and late payments, and what to do about each.
• Settlement and the platform fee: when the funds reach your master wallet, and why a token deposit can be Held.
• Webhooks: every event, retries and replay.
• Testing: simulate the other outcomes, or pay on a test network.
• Going live: what to set up before you switch to a live key.