Payment Intents

A Payment Intent is the canonical lifecycle for one payment on one asset and chain. Its payment_method_type determines how funds move:

Method	Funds movement	Customer action
`crypto_transfer`	Customer sends tokens to a one-time chain address.	Transfer from a wallet.
`customer_balance`	Funds move from a merchant-scoped customer balance.	Merchant confirms; manual capture is optional.
`paybytoken_pay`	An authenticated consumer approves a Paybytoken balance payment.	Complete a short-lived hosted handoff.

Create Payment Intents only from trusted server code. A direct crypto_transfer intent reserves payment instructions immediately; customer-balance methods never create an external destination address.

For Paybytoken hosted, embedded or custom checkout, create a Checkout Session instead. Checkout Sessions postpone address creation until the customer confirms the token and network.

Endpoints

Method	Endpoint	Purpose
`POST`	`/api/v1/payment_intents`	Create an intent for the selected funds-movement method.
`GET`	`/api/v1/payment_intents/:id`	Retrieve the complete intent and activity.
`POST`	`/api/v1/payment_intents/:id/confirm`	Confirm a customer-balance intent.
`POST`	`/api/v1/payment_intents/:id/capture`	Capture a manually authorized intent.
`POST`	`/api/v1/payment_intents/:id/cancel`	Cancel an eligible intent and release an authorization.
`GET`	`/api/v1/payment_intents/:id/status`	Retrieve a compact payment status.
`PATCH`	`/api/v1/payment_intents/:id`	Update description or metadata.
`POST`	`/api/v1/payment_intents/:id/check`	Ask Paybytoken to check the destination address now.
`GET`	`/api/v1/payment_intents`	List intents with offset pagination.

The compact status, update, manual chain check and list endpoints remain available for existing direct-transfer integrations. The versioned contract catalog identifies the preferred lifecycle surface.

Amounts

Send and receive token amounts as decimal strings, such as "15.25". Never send JavaScript floating-point numbers. The number of fractional digits must not exceed the selected token's decimals, and the amount must meet that token's minimum payment.

The PaymentIntent object

Attribute	Type	Description
`id`	string	Unique Payment Intent ID.
`account_id`	string	Merchant account that owns the intent.
`payer_address`	string or null	Source wallet after a transfer is detected.
`one_time_address`	string or null	Destination address for `crypto_transfer`; absent for balance methods.
`chain`	string	Selected blockchain, such as `base`.
`currency`	string	Selected token, such as `USDC`.
`amount`	string	Exact token amount requested.
`amount_received`	string	Total qualifying amount detected.
`description`	string or null	Merchant-authored description.
`metadata`	object or null	Merchant-authored key-value data.
`customer`	string or null	Associated merchant-scoped customer.
`payment_method_type`	string	Selected funds-movement method.
`capture_method`	string	`automatic` or `manual`.
`amount_capturable`	string	Authorized amount waiting for capture.
`amount_captured`	string	Amount captured by the merchant.
`next_action`	object or null	Required handoff, currently `paybytoken_pay`.
`customer_email`	string or null	Customer contact email.
`receipt_email`	string or null	Address intended to receive a receipt.
`status`	string	Current Payment Intent status.
`tx_hash`	string or null	Primary payer transaction hash, when detected.
`balance_detected_block`	number or null	Block where the primary payment was detected.
`error_message`	string or null	Actionable failure or review reason.
`expired_at`	timestamp or null	Latest qualifying transfer time.
`created_at`	timestamp	Creation time.
`updated_at`	timestamp	Last update time.

Retrieval can also include token, balance_transaction, activities, and refund details. List responses include the resolved token for each item.

Statuses

Status	Meaning
`requires_payment_method`	No qualifying transfer has been detected.
`requires_additional_payment`	A transfer was detected, but more funds are required.
`requires_confirmation`	Enough funds were detected and are waiting for network confirmations.
`requires_action`	The payment needs merchant review, for example because it arrived after expiry.
`requires_capture`	Customer funds are authorized and waiting for merchant capture.
`confirmed`	The payment has been confirmed for downstream processing.
`succeeded`	The payment was finalized and credited.
`canceled`	The intent was canceled before payment confirmation.
`failed`	The intent failed.

Refund state is represented by separate Refund resources and does not rewrite the successful payment lifecycle.

Webhooks are the source of truth

Do not fulfill from a browser callback or a manual check response alone. Verify the signed payment_intent.succeeded webhook and make fulfillment idempotent.