Sign in

v1

latestOpenAPI 3.0.32026-07-264469137.7 KB
Payments

Retrieve a payment

Retrieve a single payment by its charge ID, with the full object: amount, status, the customer, fees, the products paid for, refunds, and status history.

get/v1/payments/{payment_id}

Path parameters

payment_idstring required

Charge ID of the payment.

Response

Success - Payment retrieved

referencestring nullable

Checkout reference when available.

payment_idstring

Unique identifier for the payment.

billing_reason'purchase' | 'subscription_create' | 'subscription_cycle' | 'subscription_update'

Why this payment exists. purchase: a one-time purchase. subscription_create: the first cycle of a new subscription. subscription_cycle: a subscription renewal. subscription_update: an off-cycle charge from a mid-cycle plan change (proration).

checkout_idstring nullable

Checkout identifier, when linked.

status'created' | 'processing' | 'succeeded' | 'accepted' | 'failed' | 'expired' | 'cancelled' | 'refunded' | 'partially_refunded' | 'underpaid' | 'overpaid' required

payment status.

is_refundableboolean nullable

Whether this payment can currently be refunded.

amountstring required

Requested amount in currency.

amount_paidstring nullable

Amount received so far.

amount_remainingstring nullable

Remaining amount still expected.

currencystring required

Payment currency code.

fee_usdstring nullable

Processing fee for this payment, converted to USD and expressed as a decimal string. null until the payment settles.

merchant_bears_costboolean nullable

Whether merchant bears processing cost.

payment_methodstring nullable

Payment method used for this payment.

channelstring nullable

Origin channel (for example api).

narrationstring nullable

payment description/narration.

metaobject nullable

Public metadata stored for this payment.

messagestring nullable

Human-readable payment message derived from status.

subscription_idstring nullable

The subscription this payment belongs to, or null for a one-time purchase.

refundsstring[] nullable

IDs of any refunds issued for this payment. null if no refund has been created.

created_atstring date-time required

Creation timestamp.

updated_atstring date-time required

Last update timestamp.

completed_atstring date-time nullable

Completion timestamp when available.

Example response

{
  "reference": "order_9876",
  "payment_id": "pay_1a2b3c4d5e",
  "billing_reason": "purchase",
  "checkout_id": "chk_6f7g8h9i0j",
  "status": "succeeded",
  "is_refundable": true,
  "amount": "10.00",
  "amount_paid": "10.00",
  "amount_remaining": "0.00",
  "currency": "USD",
  "fee_usd": "0.59",
  "merchant_bears_cost": true,
  "payment_method": "card",
  "channel": "checkout",
  "narration": "Pro plan",
  "meta": {
    "order_id": "ORD-9876"
  },
  "message": "Successful",
  "line_items": [
    {
      "product_id": "prod_abc123",
      "product_name": "Premium Plan",
      "quantity": 1,
      "unit_amount": "50.00",
      "currency": "USD",
      "line_total": "50.00"
    }
  ],
  "invoice": {
    "invoice_id": "inv_9a8b7c6d5e",
    "number": "inv_9a8b7c6d5e",
    "subscription_id": "sub_1a2b3c4d5e",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z",
    "kind": "cycle"
  },
  "refunds": [
    "ref_1a2b3c4d5e"
  ],
  "status_history": [
    {
      "status": "succeeded",
      "occurred_at": "2026-01-24T14:35:00.000Z",
      "provider_reference": "TXN_ABC123"
    }
  ],
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:05Z",
  "completed_at": "2026-04-27T12:00:05Z"
}