Developers

API overview

A single REST API for payments, refunds, payouts, balance and disputes. This page summarises how it works; the documentation holds the complete reference.

Read documentation Get started

Authentication

Every request is made over HTTPS and carries your private API key as a bearer token. Requests over plain HTTP, or without a valid key, are rejected.

Keep private keys on your server and out of source control, browsers and mobile apps. Sandbox and production keys are different and are issued separately.

Conventions

JSON request and response bodies.
Amounts in minor units of the currency (for example, cents).
Each payment, refund and payout is identified by a token.
Your own reference travels as orderNumber and is returned in callbacks.

Resources

Authorization header

Authorization: Bearer YOUR_PRIVATE_KEY

Create payment — response

{
  "success": true,
  "errors": [],
  "token": "pt_3f9c1e7a52b84d06",
  "processingUrl": "<hosted payment page URL>",
  "payment": {
    "amount": 125000,
    "currency": "HKD",
    "status": "init"
  }
}

Fictional example values.

Payments

Create, retrieve and list payments; confirm or decline two-step payments.

POST /api/v1/payments
GET /api/v1/payments/{token}
GET /api/v1/payments
POST /api/v1/payments/confirm
POST /api/v1/payments/decline

Refunds

Refund a payment in full, or in part by passing an amount.

POST /api/v1/refunds

Payouts

Initiate supported payout operations.

POST /api/v1/payouts

Balance

Available and held amounts for a currency.

GET /api/v1/balance

Disputes

The most recent dispute records for your account.

GET /api/v1/disputes/list

Notifications

Status changes delivered to your server.

POST {callbackUrl}

Payment states

State	Final	Meaning
init	No	The payment has been created.
pending	No	The customer is completing payment.
approved	Yes	The payment completed successfully.
declined	Yes	The payment did not complete.
refunded	Yes	The payment was refunded.
expired	Yes	The payment was abandoned.

Errors

A failed call returns success: false with a list of errors, each with a code and a kind:

Kind	Meaning
api_error	A rare problem on the Rainbow Pay side.
authentication_error	The request could not be authenticated.
invalid_request_error	A parameter is missing or invalid.
processing_error	The operation could not be processed.

Parameters, validation rules and error codes are listed in the API documentation (opens in a new tab). Where this page and the documentation differ, the documentation applies.

Lifecycle

From request to callback.

Merchant server
Creates the payment with your private key.
POST /api/v1/payments
Rainbow Pay API
Validates the request and returns a payment token.
200 · token
Payment processing
The customer pays; authentication runs where required.
Result
The payment reaches a final status.
approved | declined
Callback
Status is posted to your callback URL.
POST callbackUrl

Ready to discuss your payment setup?

Tell us how your business accepts payments today and what you need from your next payment integration.

Get started Contact sales