Product: BabyFX Pay

Merchant flow

Last updated: 2026-07-23

This page walks a merchant through onboarding, creating an invoice, getting paid, and being notified.

Audience: integrators building merchant POS, e-commerce plugins, or invoicing tools. If you are a developer running the local stack, see Run locally first.

The journey in 5 steps

Onboard — create a merchant account, get api_key + webhook_secret
Set settlement address — where confirmed funds will be swept
Create invoice — specify fiat amount, get a deposit address and QR
Customer pays — wallet sends native 2BABY to the deposit address
Webhook fires — payment.detected, then payment.confirmed, then sweep

1. Onboard

POST /v1/merchants
Content-Type: application/json

{
  "name": "Acme Coffee",
  "webhook_url": "https://acme.example.com/webhooks/babyfx",
  "settlement_address": "0xC6Fe5D33615a1C52c08018c47E8Bc53646A0E101"
}

Response (201):

{
  "id": 1,
  "name": "Acme Coffee",
  "webhook_url": "https://acme.example.com/webhooks/babyfx",
  "settlement_address": "0xC6Fe5D33615a1C52c08018c47E8Bc53646A0E101",
  "api_key": "bfx_0123456789abcdef0123456789abcdef0123456789abcdef",
  "webhook_secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef"
}

Save api_key and webhook_secret immediately. They are returned exactly once, at creation time. They are stored encrypted in the database (webhook_secret_ciphertext is AES-256-GCM under PAY_SECRET_KEY); the server cannot show them to you again. If you lose them, rotate by deleting the merchant and creating a new one.

2. Set or update the settlement address (optional)

The settlement address is the merchant''s payout wallet. Confirmed invoice funds are swept to it by pay/sweep. You can set it at onboarding or later:

PUT /v1/merchant/settlement-address
Authorization: Bearer bfx_...
Content-Type: application/json

{ "settlement_address": "0xC6Fe5D33615a1C52c08018c47E8Bc53646A0E101" }

3. Create an invoice

POST /v1/invoices
Authorization: Bearer bfx_...
Content-Type: application/json

{ "fiat_amount": "4.50", "fiat_currency": "USD" }

The response includes the deposit address, the exact 2BABY amount, the EIP-681 payment URI, and a pre-rendered QR code. Display any of those to the customer.

Idempotency. Send Idempotency-Key: <opaque> on invoice creation. Re-sending the same key returns the original invoice, not a new one. This is critical for retries from your POS.

4. Customer pays

The customer scans the QR with any EVM-compatible wallet (BabyWallet, MetaMask mobile, etc.). The wallet sends native 2BABY to the deposit address.

5. Webhooks fire

Event	When	Action expected
`payment.detected`	The paying tx is in a block	Mark order as "paid, awaiting confirmations"
`payment.confirmed`	Confirmation count passes threshold (default: 12)	Mark order as "confirmed, fulfilling"
`payment.swept`	Funds have been swept to your settlement address	Mark order as "settled"
`payment.failed`	Sweep failed (insufficient gas, RPC error)	Manual intervention required

See Webhooks for payload format and signature verification.