Skip to main content
GET
/
api
/
v1
/
invoices
/
{invoiceId}
Retrieve invoice details
curl --request GET \
  --url https://api-beta.pepay.io/api/v1/invoices/{invoiceId} \
  --header 'x-api-key: <api-key>'
{
  "object": "invoice",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": 123,
  "status": "unpaid",
  "invoice_type": "standard",
  "currency": "usd",
  "amount": 49990,
  "amount_decimal": "49.990",
  "amount_paid": 0,
  "amount_paid_decimal": "0.000",
  "amount_remaining": 49990,
  "amount_remaining_decimal": "49.990",
  "amount_unit": "usd_millis",
  "customer_id": "cust_123",
  "environment": "devnet",
  "created_at": 1766318400,
  "expires_at": 1766322000,
  "metadata": {
    "order_id": "ORD-123"
  }
}

​
Overview

Use this endpoint to fetch an invoice by id. Prefer using expand to request any related fields you need in one call.

​
Authentication

  • Merchant server auth: x-api-key or Authorization: Bearer <jwt>

​
Request

​
SDK

const invoice = await pepay.invoices.retrieve('550e8400-e29b-41d4-a716-446655440000', {
  expand: ['latest_payment', 'payments'],
  payments_limit: 10
});

​
cURL

INVOICE_ID="550e8400-e29b-41d4-a716-446655440000"

curl "https://api-beta.pepay.io/api/v1/invoices/$INVOICE_ID?expand=latest_payment,payments&payments_limit=10" \
  -H "x-api-key: sk_live_..."

​
Response

{
  "object": "invoice",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": 123,
  "status": "unpaid",
  "invoice_type": "standard",
  "currency": "usd",
  "amount": 49990,
  "amount_decimal": "49.990",
  "amount_unit": "usd_millis",
  "environment": "devnet",
  "expires_at": 1766322000,
  "created_at": 1766318400,
  "metadata": {
    "order_id": "ORD-123"
  }
}

​
Errors

  • 400 invalid parameters (including unsupported expand values)
  • 401 missing/invalid merchant auth
  • 404 invoice not found

​
Examples

Retrieve an invoice with the latest payment attached: 
const invoice = await pepay.invoices.retrieve(invoiceId, { expand: ['latest_payment'] });
const latestPayment = invoice.latest_payment;
Next: Get invoice status

Authorizations

​
x-api-key
string
header
required

API key for server-to-server operations (scope=merchant or commerce)

Path Parameters

​
invoiceId
string<uuid>
required

Invoice ID

Query Parameters

​
expand
string

Comma-separated expansions (latest_payment, payments).

​
payments_limit
integer
default:10

Max payments per invoice when expand includes payments.

Required range: 1 <= x <= 100

Response

Invoice retrieved successfully

Canonical invoice object (snake_case, usd_millis amounts).

​
object
string
Example:

"invoice"

​
id
string
Example:

"550e8400-e29b-41d4-a716-446655440000"

​
merchant_id
integer
Example:

123

​
status
string
Example:

"paid"

​
invoice_type
string
Example:

"standard"

​
currency
string
Example:

"usd"

​
amount
integer

Total invoice amount in USD mills (1 USD = 1000 mills). For UI display, use amount_decimal.

Example:

10000

​
amount_decimal
string

Display-friendly USD string with 3 decimals (derived from amount).

Example:

"10.000"

​
amount_paid
integer

Total amount paid in USD mills (1 USD = 1000 mills). For UI display, use amount_paid_decimal.

Example:

10000

​
amount_paid_decimal
string

Display-friendly USD string with 3 decimals (derived from amount_paid).

Example:

"10.000"

​
amount_remaining
integer

Remaining amount in USD mills (1 USD = 1000 mills). For UI display, use amount_remaining_decimal.

Example:

0

​
amount_remaining_decimal
string

Display-friendly USD string with 3 decimals (derived from amount_remaining).

Example:

"0.000"

​
amount_unit
string

Always usd_millis (amount fields are USD * 1000).

Example:

"usd_millis"

​
customer_id
string | null
​
payer_wallet_address
string | null
​
payer_wallet_network
string | null
​
commerce_order_id
string | null
​
environment
enum<string>
Available options:
devnet,
mainnet
​
expires_at
integer | null
​
created_at
integer | null
​
paid_at
integer | null
​
last_payment_at
integer | null
​
metadata
object
​
latest_payment
object

Canonical invoice_payment object (merchant surfaces include settlement fields; payor surfaces strip them).

​
payments
object[]