Invoices API

The Invoices API is the core of ButterPay. It covers the full lifecycle of a one-time USD-denominated payment: create an invoice from your server, share the hosted payment link with your customer, and let them settle on-chain via the PayRouter contract on Arbitrum. ButterPay is non-custodial — the customer signs approve + pay() directly to PayRouter, the merchant's wallet is never involved in the flow, and ButterPay never holds funds.

There are exactly two endpoints in V2. Payment confirmation is delivered to your server via the payment.confirmed webhook configured in the dashboard — see Webhooks.

CreateInvoice

Create a new USD-denominated invoice. The returned payUrl is the hosted payment page; share it with your customer (redirect, email, QR, etc.). The customer picks any whitelisted token at pay time, signs approve + pay() to PayRouter, and the backend marks the invoice PAID once the on-chain PaymentProcessed event is observed.

• Method: POST
• Path: /v1/invoices
• Auth: Authorization: Bearer <jwt> or X-Api-Key: <key>
• Description: Creates an invoice scoped to the authenticated merchant and computes the on-chain invoiceId (a bytes32 keccak256 hash of merchantUuid, the order ID bytes, and a fresh 32-byte nonce). The invoice expires 30 minutes after creation if no payment is observed on-chain (see Status lifecycle).

Request body

Response (HTTP 201)

{
  "id": "inv_dudkhayh6ntw7ou7uz97mhfn",
  "onChainInvoiceId": "0x38e0290dffbdce828672b58cf0ec1f34d06b82581bca186ac73e8f4c65437333",
  "amountUsd": "10",
  "status": "PENDING",
  "merchantOrderId": "order_001",
  "description": "Order #1234",
  "createdAt": "2026-05-05T06:11:09.500Z",
  "payUrl": "https://pay.butterpay.io/pay/inv_dudkhayh6ntw7ou7uz97mhfn"
}

Example

curl -X POST https://api.butterpay.io/v1/invoices \
  -H "X-Api-Key: bp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": "10",
    "merchantOrderId": "order_001",
    "description": "Order #1234"
  }'

Response:

{
  "id": "inv_dudkhayh6ntw7ou7uz97mhfn",
  "onChainInvoiceId": "0x38e0290dffbdce828672b58cf0ec1f34d06b82581bca186ac73e8f4c65437333",
  "amountUsd": "10",
  "status": "PENDING",
  "merchantOrderId": "order_001",
  "description": "Order #1234",
  "createdAt": "2026-05-05T06:11:09.500Z",
  "payUrl": "https://pay.butterpay.io/pay/inv_dudkhayh6ntw7ou7uz97mhfn"
}

After creation, redirect the customer to payUrl (or render it as a button / QR code). Listen for the payment.confirmed webhook to fulfil the order on your side.

Error responses

GetInvoice

Look up a single invoice. This endpoint is public: no API key or JWT is required. The hosted payment page calls this to render invoice details and discover where funds are going.

• Method: GET
• Path: /v1/invoices/:id
• Auth: Public (no authentication)
• Description: Returns the raw invoices row, plus merchantName and merchantReceivingAddresses joined from the merchant record. The :id parameter accepts either a ButterPay DB id (inv_…) or the on-chain bytes32 onChainInvoiceId (0x + 64 hex chars).

Path parameters

Response (HTTP 200)

{
  "id": "inv_dudkhayh6ntw7ou7uz97mhfn",
  "merchantId": "mer_01hwzq3k5n8ej4v2b7r9abc123",
  "merchantOrderId": "order_001",
  "amount": "10",
  "token": "USD",
  "chain": "pending",
  "status": "PENDING",
  "onChainInvoiceId": "0x38e0290dffbdce828672b58cf0ec1f34d06b82581bca186ac73e8f4c65437333",
  "description": "Order #1234",
  "payerAddress": null,
  "txHash": null,
  "paymentMethod": null,
  "merchantNet": null,
  "serviceFee": null,
  "referrerAddress": null,
  "referrerFee": null,
  "referrerFeeBps": null,
  "confirmedAt": null,
  "createdAt": "2026-05-05T06:11:09.500Z",
  "updatedAt": "2026-05-05T06:11:09.500Z",
  "merchantName": "Acme Store",
  "merchantReceivingAddresses": {
    "arbitrum": "0xMerchantReceivingAddress"
  }
}

Field notes:

Example — lookup by DB id

curl https://api.butterpay.io/v1/invoices/inv_dudkhayh6ntw7ou7uz97mhfn

Example — lookup by on-chain id

Useful when you only have the bytes32 from a PaymentProcessed event log:

curl https://api.butterpay.io/v1/invoices/0x38e0290dffbdce828672b58cf0ec1f34d06b82581bca186ac73e8f4c65437333

Error responses

Status lifecycle

                  customer pays on-chain
   PENDING ───────────────────────────────────▶ PAID
      │
      │ no payment within 30 minutes
      ▼
   EXPIRED

There is no FAILED status on invoices. A failed on-chain attempt simply leaves the invoice in PENDING until either a successful payment lands or the expiry job moves it to EXPIRED. (The subscription.expired webhook is emitted from the recurring-billing path, not from invoices — see Plans & Subscriptions.)

There is also no REFUNDED status: refunds are not modelled by the backend in V2. If you need to return funds to a customer, do so off-platform (a direct on-chain transfer from your receiving wallet).

Operations not supported in V2

To save you from looking: the following operations existed in V1 and are gone in V2.

• No PATCH / PUT on invoices — invoices are immutable after creation.
• No DELETE — there is no way to cancel an invoice. Stop sharing the payUrl and let it expire.
• No refund endpoint — handle refunds off-chain from your receiving wallet.
• No session-token / submitTransaction flow — the customer signs pay() directly to PayRouter, so the backend never needs to be told about the tx hash. The on-chain listener picks it up.
• No /v1/transactions, /v1/transactions/summary, /v1/transactions/export, or /v1/balances endpoints on the public API. Those reports live in the dashboard.

Related

• Webhooks — payment.confirmed payload, HMAC signature verification, retry schedule. Configure your receiver URL in the dashboard.
• Authentication — issuing API keys and Bearer JWTs.
• Plans & Subscriptions API — recurring billing via EIP-2612 permits.