Payments

The Payments API handles outbound payouts — creation, status lookup, listing, and retry. All amounts are in the given currency's major unit (e.g. 500.00 USD) unless the endpoint says otherwise.

Create Payout

POST /v1/payments/initiate → POST /v1/payments/confirm

List payments

GET /api/v1/payments

Returns a paginated list of the current user's payments, most recent first.

Query param	Type	Default	Notes
`page`	`number`	`1`	1-indexed.
`limit`	`number`	`20`	Capped at `100`.
`status`	`string`	—	Exact-match filter, e.g. `?status=CONFIRMED`.

curl "https://api.lumeo.co.in/api/v1/payments?status=CONFIRMED&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response — 200 OK

{
  "items": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "txnId": "txn-7d1b6e2a-7c3e-4b9a-9b1a-3e9a2b5d9c44",
      "userId": "user_01j4abc",
      "amount": 500.00,
      "currency": "USD",
      "status": "CONFIRMED",
      "type": "SEND",
      "createdAt": "2026-06-30T09:14:22.000Z",
      "updatedAt": "2026-06-30T09:16:05.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10
}

Get payment status

GET /api/v1/payments/:id/status

Despite the path, the :id here is matched against the payment's txnId (the client-generated idempotency reference), not its id. If you stored the id from the create-payout response and pass it here, the lookup will not match. Use the txnId you generated when calling initiate.

Returns the full payment object (same shape as the list response above), or null if no payment matches.

Retry a failed payment

POST /api/v1/payments/:id/retry

This :id is the payment's id (not txnId) — the opposite convention from the status endpoint above. Double-check which identifier you're passing to which route.

No request body. Only allowed when the payment's current status is FAILED or PENDING. On success, the payment moves to PROCESSING and the updated record is returned.

curl -X POST https://api.lumeo.co.in/api/v1/payments/clx1a2b3c4d5e6f7g8h9/retry \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

There is no dedicated cancel endpoint. retry is the only way to act on an existing payment once it's been confirmed — you cannot cancel a payment that's already in PROCESSING or later.

Form 15CA prefill

GET /api/v1/payments/:id/form15ca

Returns prefill data for India's RBI/FEMA Form 15CA, needed for cross-border remittances. :id here is the payment's id.

{
  "part": "C",
  "remittanceAmount": "500.00",
  "currency": "USD",
  "purposeCode": "P0801",
  "invoiceRef": "invoice-2026-0142",
  "beneficiaryName": "Acme Corp",
  "beneficiaryCountry": "US",
  "beneficiaryBank": "Chase Bank",
  "stellarTxRef": "7d1b6e2a...",
  "requiresCA": true,
  "note": "Form 15CA Part C — chartered accountant certification required for remittances above ₹5,00,000."
}

part is "C" when the remittance amount is ₹5,00,000 or above (requiring CA certification via Form 15CB), and "A" otherwise.

Provider health

GET /api/v1/payments/providers/health

{ "status": "HEALTHY", "stellar": "UP" }

This is a static status check, not a live upstream health probe. Use it as a smoke test, not as a circuit-breaker signal.