> ## 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 API quickstart

> Create your first request-money ask and look up public status on RaaS Widgets

## Prerequisites

* Sandbox API key from the [Partner Portal](https://raas-widgets-partner-portal-sandbox.up.railway.app/) (`raas_sandbox_*`)
* Request-money feature enabled on your partner (`allowedApis` includes `request-money`, or unset for all features)
* Optional: `landingBaseUrl` / WhatsApp settings so `landingLink` and `waLink` are populated

## Create a request

<Steps>
  <Step title="Set base URL and key">
    ```bash theme={null}
    export BASE_URL="https://raas-widgets-backend-sandbox.up.railway.app"
    export API_KEY="raas_sandbox_your_api_key_here"
    ```
  </Step>

  <Step title="POST /v1/request-money">
    Supply a stable **8-character** alphanumeric `referenceId` (`a-z`, `A-Z`, `0-9`) from your systems.

    ```bash theme={null}
    curl -sS -X POST "$BASE_URL/v1/request-money" \
      -H "Content-Type: application/json" \
      -H "X-API-Key: $API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "referenceId": "TstBnK01",
        "expiresInMinutes": 120,
        "amount": 150.5,
        "currency": "GTQ",
        "requestData": {
          "userReferenceId": "user-8842",
          "name": { "firstName": "Maria", "lastName": "Lopez" },
          "address": {
            "country": "GT",
            "stateCode": "GT-01",
            "city": "Guatemala City",
            "line1": "12 Av. Reforma"
          },
          "dob": "1990-05-15",
          "payoutMethod": {
            "type": "bank_account",
            "bankAccount": {
              "country": "GT",
              "accountNumber": "0123456789012",
              "accountType": "checking",
              "bankCode": "BIND",
              "bankName": "BANCO INDUSTRIAL"
            }
          }
        }
      }'
    ```

    Minimum requester identity: **name** + **address.country**. Include `dob` when you have it.
  </Step>

  <Step title="Use the returned links">
    A successful create returns your `referenceId`, public `status` (typically `pending`), and payer URLs:

    | Field             | Use                                                    |
    | ----------------- | ------------------------------------------------------ |
    | `fundRequestLink` | Widget URL for the sender (always present on success)  |
    | `landingLink`     | Your configured landing page with `?ref={referenceId}` |
    | `waLink`          | WhatsApp deep link when WhatsApp is configured         |

    Share the URL that matches your payer experience. Persist `requestId` from the webhook (or correlate via `referenceId` on GET) for later settlement events.
  </Step>

  <Step title="Look up status">
    ```bash theme={null}
    curl -sS "$BASE_URL/v1/request-money/TstBnK01" \
      -H "X-API-Key: $API_KEY"
    ```

    Public statuses: `pending`, `processing`, `completed`, `rejected`, `cancelled`.
  </Step>
</Steps>

## Try it in the Partner Portal

Authenticated partners can exercise create, route validate, and lookup from **Developer → Request money** without pasting an API key in the browser. That playground proxies the same `/v1/request-money` contract.

## Next steps

<CardGroup cols={2}>
  <Card title="Create and lookup" icon="code" href="/raas-widgets/request-api/endpoints">
    Full field notes, status mapping, errors.
  </Card>

  <Card title="Webhooks" icon="bell" href="/raas-widgets/request-api/webhooks">
    Wire `request_money.*` and `operation.*`.
  </Card>

  <Card title="Lifecycle" icon="diagram-project" href="/raas-widgets/request-api/lifecycle">
    How the payer link becomes an operation.
  </Card>

  <Card title="Partner Portal" icon="grid-2" href="https://raas-widgets-partner-portal-sandbox.up.railway.app/">
    Keys, webhooks, and playground.
  </Card>
</CardGroup>