Request a payment

Use a Payment Request when a known customer owes one amount and may pay later, retry from another device, make a partial payment, or need a reminder. Use a reusable Payment Link for campaigns and repeatable products, and a direct Checkout Session for one immediate checkout interaction.

Resource	Owns
Payment Request	Customer, due date, exact balance and collection history.
Checkout Session	One hosted customer interaction.
PaymentIntent	One token/network transfer execution.
Payment Request payment	Immutable allocation of confirmed funds to the receivable.

The recommended workflow is:

create a draft from server-owned customer and order data;
review and finalize it to lock terms;
share the returned URL or schedule email delivery;
process verified payment_request.* webhooks exactly once; and
monitor unapplied payments and reconciliation reports.

Lifecycle

Receivable lifecycle

EditableDraftReview terms

CollectibleOpenShare or deliver

Per attemptCheckout + IntentMay repeat

Covered in fullPaidTerminal

A failed or expired Checkout Session creates another attempt; it does not rewrite the receivable.

Status	Meaning	Merchant action
`draft`	Terms can still be edited.	Review customer, line items, due date and token choices.
`open`	Terms are locked and the request can collect payment.	Share the URL or schedule delivery.
`paid`	Allocated confirmed funds reduced the remaining amount to zero.	Fulfill exactly once.
`canceled`	New collection attempts are stopped by the merchant.	Preserve history; create a new request for new terms.
`expired`	The collection window ended.	Review late or unapplied funds before replacement.

Finalization is a business boundary. Do not finalize until the amount, customer identity and due date are correct. Updating a draft increments its version; existing financial allocations are not rewritten.

Create and finalize from your server

const request = await paybytoken.paymentRequests.create(
  {
    title: 'August services',
    customer_name: 'Alex Morgan',
    customer_email: 'alex@example.com',
    merchant_reference: 'AR-1042',
    currency: 'usd',
    line_items: [
      {
        name: 'Consulting',
        description: 'August delivery milestone',
        quantity: 1,
        unit_amount: '750.00',
      },
    ],
    supported_tokens: [{ chain: 'base', currency: 'USDC' }],
    due_at: '2030-08-31T23:59:59.000Z',
    metadata: { account_receivable_id: 'AR-1042' },
  },
  { idempotencyKey: 'payment-request:AR-1042:v1' },
)

const openRequest = await paybytoken.paymentRequests.finalize(request.id, {
  idempotencyKey: `payment-request:${request.id}:finalize:v${request.version}`,
})

Keep both your receivable ID and the Paybytoken Payment Request ID. Metadata helps correlation but does not replace that relationship.

Understand partial and unapplied funds

Each confirmed transfer creates an immutable Payment Request payment allocation. amount_paid is the sum applied to the receivable; amount_remaining is what another Checkout Session should collect. A Payment Request can therefore have several Checkout Sessions and Payment Intents without losing one durable balance.

Funds become unapplied when Paybytoken cannot safely assign them—for example, a late or excess payment conflicts with current request state. Do not silently credit or refund those funds from a browser action. Review the payment record, request timeline and reconciliation report through an authorized operations workflow.

Start with Create a Payment Request, then collect payment.

Request a payment

Lifecycle

Create and finalize from your server

Understand partial and unapplied funds

On this page

Full Explorer