Quick start

This guide takes you from nothing to a created invoice. Every request goes to https://api.roamerwave.com, uses JSON, and is authenticated with an API key.

1. Get a test API key

A workspace owner creates keys in the Developers section of the Roamerwave workspace. A key has a name and only the scopes you choose:

Keys beginning rw_test_ act on your test environment, where no real money moves. Keys beginning rw_live_ act on your live environment. The full key is shown once when it is created, so store it as a secret. Never put it in a web page or a mobile app.

Send it on every request:

Authorization: Bearer rw_test_…

2. Send an Idempotency-Key on every write

Each POST needs an Idempotency-Key header of 8 to 255 characters. If a request times out or you are unsure whether it arrived, send it again with the same key and the same body: you get the original result back, never a second invoice. Use a key that comes from your own record, such as an order number.

3. Add a customer

curl https://api.roamerwave.com/v1/customers \
  -H "Authorization: Bearer rw_test_…" \
  -H "Idempotency-Key: customer-amina-otieno" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "amina-otieno",
    "name": "Amina Otieno",
    "phone": "+254712345318"
  }'

The phone number is a Kenyan mobile number in international format. The response returns the customer with its id (starting cus_). The phone number itself is never returned, only a masked form.

4. Create an invoice

Money is always an object with minor and currency. minor is an amount in integer minor units, sent as a string, so KES 1,350.00 is "135000".

curl https://api.roamerwave.com/v1/invoices \
  -H "Authorization: Bearer rw_test_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_…",
    "amount": { "minor": "135000", "currency": "KES" },
    "description": "Monthly membership, October",
    "dueAt": "2026-10-31T20:59:59Z",
    "reference": "order-1042"
  }'

An amount outside the range allowed for your workspace is refused with 422 AMOUNT_OUT_OF_RANGE.

5. Read it back

curl https://api.roamerwave.com/v1/invoices/inv_… \
  -H "Authorization: Bearer rw_test_…"

An invoice reports three things separately, and you should read them separately:

• paymentStatus: due, pending, unknown, succeeded or failed.
• reconciliationStatus: whether the confirmed payment has been matched to this invoice.
• settlementStatus: whether the provider has reported the money as settled to you.

A payment can succeed before it is reconciled, and be reconciled before it is settled. None of them implies the next.

Errors

Every error has the same shape. Quote requestId when you contact support.

{
  "error": {
    "code": "AMOUNT_OUT_OF_RANGE",
    "message": "…",
    "requestId": "req_…",
    "details": []
  }
}

Next

• Take a payment with a hosted checkout link.
• Subscribe a customer so invoices are created for you each period.
• Verify webhooks so your system hears about payments as they happen.
• The API reference lists every endpoint and field.