API reference

Every endpoint, every parameter. Short by design, because the why is on the pages either side of this one.

Conventions


Base URL	`https://api.xendlypay.com`
Auth	`Authorization: Bearer <key>` or `X-Api-Key`
Content type	application/json, both directions
Amounts	Integers in minor units. RWF has no cents.
Timestamps	RFC 3339, UTC
Ids	UUIDs

Successes are wrapped:

{
  "success": true,
  "payload": { "id": "0f8c2b7e…", "status": "pending", "amount": 5000 },
  "timestamp": "2026-09-12T09:14:02.000Z"
}

Errors are not. They key on status instead. See errors and limits.

Create a payment (cash in)

POST/v1/payments

Field	Type	Required
`amount`	integer, minor units, ≥ 100	yes
`msisdn`	string, MTN or Airtel RW	yes
`currency`	string, RWF	no
`description`	string	no
`reference`	string	no
`metadata`	object	no
`method`	"prompt" (default) or "dial"	no

With "method": "dial" the customer dials a short code instead of approving a prompt, and the response carries pay_with (what to dial, and a QR code of it in pay_with.qr). Pay by dialing.

Header: Idempotency-Key, optional but strongly advised. Returns 201 with a pending transaction. Full page.

Create a payout (cash out)

POST/v1/payouts

Same body as a payment. Requires an approved merchant, a live app, and an available balance covering amount plus fee. The amount must be at least 10,000 RWF; the networks do not send less. Returns 201; 409 when the balance will not cover it. Full page.

Refund a payment

POST/v1/payments/:id/refund

Field	Type	Required
`amount`	integer, omit to refund in full	no
`reason`	string, up to 64 characters	no

Only a succeeded cash in can be refunded, and only once. Returns 201 with a new payout carrying reverses_payment_id. Full page.

Retrieve a payment

GET/v1/payments/:id

Scoped to the key’s app: a payment belonging to another app answers 404, not 403. Authoritative and permanent, so it is safe to use for reconciliation.

List payments

GET/v1/payments

Query	Values	Notes
`status`	pending, succeeded, failed, cancelled, all	Omit or `all` for no filter
`kind`	CASHIN, CASHOUT	Or `direction=collect\|payout`
`network`	mtn, airtel	Routed from the number, not chosen
`msisdn`	any format	Normalised before matching, so 078… finds 250 78…
`from`	YYYY-MM-DD	Inclusive
`to`	YYYY-MM-DD	Inclusive of the whole day
`limit`	1–100, default 50. Anything outside that becomes 50.
`offset`	integer

{
  "success": true,
  "payload": {
    "payments": [ … ],
    "total": 214
  },
  "timestamp": "2026-09-12T09:14:02.000Z"
}

app_id and mode are not yours to set here

An app key always sees its own app, in its own mode, whatever the query string says. Otherwise ?app_id= would be an access-control decision made by the caller.

Balance

GET/v1/balance

Optional ?currency=RWF. Returns pending and available for the key’s mode. Full page.

The payment object

Field	Type	Notes
`id`	uuid	Ours. Store it against your order.
`kind`	string	Alias for direction: `CASHIN` or `CASHOUT`
`direction`	string	collect \| payout
`status`	string	pending \| succeeded \| failed \| cancelled
`amount`	integer	Minor units, what the customer paid or received
`fee`	integer	Our cut, at the rate that applied when it happened
`currency`	string	RWF
`msisdn`	string	Country-coded: 250781234567
`network`	string	mtn \| airtel \| unknown
`mode`	string	test \| live
`reference`	string \| null	Yours
`metadata`	object \| null	Yours, untouched
`failure_code`	string \| null	The gateway's code, when it gave one
`failure_message`	string \| null	Readable reason
`initiated_by`	string	api \| dashboard: who asked
`reverses_payment_id`	uuid \| null	Set on a refund
`created_at`	timestamp
`completed_at`	timestamp \| null	When it reached a final status
`settled_at`	timestamp \| null	When it became withdrawable

← Errors and limits Schemas →