BchainPayBchainPay

Quickstart

This guide walks through the full payment flow on the sandbox environment: create an intent, generate a deposit address, and receive a webhook on completion.

Prerequisites

  • A free BchainPay account (no KYC for sandbox)
  • curl and a terminal
  • ngrok or a similar tool to expose a local webhook endpoint

1. Get a sandbox API key

Sign in to the dashboard, switch to the Sandbox environment, and copy your secret key. Sandbox keys start with sk_sb_.

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": "ethereum",
  "token": "USDC",
  "reference": "INV-2026-001"
}'

The response returns the intent with status requires_action:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "merchant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount_cents": 4999,
  "received_amount_cents": 0,
  "remaining_amount_cents": 4999,
  "currency": "USD",
  "settlement_currency": "USDC",
  "network": "ethereum",
  "token": "USDC",
  "crypto_amount": "4999000",
  "crypto_amount_decimal": "4.999",
  "token_price_cents": 100,
  "status": "requires_action",
  "reference": "INV-2026-001",
  "metadata": {},
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:00Z"
}

Save the id — you'll need it in the next steps.

3. Generate a deposit address

Call the generate-address endpoint with the intent ID:

curl -X POST https://api.bchainpay.com/v1/payment-intents/d290f1ee-6c54-4b01-90e6-d701748f0851/generate-address \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json"

The response returns the updated intent with a blockchain_address in the metadata. Show this address (or a QR code of it) to your customer.

4. (Optional) Confirm the intent

In some flows you may want to explicitly confirm the intent before the customer pays:

curl -X POST https://api.bchainpay.com/v1/payment-intents/d290f1ee-6c54-4b01-90e6-d701748f0851/confirm \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json"

The intent status moves to processing.

5. Customer pays on-chain

The customer sends the crypto amount to the generated address on the specified network (use a testnet in sandbox). BchainPay monitors the blockchain for the incoming transaction.

You can poll the intent status at any time:

curl https://api.bchainpay.com/v1/payment-intents/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer $BCHAINPAY_API_KEY"

6. Receive the webhook

Once the payment is confirmed on-chain, BchainPay sends a signed payment_intent.completed event to your webhook endpoint:

{
  "id": "evt_7f2a91bc-4e3d-4c0f-b892-1a3d5e6f7890",
  "event_type": "payment_intent.completed",
  "created_at": "2026-04-27T12:08:11Z",
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "merchant_id": "merch_abc123",
    "amount_cents": 4999,
    "received_amount_cents": 4999,
    "remaining_amount_cents": 0,
    "currency": "USD",
    "network": "ethereum",
    "token": "USDC",
    "crypto_amount": "4990000",
    "crypto_amount_decimal": "4.99",
    "status": "completed",
    "reference": "INV-2026-001",
    "created_at": "2026-04-27T12:00:00Z",
    "updated_at": "2026-04-27T12:08:11Z"
  }
}

The webhook includes an X-Webhook-Signature header. Always verify the signature before trusting the payload.

What's next

Last updated Edit on GitHub