Step-by-step guide to integrate Ralio using the sandbox environment — users, KYC, funding, transfers, and webhooks. This guide walks you through a complete Ralio integration from scratch using the sandbox environment. No real money, no real KYC — fully simulated.

Sandbox Portal

Manage API keys, simulate KYC approvals, and monitor operations
https://portal.sandbox.raliopay.com

Sandbox API

https://sandbox-revo-api.raliopay.com

Integration flow

Setup — API Keys & Webhooks

Every Ralio integration follows the same sequence. Each step depends on the previous one.

Create a user

Generate your API credentials and configure your webhook endpoint from the Portal.

Verify the user (KYC / KYB)

Launch an identity verification session. In sandbox you approve it manually.

Create an account (Wallet)

Once the user is verified, create one or more accounts in any supported currency.

Fund the account (Payin)

Add funds via bank transfer, crypto deposit, or card. Simulate instantly in sandbox.

Move money — Transfer or Payout

Send funds internally between accounts (Transfer) or externally (Payout).

Track Orders & Ledger

Every operation creates an Order. Completed orders appear as entries in the Ledger.

Setup — API Keys & Webhooks

Generate your API credentials and configure webhooks before making any API call.

Step 1 — Generate API Keys

API Keys are managed exclusively from the Ralio Management Portal. You’ll need them to authenticate every API request.

Open the Sandbox Portal

Go to portal.sandbox.raliopay.com/settings/api-keys

Create a new API Key

Click Generate and save both values — you won’t be able to see the api_key again.

Field	Description
`api_code`	Your merchant identifier
`api_key`	Your secret key — treat it like a password

Step 2 — Authenticate (get a Bearer Token)

All API endpoints require a Bearer Token. Exchange your API Key for a token:

POST /api/v1/auth/login

{
  "api_code": "your-api-code",
  "api_key":  "your-api-key"
}

Response 200:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Include this token in every subsequent request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Step 3 — Configure Webhooks

Webhooks let your system react in real time to events without polling.

Go to portal.sandbox.raliopay.com/account/webhooks

Must be a valid https:// URL
Must accept POST requests
Must respond with 2xx within 60 seconds

Select events

Subscribe only to the events you need.

Save your Webhook Secret

Ralio signs every delivery with HMAC-SHA256. Store this secret to verify requests.

Available events

Category	Events
Accounts	`account_activated`
Payins	`payin_processing` · `payin_completed` · `payin_failed` · `payin_canceled`
Payouts	`payout_processing` · `payout_completed` · `payout_failed` · `payout_canceled`
Transfers	`transfer_processing` · `transfer_completed` · `transfer_failed` · `transfer_canceled`
Unmatched Bank Payins	`unmatched_bank_payin_detected` · `unmatched_bank_payin_assigned` · `unmatched_bank_payin_rejected`
Order Requirements	`requirement_created` · `requirement_in_review` · `requirement_more_info` · `requirement_approved` · `requirement_rejected` · `requirement_expired`
KYC	`kyc_state_updated` · `kyc_session_verified` · `kyc_session_manual_review` · `kyc_session_failed` · `kyc_session_expired`
KYB	`kyb_state_updated`
Virtual IBANs	`viban_activated` · `viban_failed` · `viban_deactivated`

See the full catalog with payload examples in Webhooks & Events.

Create a user

Create individual (KYC) or business (KYB) users before issuing accounts or processing transactions.

User types

Individual User

A natural person. Goes through KYC (Know Your Customer) verification.

POST /api/v1/account/individual-users

Business User

A legal entity / company. Goes through KYB (Know Your Business) verification.

POST /api/v1/account/business-user

Save the id returned in the response — you’ll need it for every subsequent operation (KYC sessions, account creation, transfers, etc.).

Verify the user (KYC / KYB)

Launch identity verification sessions for users. In sandbox, approve or reject them instantly from the Portal.

How it works

Create an IDV session

Your backend creates a session for the user and receives a hostedUrl.

User completes verification

In production, the user follows the URL to submit documents.
In sandbox: skip this — approve directly from the Portal.

Receive webhook notification

Ralio notifies your endpoint when the session state changes.

User is verified

Once approved, the user can have accounts and operate.

Create an account (Wallet)

Create wallets for verified users. Required before any funding or payment operation.

A user must be verified (KYC or KYB REGULAR) before you can create accounts for them.

Create a user account

POST /api/v1/account/users/{uid}/accounts
Authorization: Bearer <token>
Content-Type: application/json

{
  "currency": "EUR",
  "alias":    "Main Account"
}

Response 201:

{
  "id":         "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "alias":      "Main Account",
  "currency":   "EUR",
  "balance":    0,
  "pendingIn":  0,
  "pendingOut": 0,
  "state":      "ACTIVE",
  "type":       "Personal"
}

Save the id (Account ID). You’ll need it for funding, transfers, payouts, and querying orders.

Fund the account (Payin)

Add funds via bank transfer, crypto, or card. In sandbox, simulate funding instantly from the Portal.

Payin methods

Bank Payin

User sends a bank transfer to an assigned IBAN. Ralio credits the account once the transfer settles.

Crypto Payin

User sends stablecoins to a generated wallet address. Auto-converted to account currency.

Card Payin

Payment via credit or debit card through an integrated payment gateway.

Simulate Bank Payin and Crypto Payin

Open the Sandbox Portal

Go to portal.sandbox.raliopay.com

Open the Funds Simulator

In the sidebar Developers > Funds Simulator

Select the account

Find it by account ID.

Simulate Funding

Enter the amount and currency, select the funding type and click Simulate Funding

