Payments API

Use the Payments API to record and retrieve payments associated with invoices.

Payment object

Field	Type	Description
id	string	Payment ID with the pay_ prefix.
invoice_id	string	Invoice receiving the payment.
customer_id	string	Customer associated with the invoice.
amount	integer	Payment amount.
currency	string	ISO 4217 currency code.
method	string	bank_transfer, cash, card, mobile_money, or other.
status	string	pending, completed, failed, or refunded.
reference	string | null	Payment reference.
paid_at	string	ISO 8601 timestamp.
created_at	string	ISO 8601 timestamp.

List payments

GET /payments

Filters: invoice_id, customer_id, status, method, from, to, page, limit.

Create a payment

POST /payments

Required: invoice_id, amount, method.

Financial writes should include an idempotency key.

curl -X POST https://api.cedius.app/v1/payments   -H "Authorization: Bearer cedius_test_sk_example"   -H "Content-Type: application/json"   -H "Idempotency-Key: payment-order-4832"   -d '{
    "invoice_id": "inv_91ac20",
    "amount": 161250,
    "method": "bank_transfer",
    "reference": "TRX-20260910-8821"
  }'

201 Created

{
  "data": {
    "id": "pay_72bd13",
    "invoice_id": "inv_91ac20",
    "customer_id": "cus_4d7c21",
    "amount": 161250,
    "currency": "NGN",
    "method": "bank_transfer",
    "status": "completed",
    "reference": "TRX-20260910-8821",
    "paid_at": "2026-09-10T08:45:00Z",
    "created_at": "2026-09-10T08:45:02Z"
  }
}

Invoice status behavior

When completed payments equal the invoice total:

invoice.status -> paid

When completed payments are greater than zero but below the total:

invoice.status -> partially_paid

Retrieve a payment

GET /payments/{payment_id}

Completed payments are not directly edited. Corrections should use an explicit financial operation such as a refund.