An API that shows its working.

1. Get your test keys

   Request access and we’ll send you a secret key starting sk_test_. Test mode needs no paperwork. Keep the key on your server, never in the browser.

2. Create a payment

   Amounts are in cents. Send an idempotency key so a retry can never charge twice.

   cURLTypeScript

   POST /v1/payments

   curl https://api.rano.co.za/v1/payments \
     -H "Authorization: Bearer $RANO_SECRET_KEY" \
     -H "Idempotency-Key: order-2048" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 38600,
       "currency": "ZAR",
       "payment_method_type": "card",
       "confirm": true
     }'

3. Read the result

   The payment comes back with its status and the full fee breakdown, like the object at the top of this page. Listen for webhooks to hear about anything that changes after the call returns.

VAT at 15% applies to our margin only and is already in it: fee.vat shows how much, and fee.margin_excl_vat the rest. net is what reaches your bank account: amount minus fee.total.

POST /webhooks/rano HTTP/1.1
Content-Type: application/json
Rano-Signature: t=1791532800,v1=5f0c9e2a7b…

{
  "id": "evt_01k7f3m9t5r2y8d4p6e0a3s9gq",
  "object": "event",
  "type": "payment.succeeded",
  "livemode": false,
  "created": 1791532800,
  "data": {
    "object": { "id": "pay_01k7f3m9q2v8x4c6n0b5h1t7wz", "status": "succeeded", … }
  }
}

Verify the signature

The Rano-Signature header holds a Unix timestamp t and v1, a hex HMAC-SHA256 of <t>.<body> using your endpoint’s secret. The SDK checks it for you, including rejecting timestamps more than five minutes old to block replays.

import { Rano } from "@rano/sdk";

const rano = new Rano(process.env.RANO_SECRET_KEY);

// Throws if the signature doesn't match. Pass the body exactly as received.
const event = rano.webhooks.constructEvent(
  rawBody,
  req.headers["rano-signature"],
  process.env.RANO_WEBHOOK_SECRET,
);

Events

payment.created

A payment was created.

payment.requires_action

Waiting on the customer: 3D Secure, approval in their banking app, or an EFT.

payment.succeeded

Money is confirmed. Safe to fulfil the order.

payment.failed

The payment was declined or failed. last_error says why.

payment.canceled

You canceled the payment, or the customer didn’t approve it in time. cancellation_reason says which.

refund.created

A refund was created and is on its way to the bank.

refund.succeeded

The refund has been sent back to the customer.

refund.failed

The bank rejected the refund. failure_code says why.

• Delivery is at least once. Use the event id to ignore duplicates.
• Order isn’t guaranteed. Each event carries the object as it was when the event happened. When order matters, retrieve the object for its latest state.
• Reply with any 2xx quickly, then do slow work in the background.
• Missed one? Every event can be fetched again with GET /v1/events or GET /v1/events/:id.

PayShap and EFT in test mode

PayShap and EFT payments wait for the customer, just like in real life, unless the amount picks one of the outcomes above. In test mode, play the customer with a test helper: approve or decline. Test helpers don’t exist in live mode. Refunds follow the same rule: an amount ending in 01 is rejected, and 05 times out, then succeeds.

// PayShap and EFT payments wait for the customer in test mode too.
await rano.testHelpers.payments.approve("pay_01k7f3m9q2v8x4c6n0b5h1t7wz");

// Or have the customer say no.
await rano.testHelpers.payments.decline("pay_01k7f3m9q2v8x4c6n0b5h1t7wz");

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "currency is required.",
    "param": "currency"
  }
}

Common codes

parameter_missing

A required parameter wasn’t sent.

parameter_invalid

A parameter has the wrong type or format.

parameter_unknown

A parameter we don’t recognise. Check the spelling.

amount_too_small

The fee would be at least the whole payment. Use a larger amount.

payment_method_unavailable

That payment method isn’t available for this currency yet.

payment_unexpected_state

The payment can’t do that from its current status.

resource_missing

No object with that ID on your account.

api_key_invalid

The API key isn’t recognised or has been revoked.

api_key_wrong_mode

A live key sent to test mode, or the other way round.

idempotency_key_reused

The same Idempotency-Key with a different request body.

Declines aren’t errors

A declined payment is a normal result, not an HTTP error. You get 200 and the payment, with status: failed and last_error holding a code for your logic and a sentence you can show your customer.

{
  "id": "pay_01k7f3n2c8w5j9r1x6m4d0a7kp",
  "object": "payment",
  "amount": 10001,
  "status": "failed",
  "last_error": {
    "code": "insufficient_funds",
    "message": "The customer's account has insufficient funds."
  },
  …
}

TypeScript SDK

@rano/sdk: typed methods for payments, refunds, events and webhook endpoints, webhook verification, idempotency keys and automatic retries.

OpenAPI spec

One file describing every endpoint, object and error, served at GET /openapi.json.