Integration Guides
Plan your integration.
Hosted Checkout integration
Redirect the customer to a Rainbow Pay-hosted payment page and receive the result on your server. Card details are entered on the hosted page, not on your site.
For: Merchants who want to accept card and wallet payments without building their own payment form.
- 1
Get sandbox access
Sandbox credentials are issued during onboarding. The sandbox emulates processing, so you can build and test without moving real money. Store credentials on your server only.
- 2
Create the payment on your server
When the customer is ready to pay, your server sends a payment request with the amount, currency, your order reference, a success URL, a fail URL and a callback URL. Never create payments from browser code.
- 3
Save the payment token and redirect
The response contains a payment token and the address of the hosted payment page. Store the token against the order, then redirect the customer to the page.
- 4
Handle the customer's return
After paying, the customer is returned to your success or fail URL. Show them a clear message, but do not treat the return as proof of payment. A customer can close the browser or open the URL directly.
- 5
Confirm the status on your server
Update the order from the callback sent to your callback URL, and confirm the status through the API using the payment token before fulfilling. See Handling callbacks.
- 6
Test, then request go-live
Test approved, declined and abandoned payments, and refunds, in the sandbox. Production access follows compliance, commercial and technical approval. Field names and formats are in the API documentation (opens in a new tab).
Server-to-server API payments
Create and manage payments directly from your server through the Rainbow Pay API, including two-step payments and refunds.
For: Development teams building a custom checkout who can meet the security obligations that come with it.
- 1
Decide how card data will be collected
Sending raw card data from your server brings your systems into PCI DSS scope and requires Rainbow Pay approval. Confirm your approach during onboarding, before you build. If you do not need to handle card data, consider Hosted Checkout.
- 2
Secure your credentials and environments
Keep API credentials on the server, out of source control and client code. Use separate credentials for sandbox and production, and restrict who can read them.
- 3
Create payments
Send the payment request with the amount, currency, order reference and callback URL. Store the payment token from the response against the order.
- 4
Use two-step payments where the amount or stock is confirmed later
Set needConfirmation on the payment request, then confirm or decline the payment through the API once you have checked the order.
- 5
Handle errors and retries safely
Set timeouts on every call. If a response is lost, query the payment by its token before retrying, so a retry cannot create a duplicate charge.
- 6
Refunds, disputes and balance
Issue full or partial refunds against the payment token. Retrieve dispute information through the list endpoint and check available funds through the balance endpoint.
- 7
Test the full lifecycle
Exercise approvals, declines, confirmations, refunds and callbacks in the sandbox before requesting go-live. Endpoint details are in the API documentation (opens in a new tab).
Handling callbacks
Receive payment status changes on your server and process them safely, even when notifications are repeated, delayed or out of order.
For: Developers responsible for order fulfilment and payment status in a Rainbow Pay integration.
- 1
Expose an HTTPS endpoint
Provide a callback URL on your server that accepts POST requests. Rainbow Pay sends a callback when a payment's status changes, for example to pending, approved or declined.
- 2
Verify every request
Check authenticity using the method described in the API documentation (opens in a new tab), and confirm that the payment token belongs to one of your orders. Reject anything that fails.
- 3
Record it and answer 200 quickly
Store the callback durably and respond with HTTP 200. Do slow work, such as emails or stock updates, in a separate process. A non-200 response causes the callback to be retried.
- 4
Process idempotently
The same callback can arrive more than once. Key processing on the payment token and status so that handling a message twice has the same effect as handling it once.
- 5
Respect the order of states
Callbacks can arrive out of order. Do not let a pending notification overwrite a final approved or declined status.
- 6
Reconcile with the API
Before fulfilling, confirm the status through the API. Run a scheduled check for payments that stay pending longer than expected, to catch callbacks missed during an outage. See Designing reliable payment callbacks.
Recurring payments
Take a first payment with the customer present, then charge later repeat payments using a recurring token.
For: Merchants with subscriptions, instalments or other agreed repeat charges.
- 1
Agree the terms with the customer
Before the first payment, show the amount, frequency, start date and how to cancel, and record the customer's agreement. Recurring availability can vary by payment method.
- 2
Mark the first payment as recurring
Create the customer's first payment with recurring: true. The customer completes it in the usual way, through Hosted Checkout or your approved API flow.
- 3
Store the recurring token
When the first payment is approved, the response includes a recurringToken. Store it securely against the customer's agreement. It is not a card number, but it can be used to charge the customer, so protect it accordingly.
- 4
Create repeat payments
For each later charge, your server creates a payment with the recurring token and the amount due under the agreement. Handle the result through callbacks, as for any payment.
- 5
Handle declines and cancellations
Decide in advance how many times you will retry a declined repeat payment and how you will contact the customer. Stop charging immediately when a customer cancels.
- 6
Test the cycle
In the sandbox, test the first payment, a successful repeat, a declined repeat and a cancellation. Request fields are in the API documentation (opens in a new tab).
Ready to discuss your payment setup?
Tell us how your business accepts payments today and what you need from your next payment integration.