Quickstart

title: "Quickstart" description: "Create your first BchainPay payment intent and verify the webhook in five minutes." section: "Get started" order: 2 updated: "2026-04-18" sourcePath: "content/docs/quickstart.mdx"

This guide takes you from zero to a confirmed test payment on the Polygon Amoy testnet. You'll need:

A free BchainPay account (no KYC for sandbox)
curl and a terminal
A public HTTPS endpoint to receive webhooks (use ngrok locally)

1. Get a sandbox API key

Sign in, switch to the Sandbox environment from the workspace switcher, and copy your secret key. It looks like sk_sb_•••. Export it:

export BCHAINPAY_API_KEY="sk_sb_..."

2. Create a payment intent

curl -X POST https://api.bchainpay.com/v1/payment-intents \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 4999,
    "currency": "USD",
    "settlement_currency": "USDC",
    "network": "polygon",
    "reference": "INV-2026-001"
  }'

The response includes a fresh on-chain address and a pocket_id:

{
  "id": "pi_3L9k...42",
  "status": "requires_payment",
  "address": "0x9f3a...b41C",
  "pocket_id": "pkt_usdc_polygon",
  "amount_cents": 4999,
  "settlement_currency": "USDC",
  "network": "polygon",
  "expires_at": "2026-04-18T13:00:00Z"
}

3. Pay it from a testnet wallet

Send 49.99 USDC on Polygon Amoy to the returned address. Faucet links are in the dashboard.

4. Receive the webhook

Once confirmed (12 blocks on Polygon), we POST a signed event to your endpoint:

{
  "type": "payment_intent.completed",
  "data": {
    "id": "pi_3L9k...42",
    "status": "completed",
    "pocket_id": "pkt_usdc_polygon",
    "tx_hash": "0x7d2e...01ab",
    "reference": "INV-2026-001"
  }
}

Verify the signature before trusting the body — see Verify a webhook.

5. Withdraw the pocket

curl -X POST https://api.bchainpay.com/v1/withdrawals \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "pocket_id": "pkt_usdc_polygon",
    "amount_cents": 4999,
    "destination": "0xYourWalletHere"
  }'

You're done. The withdrawal.completed webhook will fire with the tx_hash once broadcast.