Check payin details

GET /api/v1/account/bank-payins/{oid}

GET /api/v1/account/crypto-payins/{oid}

Webhooks

Event	When
`payin_processing`	Payin detected, waiting for settlement
`payin_completed`	Funds credited to the account
`payin_failed`	Could not be processed

Move money — Transfer or Payout

Move money internally between Ralio accounts (Transfer) or externally to a bank or crypto wallet (Payout).

Transfer

Internal. Between two accounts inside Ralio. Instant, no external intermediaries.

Payout

External. To a bank account (IBAN) or crypto wallet address.

Both operations accept an idempotency key. Send one on every create request so a retry after a timeout can never move the money twice.

Transfers

Create a transfer

POST /api/v1/account/users/{uid}/accounts/{aid}/transfers

Webhooks

Event	When
`transfer_processing`	Being processed
`transfer_completed`	Settled successfully

Payouts

POST /api/v1/account/users/{uid}/accounts/{aid}/bank-payouts

POST /api/v1/account/users/{uid}/accounts/{aid}/crypto-payouts

Example bank payout (SEPA):

{
  "amounts": {
    "debitedAmount":  { "currency": "EUR", "amount": 25000 },
    "receivedAmount": { "currency": "EUR", "amount": 0 }
  },
  "recipient": {
    "beneficiaryType": "PERSON",
    "name":            "Jane",
    "surname":         "Doe",
    "relation":        "FRIEND",
    "accountNumber":   "ES9121000418450200051332",
    "routingData":     "SEPA",
    "bankCountry":     "ES",
    "document": { "documentType": "NATIONAL_ID", "number": "87654321B" },
    "address": {
      "line1":      "Calle Gran Via 123",
      "city":       "Barcelona",
      "province":   "Barcelona",
      "postalCode": "08001",
      "country":    "ES"
    }
  },
  "description":  "Payment for services rendered",
  "ownReference": "INV-1042"
}

Amounts are in minor units (25000 = 250.00 EUR). Provide either amounts.debitedAmount.amount or amounts.receivedAmount.amount and set the other to 0. The payout may require OTP validation before being dispatched — see Create bank payout.

Webhooks

Event	When
`payout_processing`	Submitted to network
`payout_completed`	Funds delivered
`payout_failed`	Could not be processed

Orders

Every operation in Ralio (payin, payout, transfer) generates an Order. Orders are the central record of all operation attempts along with their statuses.

Order States

State	Meaning
`CREATED`	Order received, not yet processed
`PENDING`	Being validated or processed
`SETTLED`	Completed → entry created in Ledger
`FAILED`	Operation failed
`CANCELED`	Canceled before completion
`REVERSING` / `REVERSED`	Refund in progress / refunded

GET /api/v1/account/orders
GET /api/v1/account/users/{uid}/accounts/{aid}/orders

Ledger

The Ledger is the system’s accounting ledger. It contains the immutable record of all transactions that have been successfully completed. Each Order in SETTLED status generates an entry in the Ledger

Difference between Orders and Ledger

	Orders	Ledger
What it records	All operation attempts	Only settled operations
Statuses	CREATED, PENDING, SETTLED, FAILED, CANCELED, REVERSED	Only successful transactions
Main use	Real-time status tracking	Auditing and accounting

GET /api/v1/account/users/{uid}/accounts/{aid}/transactions
GET /api/v1/account/users/{uid}/accounts/{aid}/transactions/{tid}

Getting started

FX

Welcome

Sandbox Portal

Sandbox API

Integration flow

Setup — API Keys & Webhooks

Step 1 — Generate API Keys

Step 2 — Authenticate (get a Bearer Token)

Step 3 — Configure Webhooks

Available events

Create a user

User types

Individual User

Business User

Verify the user (KYC / KYB)

How it works

Create an account (Wallet)

Create a user account

Fund the account (Payin)

Payin methods

Bank Payin

Crypto Payin

Card Payin

Simulate Bank Payin and Crypto Payin

Check payin details

Webhooks

Move money — Transfer or Payout

Transfer

Payout

Transfers

Create a transfer

Webhooks

Payouts

Webhooks

Orders

Order States

Ledger

Difference between Orders and Ledger

Sandbox Portal

Sandbox API

​Integration flow

​Setup — API Keys & Webhooks

​Step 1 — Generate API Keys

​Step 2 — Authenticate (get a Bearer Token)

​Step 3 — Configure Webhooks

​Available events

​Create a user

​User types

Individual User

Business User

​Verify the user (KYC / KYB)

​How it works

​Create an account (Wallet)

​Create a user account

​Fund the account (Payin)

​Payin methods

Bank Payin

Crypto Payin

Card Payin

​Simulate Bank Payin and Crypto Payin

​Check payin details

​Webhooks

​Move money — Transfer or Payout

Transfer

Payout

​Transfers

​Create a transfer

​Webhooks

​Payouts

​Webhooks

​Orders

​Order States

​Ledger

​Difference between Orders and Ledger

Integration flow

Setup — API Keys & Webhooks

Step 1 — Generate API Keys

Step 2 — Authenticate (get a Bearer Token)

Step 3 — Configure Webhooks

Available events

Create a user

User types

Verify the user (KYC / KYB)

How it works

Create an account (Wallet)

Create a user account

Fund the account (Payin)

Payin methods

Simulate Bank Payin and Crypto Payin

Check payin details

Webhooks

Move money — Transfer or Payout

Transfers

Create a transfer

Webhooks

Payouts

Webhooks

Orders

Order States

Ledger

Difference between Orders and Ledger