Create a Payment Intent

POST /api/v1/payment_intents

Create this resource from your server. The default crypto_transfer method returns one-time chain payment instructions. Balance methods return an authorization or hosted-consumer action instead.

The default crypto_transfer method creates chain payment instructions. Private-beta merchants may instead request payment_method_types: ["paybytoken_pay"]; that flow returns requires_action and must be approved by the authenticated consumer through a ConsumerPaymentSession.

Use payment_method_types: ["customer_balance"] with a Customer ID to pay from merchant-scoped available funds. See Confirm and capture and the customer balance guide.

curl https://api-prod.paybytoken.io/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "15.25",
    "currency": "USDC",
    "chain": "base",
    "description": "Order 123",
    "metadata": { "order_id": "order_123" },
    "customer_email": "customer@example.com",
    "receipt_email": "receipts@example.com"
  }'

Request body

Parameter	Type	Required	Description
`amount`	string	yes	Positive decimal token amount. Fractional digits cannot exceed token precision.
`currency`	string	yes	Enabled token code, such as `USDC`.
`chain`	string	yes	Enabled network code, such as `base`.
`description`	string	no	Description shown in merchant records.
`metadata`	object	no	Merchant-authored key-value data.
`customer`	string	balance methods	Existing merchant-scoped customer ID.
`customer_id`	string	no	Deprecated alias for `customer`.
`customer_email`	string	no	Customer contact email.
`receipt_email`	string	no	Email address intended to receive the receipt.
`expired_at`	timestamp	no	Future expiry. When omitted, the platform payment timeout is used.
`payment_method_types`	string[]	no	One of `crypto_transfer`, `customer_balance`, or private-beta `paybytoken_pay`; defaults to `crypto_transfer`.
`capture_method`	string	no	`automatic` (default) or `manual`; manual capture applies to customer balance.
`confirm`	boolean	no	Confirm the intent in the create request. Defaults to `false`.

Response

The following response illustrates the default crypto_transfer method. Balance methods return the same canonical Payment Intent lifecycle fields but do not return a one-time chain address.

{
  "id": "pay_t24b28nbodnk4icGMyE7",
  "account_id": "acct_1",
  "payer_address": null,
  "one_time_address": "0xa1A0340cF7b9326eA4210AB49c17e20e0c32a2FB",
  "chain": "base",
  "currency": "USDC",
  "amount": "15.25",
  "amount_received": "0.0",
  "amount_capturable": "0.0",
  "amount_captured": "0.0",
  "payment_method_types": ["crypto_transfer"],
  "payment_method_type": "crypto_transfer",
  "capture_method": "automatic",
  "description": "Order 123",
  "metadata": { "order_id": "order_123" },
  "customer_id": null,
  "customer_email": "customer@example.com",
  "receipt_email": "receipts@example.com",
  "status": "requires_payment_method",
  "tx_hash": null,
  "balance_detected_block": null,
  "error_message": null,
  "created_at": "2026-07-29T10:15:00.000Z",
  "updated_at": "2026-07-29T10:15:00.000Z",
  "expired_at": "2026-07-29T10:30:00.000Z"
}

See Payment Intents for the full object and lifecycle.

Create a Payment Intent

Request body

Response

On this page

Full Explorer