Retrieve an invoice

GET/v1/invoices/{id}

Authorization

Send your API key as a bearer token in the Authorization header. Secret API key: Authorization: Bearer ctp_live_sk_…. A publishable key (ctp_…_pk_…) is accepted by these operations only, which serve reference data: getRate, listAssets, listNetworks (each marked x-publishable-key: true). Every other operation refuses it with 403 publishable_key_not_allowed, whatever Origin the request carries: that header binds browsers, not other clients, and nothing on this API relies on it.

Path parameters

Name	Type	Description
`id` required	string	At most 100 characters.

curl "https://api.ctpeway.com/v1/invoices/{id}" \
  -H "Authorization: Bearer $CTPEWAY_API_KEY"

import { CtpeWay } from '@ctpeway/sdk';

const ctpeway = new CtpeWay(process.env.CTPEWAY_API_KEY);

const result = await ctpeway.invoices.retrieve('<id>');

Response

200 OK

Field	Type	Description
`id`	string
`number`	integer
`status`	string	One of `open`, `pending`, `underpaid`, `paid`, `expired`, `canceled`, `refunded`.
`outcome_flags`	array of strings	Values: `overpaid`, `late`, `underpaid_accepted`, `partially_refunded`.
`kind`	string	One of `fiat`, `crypto`.
`price` optional	object
`price.currency`	string
`price.amount`	string	A decimal number written as a string, with up to 8 decimal places.
`options`	array of objects
`options[].id`	string
`options[].network`	string
`options[].asset`	string
`options[].asset_id`	string
`options[].contract` optional	string
`options[].decimals`	integer
`options[].amount_due` optional	string	Set once the option is selected (fiat invoices). A quoted amount is rounded up to `display_decimals`, so the amount shown to the payer is exactly the amount that pays the invoice. A whole number written as a string of digits.
`options[].display_decimals` optional	integer	Present with `amount_due`: the decimals it is stated with. `amount_due` is a whole number of 10^(decimals − display_decimals) base units; equal to `decimals` when the amount is exact to the base unit (crypto invoices).
`options[].rate` optional	string	Price of one unit of the asset in the invoice currency at lock time. A decimal number written as a string, with up to 8 decimal places.
`options[].quote_expires_at` optional	string (date-time)	Until when `amount_due` holds. Afterwards the payer takes a new quote; the invoice lives on.
`options[].address` optional	string
`options[].token_account` optional	string	Solana tokens: the address’s associated token account, where the token is held.
`options[].selected_at` optional	string (date-time)
`options[].amount_paid`	string	Sum of confirmed payments to this option. A whole number written as a string of digits.
`options[].amount_detected`	string	Sum of detected, unconfirmed payments to this option. A whole number written as a string of digits.
`selected_option_id` optional	string
`paid_option_id` optional	string
`tolerance_bps`	integer
`order_id` optional	string
`customer_email` optional	string	The customer the merchant named when creating the invoice.
`description` optional	string
`metadata` optional	map of string to string
`expires_at`	string (date-time)
`pre_selection_expires_at`	string (date-time)
`created_at`	string (date-time)
`paid_at` optional	string (date-time)
`expired_at` optional	string (date-time)
`canceled_at` optional	string (date-time)
`refunded_at` optional	string (date-time)	When the invoice became `refunded`.
`livemode`	boolean	`false` for objects of the test environment.
`checkout_url`	string	The hosted checkout page of this invoice. Send the payer here.

{
  "id": "string",
  "number": 0,
  "status": "open",
  "outcome_flags": [
    "overpaid"
  ],
  "kind": "fiat",
  "price": {
    "currency": "string",
    "amount": "10.00"
  },
  "options": [
    {
      "id": "string",
      "network": "string",
      "asset": "string",
      "asset_id": "string",
      "contract": "string",
      "decimals": 0,
      "amount_due": "1000000",
      "display_decimals": 0,
      "rate": "10.00",
      "quote_expires_at": "2026-01-01T00:00:00.000Z",
      "address": "string",
      "token_account": "string",
      "selected_at": "2026-01-01T00:00:00.000Z",
      "amount_paid": "1000000",
      "amount_detected": "1000000"
    }
  ],
  "selected_option_id": "string",
  "paid_option_id": "string",
  "tolerance_bps": 0,
  "order_id": "string",
  "customer_email": "string",
  "description": "string",
  "metadata": {},
  "expires_at": "2026-01-01T00:00:00.000Z",
  "pre_selection_expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "paid_at": "2026-01-01T00:00:00.000Z",
  "expired_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "refunded_at": "2026-01-01T00:00:00.000Z",
  "livemode": true,
  "checkout_url": "string"
}

The values are placeholders generated from the schema. They show the shape, not real data.

Errors

A failed request answers with the error format described under Errors.

Besides the codes any endpoint can return, this endpoint can answer with these code values:

invoice_not_found