Payment object

An order may have one or multiple payments depending on the payment rail and order capabilities (for example partial payments or retries).

Amounts are decimal strings

All monetary values in Payments are represented as decimal strings. Floating-point numbers must not be used.

{
  "paid_amount": "100.00",
  "fee_amount": "2.50",
  "net_amount": "97.50"
}

Decimal precision depends on the payment currency. See Amounts and currency conversion for details.

Field	Type	Description
`id`	`string`	Unique payment identifier (e.g., `pay_...`).
`merchant_id`	`string`	Identifier of the merchant that owns the payment.
`order_id`	`string`	Identifier of the order this payment is associated with.
`status`	`string`	Current payment status. See Payment status below.
`payment_rail`	`string`	Payment rail used to process the payment.
`provider_id`	`string`	Provider-side identifier (for example an on-chain transaction hash or internal provider reference).
`paid_amount`	`string`	Gross amount received from the payer, as a decimal string.
`fee_amount`	`string`	Fees applied to the payment, as a decimal string.
`net_amount`	`string`	Net amount credited after fees (`paid_amount - fee_amount`).
`currency`	`string`	Currency or asset code of the payment.
`metadata`	`Record<string, string>?`	Optional provider-specific metadata.
`created_at`	`string`	ISO-8601 timestamp when the payment was recorded.
`updated_at`	`string`	ISO-8601 timestamp of the last payment update.

Payments progress through a defined set of statuses during their lifecycle.

Status	Meaning
`received`	The payment was detected but not yet applied to the order.
`applied`	The payment was successfully applied to the order balance.
`failed`	The payment attempt failed and has no effect on the order.
`refunded`	The payment was refunded after being applied.
`orphan`	The payment could not be matched to a valid order.

Note
Payment status changes are delivered via payment-related webhook events.

A typical flow:

Fees are calculated based on the selected payment rail and merchant configuration.

All three values are always expressed in the payment currency.

Payments are append-only records and can not be modified by merchants.
Always rely on status to determine whether a payment affects an order.
Do not assume that a payment implies an order is paid; rely on the Order status.
For partial payments, multiple Payment objects may exist for a single order.