Skip to main content
GET
/
api
/
v1
/
invoices
/
{invoiceId}
/
status
Poll invoice status
curl --request GET \
  --url https://api-beta.pepay.io/api/v1/invoices/{invoiceId}/status \
  --header 'x-api-key: <api-key>'
{
  "object": "invoice_status",
  "invoice": {
    "object": "invoice",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_id": 123,
    "status": "paid",
    "invoice_type": "standard",
    "currency": "usd",
    "amount": 49990,
    "amount_decimal": "49.990",
    "amount_unit": "usd_millis",
    "environment": "devnet"
  },
  "latest_payment": {
    "object": "invoice_payment",
    "id": "550e8400-e29b-41d4-a716-446655440111",
    "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_id": 123,
    "status": "confirmed",
    "settlement_status": "settled",
    "currency": "usd",
    "amount": 49990,
    "amount_decimal": "49.990",
    "amount_unit": "usd_millis"
  }
}

​
Overview

Use this endpoint to get the latest invoice status and any associated payment/settlement summaries.

​
Authentication

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

​
Request

​
SDK

const status = await pepay.invoices.status('550e8400-e29b-41d4-a716-446655440000');

​
cURL

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

curl "https://api-beta.pepay.io/api/v1/invoices/$INVOICE_ID/status" \
  -H "x-api-key: sk_live_..."

​
Response

{
  "object": "invoice_status",
  "invoice": {
    "object": "invoice",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_id": 123,
    "status": "paid",
    "invoice_type": "standard",
    "currency": "usd",
    "amount": 49990,
    "amount_decimal": "49.990",
    "amount_unit": "usd_millis",
    "environment": "devnet"
  },
  "latest_payment": {
    "object": "invoice_payment",
    "id": "550e8400-e29b-41d4-a716-446655440111",
    "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_id": 123,
    "status": "confirmed",
    "settlement_status": "settled",
    "settlement": {
      "summary_status": "settled",
      "stage": "final",
      "merchant_settlement_id": 30,
      "settlement_tx_hash": "0xabc123",
      "network": "bsc",
      "status": "settled"
    }
  }
}

​
Errors

  • 400 invalid invoice id
  • 401 missing/invalid merchant auth
  • 404 invoice not found

​
Examples

Poll until the invoice is terminal: 
const status = await pepay.invoices.waitForStatus(invoiceId, { timeoutMs: 5 * 60 * 1000 });
Next: List merchant tokens

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

Response

Invoice status retrieved successfully

​
object
string
Example:

"invoice_status"

​
invoice
object

Canonical invoice object (snake_case, usd_millis amounts).

​
latest_payment
object

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