Create a Payment Request

POST /api/v1/payment_requests

Create drafts from trusted server data. Do not accept price or quantity directly from browser input.

const request = await paybytoken.paymentRequests.create(
  {
    title: 'August services',
    customer_name: 'Alex Morgan',
    customer_email: 'alex@example.com',
    merchant_reference: 'PO-1042',
    currency: 'usd',
    line_items: [
      { name: 'Consulting', quantity: 2, unit_amount: '25.00' },
    ],
    supported_tokens: [
      { currency: 'USDC', chain: 'base' },
      { currency: 'USDC', chain: 'ethereum' },
    ],
    due_at: '2026-09-15T23:59:59.000Z',
    metadata: { customer_id: 'cus_1042' },
  },
  { idempotencyKey: 'payment-request:PO-1042' },
)

The response has status: "draft", url: null, and server-calculated subtotal, total, and remaining amount. A duplicate request with the same idempotency key and body returns the same resource; reusing the key with different input is rejected.

Parameters

Parameter	Required	Description
`title`	yes	Customer-facing purpose, up to 160 characters.
`currency`	yes	Currently `usd`.
`line_items`	yes	1–100 items with name, quantity and decimal `unit_amount`.
`supported_tokens`	yes	One or more enabled `{ currency, chain }` pairs.
`customer_email`	no	Default email recipient for sending the request.
`due_at`	no	ISO timestamp; finalization defaults it to 30 days ahead.
`memo`, `footer`	no	Customer-facing supporting text.
`merchant_reference`, `metadata`	no	Merchant-owned reconciliation fields.

Create a Payment Request

Parameters

On this page

Full Explorer