Raelic

Guides

Integration Guide

Use this guide to plan, implement, test, and launch your Raelic integration before diving into endpoint-level API Reference details.

Open API Reference Request Access

Before You Start

Prerequisites

  • Active merchant account and API key.
  • Sandbox access for development and QA.
  • Server endpoint to receive webhook events.
  • Storage for IDs and status history for reconciliation.

Environment Model

All endpoints are versioned with /v1. Build and validate in Sandbox first, then move to Production with the same request contracts.

Sandbox: https://sandbox-api.platform.raenest.com
Production: https://api.platform.raenest.com

Authentication, Requests, and Responses

Authentication

Send your merchant API key as a Bearer token for authenticated endpoints.

Authorization: Bearer YOUR_API_KEY

Production IP Allowlisting

Production API access is restricted to allowlisted source IP addresses. Before go-live, share your static outbound IPs so they can be added to your merchant profile.

If your infrastructure changes egress IPs (for example, autoscaling without a fixed NAT), requests can be blocked until the new IPs are allowlisted.

Response Envelope

All responses follow a consistent envelope. Handle the errors field explicitly even when HTTP status is successful.

{
  "message": "success",
  "errors": null,
  "data": { ... }
}

Error Handling

Validation and business failures return structured errors. Persist request identifiers and references so you can retry and investigate safely.

Recommended Integration Flow

1. Create Customer Profiles

Create and store customer records first. Most downstream flows reference a customer ID.

2. Run KYC/CIP Checks

Submit identity checks and wait for approved outcomes before enabling account creation or money movement.

3. Generate Accounts

Create virtual accounts for eligible customers and fetch balances for reconciliation workflows.

4. Prepare Transfers

Fetch transfer requirements, create quotes, and validate destination details before initiating payouts.

5. Execute Transfers

Submit transfer requests with unique references from your system and track each transfer state.

6. Reconcile with Transactions + Webhooks

Use transaction history and webhook events together to maintain accurate internal ledgers and user-visible statuses.

Webhooks and Testing Strategy

Sandbox Validation

Use simulation endpoints to test CIP, inflow, and transfer-status webhook handling before go-live.

Confirm idempotent processing so duplicate delivery does not create duplicate side effects.

Production Readiness

  • Verify webhook signatures on every callback.
  • Store raw payloads and processing outcomes for audits.
  • Alert on failed webhook processing and retry backlog growth.

Go-Live Checklist

  • Sandbox happy-path and failure-path tests completed.
  • Auth, permissions, and rate controls verified.
  • Reconciliation reports validated against API transactions.
  • Webhook retries and incident alerts tested end-to-end.
  • Production credentials rotated and stored securely.

When you are ready to implement each endpoint, continue to the API Reference for required fields, request payloads, and response examples.