> ## Documentation Index
> Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome

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.

<Columns cols={2}>
  <Column>
    <Card title="Sandbox Portal" icon="circle-info">
      Manage API keys, simulate KYC approvals, and monitor operations\
      [https://portal.sandbox.raliopay.com](https://www.portal.sandbox.raliopay.com)
    </Card>
  </Column>

  <Column>
    <Card title="Sandbox API" icon="laptop">
      [https://sandbox-revo-api.raliopay.com](https://sandbox-revo-api.raliopay.com)
    </Card>
  </Column>
</Columns>

***

## Integration flow

<Steps>
  <Step title="Setup — API Keys & Webhooks">
    Every Ralio integration follows the same sequence. Each step depends on the previous one.
  </Step>

  <Step title="Create a user">
    Generate your API credentials and configure your webhook endpoint from the Portal.
  </Step>

  <Step title="Verify the user (KYC / KYB)">
    Launch an identity verification session. In sandbox you approve it manually.
  </Step>

  <Step title="Create an account (Wallet)">
    Once the user is verified, create one or more accounts in any supported currency.
  </Step>

  <Step title="Fund the account (Payin)">
    Add funds via bank transfer, crypto deposit, or card. Simulate instantly in sandbox.
  </Step>

  <Step title="Move money — Transfer or Payout">
    Send funds internally between accounts (Transfer) or externally (Payout).
  </Step>

  <Step title="Track Orders & Ledger">
    Every operation creates an Order. Completed orders appear as entries in the Ledger.
  </Step>
</Steps>

***

# 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.

<Steps>
  <Step title="Open the Sandbox Portal">
    Go to [portal.sandbox.raliopay.com/settings/api-keys](https://portal.sandbox.raliopay.com/settings/api-keys)
  </Step>

  <Step title="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>
</Steps>

***

## Step 2 — Authenticate (get a Bearer Token)

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

```json theme={null}
POST /api/v1/auth/login
```

```json theme={null}
{
  "api_code": "your-api-code",
  "api_key":  "your-api-key"
}
```

**Response `200`:**

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}
```

Include this token in every subsequent request:

```json theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

***

## Step 3 — Configure Webhooks

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

<Steps>
  <Step title="Register your endpoint">
    Go to [portal.sandbox.raliopay.com/account/webhooks](https://portal.sandbox.raliopay.com/account/webhooks)

    * Must be a valid `https://` URL
    * Must accept `POST` requests
    * Must respond with `2xx` within 60 seconds
  </Step>

  <Step title="Select events">
    Subscribe only to the events you need.
  </Step>

  <Step title="Save your Webhook Secret">
    Ralio signs every delivery with HMAC-SHA256. Store this secret to verify requests.
  </Step>
</Steps>

### Available events

| **Category**  | **Events**                                                                                  |
| :------------ | :------------------------------------------------------------------------------------------ |
| **Accounts**  | `account.activated`                                                                         |
| **Payins**    | `payin.processing` · `payin.completed` · `payin.failed`                                     |
| **Payouts**   | `payout.processing` · `payout.completed`                                                    |
| **Transfers** | `transfer.processing` · `transfer.completed`                                                |
| **KYC / KYB** | `kyc.state_updated` · `kyc.session_verified` · `kyc.session_failed` · `kyc.session_expired` |

***

# Create a user

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

## User types

<Columns cols={2}>
  <Column>
    <Card title="Individual User" icon="person">
      A natural person. Goes through **KYC** (Know Your Customer) verification.\
      \
      `POST /api/v1/account/individual-users`
    </Card>
  </Column>

  <Column>
    <Card title="Business User" icon="building">
      A legal entity / company. Goes through **KYB** (Know Your Business) verification.\
      \
      `POST /api/v1/account/business-users`
    </Card>
  </Column>
</Columns>

<Tip>
  Save the `id` returned in the response — you'll need it for every subsequent operation (KYC sessions, account creation, transfers, etc.).
</Tip>

***

# Verify the user (KYC / KYB)

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

### How it works

<Steps>
  <Step title="Create an IDV session">
    Your backend creates a session for the user and receives a `hostedUrl`.
  </Step>

  <Step title="User completes verification">
    In production, the user follows the URL to submit documents.\
    **In sandbox: skip this — approve directly from the Portal.**
  </Step>

  <Step title="Receive webhook notification">
    Ralio notifies your endpoint when the session state changes.
  </Step>

  <Step title="User is verified">
    Once approved, the user can have accounts and operate.
  </Step>
</Steps>

***

# Create an account (Wallet)

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

<Warning>
  A user must be **verified** (KYC or KYB `REGULAR`) before you can create accounts for them.
</Warning>

## Create a user account

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

```json theme={null}
{
  "currency": "EUR",
  "label":    "Main Account"
}
```

**Response `201`:**

```json theme={null}
{
  "id":       "acc-uuid-1234",
  "currency": "EUR",
  "balance":  0,
  "state":    "ACTIVE",
  "label":    "Main Account",
  "userId":   "user-uuid-5678"
}
```

<Tip>
  Save the `id` (Account ID). You'll need it for funding, transfers, payouts, and querying orders.
</Tip>

***

# Fund the account (Payin)

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

## Payin methods

<Columns cols={3}>
  <Column>
    <Card title="Bank Payin" icon="building-columns">
      User sends a bank transfer to an assigned IBAN. Ralio credits the account once the transfer settles.
    </Card>
  </Column>

  <Column>
    <Card title="Crypto Payin" icon="coins">
      User sends stablecoins to a generated wallet address. Auto-converted to account currency.
    </Card>
  </Column>

  <Column>
    <Card title="Card Payin" icon="credit-card">
      Payment via credit or debit card through an integrated payment gateway.
    </Card>
  </Column>
</Columns>

***

## Simulate Bank Payin and Crypto Payin

<Steps>
  <Step title="Open the Sandbox Portal">
    Go to [portal.sandbox.raliopay.com](http://portal.sandbox.raliopay.com)
  </Step>

  <Step title="Open the Funds Simulator">
    In the sidebar Developers > Funds Simulator
  </Step>

  <Step title="Select the account">
    Find it by account ID.
  </Step>

  <Step title="Simulate Funding">
    Enter the amount and currency, select the funding type and click **Simulate Funding**
  </Step>
</Steps>

## Check payin details

<CodeGroup>
  ```json Bank Payin theme={null}
  GET /api/v1/account/bank-payins/{oid}
  ```

  ```text Crypto Payin theme={null}
  GET /api/v1/account/crypto-payins/{oid}
  ```
</CodeGroup>

## 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).

<Columns cols={2}>
  <Column>
    <Card title="Transfer" icon="arrow-right-arrow-left">
      **Internal.** Between two accounts inside Ralio. Instant, no external intermediaries.
    </Card>
  </Column>

  <Column>
    <Card title="Payout" icon="arrow-up">
      **External.** To a bank account (IBAN) or crypto wallet address.
    </Card>
  </Column>
</Columns>

## Transfers

### Create a transfer

```json theme={null}
POST /api/v1/account/users/{uid}/accounts/{aid}/transfers
```

### Webhooks

| **Event**             | **When**             |
| :-------------------- | :------------------- |
| `transfer.processing` | Being processed      |
| `transfer.completed`  | Settled successfully |

## Payouts

Bank PayoutCrypto Payout

```text theme={null}
POST /api/v1/account/users/{uid}/accounts/{aid}/bank-payouts

{
  "origin":    { "currency": "EUR", "amount": 250 },
  "recipient": {
    "iban":          "ES9121000418450200051332",
    "accountHolder": "Jane Doe",
    "bankName":      "Banco Santander"
  },
  "reference": "Invoice #1042",
  "code2fa":   "123456"
}
```

### **Webhooks**

| **Event**           | **When**             |
| :------------------ | :------------------- |
| `payout.processing` | Submitted to network |
| `payout.completed`  | Funds delivered      |

***

# 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**                        |
| :----------- | :--------------------------------- |
| `PENDING`    | Awaiting processing                |
| `PROCESSING` | Being processed                    |
| `COMPLETED`  | Settled  → entry created in Ledger |
| `FAILED`     | Operation failed                   |
| `CANCELLED`  | Cancelled before completion        |

```json theme={null}
GET /api/v1/account/orders
GET /api/v1/account/users/{uid}/accounts/{aid}/orders
GET /api/v1/account/orders/{order-id}
```

***

# 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 COMPLETED status generates an entry in the Ledger

## Difference between Orders and Ledger

|                 | Orders                                            | Ledger                       |
| --------------- | ------------------------------------------------- | ---------------------------- |
| What it records | All operation attempts                            | Only completed operations    |
| Statuses        | PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED | Only successful transactions |
| Main use        | Real-time status tracking                         | Auditing and accounting      |

```json theme={null}
GET /api/v1/account/users/{uid}/accounts/{aid}/transactions
GET /api/v1/account/transactions/{transaction-id}
```