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

# Create and lookup

> POST and GET /v1/request-money — payloads, public status, idempotency, and errors

## Endpoints

| Method | Path                              | Description                                                     |
| ------ | --------------------------------- | --------------------------------------------------------------- |
| `POST` | `/v1/request-money`               | Create a request-money ask and mint the payer fund-request link |
| `GET`  | `/v1/request-money/{referenceId}` | Public status for your 8-char `referenceId`                     |

Auth: `X-API-Key` (`raas_sandbox_*` / `raas_live_*`). Feature: `request-money`.

Base URL: `https://raas-widgets-backend-sandbox.up.railway.app` (sandbox).

## Create — `POST /v1/request-money`

### Body (conceptual)

| Field                         | Required | Notes                                                                |
| ----------------------------- | -------- | -------------------------------------------------------------------- |
| `referenceId`                 | Yes      | Exactly **8** chars: `a-z`, `A-Z`, `0-9`. Your stable operation code |
| `amount`                      | Yes      | Numeric amount                                                       |
| `currency`                    | Yes      | ISO 4217 (destination / receive currency for the ask)                |
| `expiresInMinutes`            | No       | Link TTL                                                             |
| `requestData.userReferenceId` | Yes      | Your id for the **requester**                                        |
| `requestData.name`            | Yes      | Requester name                                                       |
| `requestData.address.country` | Yes      | Destination country (ISO 3166-1 alpha-2)                             |
| `requestData.dob`             | No       | Recommended when available (`YYYY-MM-DD`)                            |
| `requestData.payoutMethod`    | Yes      | `bank_account`, `card`, or `cash`                                    |

Exact nested shapes are in OpenAPI (`CreateRequestMoneyDto`). For cash, send `cash.provider` as before — the platform maps it to the fund-request payer field.

### Success response (additive)

Fields you already use remain. RaaS Widgets also returns:

| Field             | Meaning                                              |
| ----------------- | ---------------------------------------------------- |
| `fundRequestLink` | Payer widget URL                                     |
| `resolved`        | Effective corridor/payout the backend inferred       |
| `warnings`        | Non-blocking offerability hints (omitted when empty) |

```json theme={null}
{
  "referenceId": "Ab3xY9mK",
  "id": "Ab3xY9mK",
  "status": "pending",
  "statusDetails": "The operation is pending because the sender has not yet started the process.",
  "waLink": "https://wa.me/…",
  "landingLink": "https://app.example.com/pay?ref=Ab3xY9mK",
  "fundRequestLink": "https://<fund-request-host>/link_…",
  "resolved": {
    "sourceCountry": "US",
    "destinationCountry": "GT",
    "sourceCurrency": "USD",
    "destinationCurrency": "GTQ",
    "payoutType": "bank_account",
    "payerCode": null,
    "stateCode": "GT-01"
  }
}
```

### Idempotency

| Header            | Behaviour                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | Optional. Opaque string (UUID recommended). Safe retry of the same body returns the original create instead of `409` |

Without a matching key, a duplicate partner + `referenceId` returns **`409` `LEGACY_REFERENCE_EXISTS`**.

### Offerability warnings

`warnings[]` entries such as `ROUTE_NOT_OFFERABLE` do **not** fail create. They mean the route can commit but may not appear in the payer widget at that amount. Try another amount/payer or contact your account manager.

## Lookup — `GET /v1/request-money/{referenceId}`

Returns the public snapshot for your integrator `referenceId`, or **404** when unknown.

### Public status values

| Status       | Meaning                                               |
| ------------ | ----------------------------------------------------- |
| `pending`    | Ask created; sender has not completed payment         |
| `processing` | Sender created the fulfilling operation (in progress) |
| `completed`  | Transfer settled / ask funded                         |
| `rejected`   | Fulfilling operation failed                           |
| `cancelled`  | Cancelled or expired                                  |

How these map from the internal money request / operation: see [Lifecycle](/raas-widgets/request-api/lifecycle). After an operation exists, prefer [operation webhooks](/raas-widgets/request-api/webhooks) for real-time updates.

## Common error codes

Branch on stable `error.code` (or OFAC body `code`), never on `message`.

| Code                        | HTTP | Meaning                                                  |
| --------------------------- | ---- | -------------------------------------------------------- |
| `CORRIDOR_UNRESOLVABLE`     | 422  | Could not derive source/destination corridor             |
| `ROUTE_NOT_AVAILABLE`       | 422  | No provider for the route                                |
| `STATE_NOT_MAPPED`          | 422  | Payout state not mapped for the provider                 |
| `PAYOUT_METHOD_UNSUPPORTED` | 422  | Payout type not supported on this route                  |
| `LEGACY_REFERENCE_EXISTS`   | 409  | Duplicate `referenceId` without matching idempotency key |
| `OFAC_HIT`                  | 403  | Watch-list / OFAC rejection                              |
| `API_FEATURE_NOT_ENABLED`   | 403  | Partner lacks `request-money`                            |
| `IDENTITY_VALIDATOR_*`      | 503  | Identity screening unavailable                           |

Failed creates may also emit `request_money.failed` — see [Webhooks](/raas-widgets/request-api/webhooks).

## Partner configuration

Optional partner settings power derived links:

* **`landingBaseUrl`** — `landingLink` = base + `?ref={referenceId}`
* **`whatsappBaseUrl`** + message template — builds `waLink`

Configure via Partner Portal / Leap admin. Missing WhatsApp config yields an empty `waLink` string.

## Next steps

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="diagram-project" href="/raas-widgets/request-api/lifecycle">
    Fund-request link → operation → settlement.
  </Card>

  <Card title="Webhooks" icon="bell" href="/raas-widgets/request-api/webhooks">
    Events from create through settlement.
  </Card>
</CardGroup>