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

# Request Money API overview

> Create request-money operations, read public status by referenceId, and integrate using the JSON contract and interactive API reference.

You use this API when your product needs to **start a request-money flow** and **surface status** to end users or internal systems. The public surface is versioned under **`/v1`** and speaks **JSON** over HTTPS.

## What this API offers today

* **`POST /v1/request-money`** — You send a `RequestMoneyRequest` body (applicant, payout method, amount, currency, and your **`referenceId`**). The `referenceId` must be exactly **8** characters from **`a-z`**, **`A-Z`**, and **`0-9`**. The API returns **`201 Created`** with a `RequestMoneyResponse`: your `referenceId`, an operation `id`, a `status`, **`waLink`** (WhatsApp payer journey), **`landingLink`** (web landing), and related fields as in OpenAPI. Screening may respond with **`403 Forbidden`** (for example OFAC hit) without the standard create success body.
* **`GET /v1/request-money/{referenceId}`** — You read the **public status** for the same integrator `referenceId`. A missing or unknown resource returns **`404`** with JSON **`error`** and **`message`** fields as in OpenAPI.

The authoritative field list, formats (for example **ISO 3166-1 alpha-2** for `country`), and `status` enum live in the **API Reference** tab (OpenAPI-backed).

## Typical integration flow

```mermaid theme={null}
sequenceDiagram
  participant You as Your backend
  participant API as Request API
  participant Payer as Payer journey
  You->>API: POST /v1/request-money (X-API-Key)
  API-->>You: 201 + id, status, waLink, landingLink
  You->>Payer: Redirect or embed payer URL
  You->>API: GET /v1/request-money/{referenceId}
  API-->>You: 200 public status
```

<Steps>
  <Step title="Choose your base URL">
    Use the base URL for your environment (sandbox vs production). For sandbox, the versioned API root is **`https://{raas-backend-sandbox}/v1`** (host base URL without the path: `https://{raas-backend-sandbox}`). Your integration contact provides the concrete host for each environment.
  </Step>

  <Step title="Send your API key">
    On every **`POST`** and **`GET`** under **`/v1/request-money`**, include header **`X-API-Key`** with the key your integration contact gives you for that environment. Missing or wrong keys receive **`401 Unauthorized`**. In the **API Reference** playground, use **Authorize** (or your client’s equivalent) so requests include the key.
  </Step>

  <Step title="Configure landing and messaging">
    Before **`POST /v1/request-money`** succeeds, your operator stores **`landingBaseUrl`** (HTTPS base for the payer funding page), **`whatsappBaseUrl`**, and **`whatsappMessageTemplate`** on your partner record through the partner portal or Leap admin. The API builds **`landingLink`** from **`landingBaseUrl`** by appending a **`ref`** query parameter for your **`referenceId`**. Omitting **`landingBaseUrl`** yields **`422`** until you configure it.
  </Step>

  <Step title="Create the operation">
    Call **`POST /v1/request-money`** with a payload that matches **`RequestMoneyRequest`**. Supply a stable **`referenceId`** (8 alphanumeric characters: `a-z`, `A-Z`, `0-9`) from your own systems so you can correlate webhooks, support tickets, and later `GET` calls.
  </Step>

  <Step title="Use the returned links">
    Read **`waLink`** and **`landingLink`** from **`RequestMoneyResponse`**. Use the URL that matches your payer experience (WhatsApp vs browser). Treat **`status`** as the public lifecycle field (`pending`, `processing`, `completed`, `rejected`, `cancelled` as defined in the schema).
  </Step>

  <Step title="Poll or branch on status (optional)">
    Call **`GET /v1/request-money/{referenceId}`** when you need the latest **public** snapshot for that `referenceId`. Design your UX so you do not rely on aggressive polling unless your integration guide says otherwise.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="API keys and environments">
    You receive separate credentials per environment. Never use production keys in development builds, CI logs, or example code you ship to partners.
  </Accordion>

  <Accordion title="referenceId ownership">
    `referenceId` is **your** stable operation code: exactly **8** characters from **`a-z`**, **`A-Z`**, and **`0-9`**. The API uses it to correlate `GET` responses with the original `POST` for your integrator account.
  </Accordion>

  <Accordion title="Tooling routes">
    **`GET /api-docs`**, **`GET /openapi.json`**, and other non-versioned tooling routes may sit outside `api_key` security unless your deployment adds another layer in front of the process.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/request-api/quickstart">
    Make your first authenticated calls in a few minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/request-api/authentication">
    How `X-API-Key` works, errors (including **403** screening), and operational tips.
  </Card>

  <Card title="Partner portal playground" icon="flask" href="/request-api/guides/partner-portal-playground">
    Run guided **create**, **GET**, and optional **internal status** tests from the partner portal (API key for create and lookup; server secret for internal status).
  </Card>

  <Card title="API reference intro" icon="book-open" href="/request-api/api-reference/introduction">
    Base URLs, headers, status codes, and response shape.
  </Card>

  <Card title="Webhooks" icon="bell" href="/request-api/webhooks/overview">
    Receive signed callbacks for **operation\_created**, **operation\_updated**, and **operation\_error** with HMAC-SHA256 verification and built-in retries.
  </Card>

  <Card title="OpenAPI playground" icon="code" href="/api-reference/request-money/create-a-request-money-operation">
    Interactive **POST /v1/request-money** with schemas and examples.
  </Card>

  <Card title="GET status endpoint" icon="magnifying-glass" href={`/api-reference/request-money/get-the-public-status-of-a-request-by-\u0060referenceid\u0060`}>
    Open **GET** `/v1/request-money/{referenceId}` for the public status payload and **404** behavior.
  </Card>
</CardGroup>

## Environments

| Environment | Host base URL                       | Versioned API root                     |
| ----------- | ----------------------------------- | -------------------------------------- |
| Sandbox     | `https://{raas-backend-sandbox}`    | `https://{raas-backend-sandbox}/v1`    |
| Production  | `https://{raas-backend-production}` | `https://{raas-backend-production}/v1` |

In code samples, set **`BASE_URL`** to the **host base URL** (no trailing slash, no `/v1`). Append **`/v1/request-money`** (or other versioned paths) in your client, as in the Quickstart examples. Your integration contact provides the concrete hosts.

The OpenAPI **`servers`** entry and API Reference playground use the sandbox placeholder. Your deployment may set **`OPENAPI_SERVER_URL`** when exporting OpenAPI from the API repo so `servers` reflects a concrete environment.

<Warning>
  Do not use **production** API keys in development, shared sandboxes, or public repositories. Rotate keys if they are exposed.
</Warning>