# API reference

This page indexes every customer-facing server endpoint that authenticates with your organization `accesskey`. Dashboard-session and Relay-operator endpoints are intentionally excluded.

Base URL: `https://bridge.relayfinance.io`

## Payments

| Method | Path | Success | Purpose |
| --- | --- | ---: | --- |
| `POST` | `/payment/create-crypto-Payment-Intent` | `201` | Create a one-off crypto collection intent and temporary deposit wallet. |
| `POST` | `/payment/create-fiat-payment-intent` | `201` | Create an NGN virtual-account collection intent. |
| `GET` | `/payment/get-payment-intent/{txId}` | `200` | Retrieve a tenant-scoped crypto or fiat intent. |
| `GET` | `/payment/get-active-payment-intents-currency` | `200` | List assets currently active for payment intents. |
| `GET` | `/payment/fiat-rate?currency=ngn` | `200` | Get the current buffered NGN-per-USD rate. |

Detailed inputs and responses:

- [Crypto payment intents](/docs/payments/crypto-payment-intents)
- [Fiat payment intents](/docs/payments/fiat-payment-intents)
- [Payment object](/docs/reference/payment-object)

## Customer deposit wallets

| Method | Path | Success | Purpose |
| --- | --- | ---: | --- |
| `POST` | `/customer-wallets` | `201` | Get or create a reusable wallet/token enrollment and renew its watch. |
| `GET` | `/customer-wallets/{id}` | `200` | Retrieve a wallet and its enrolled assets. |
| `GET` | `/customer-wallets/{id}/deposits` | `200` | List confirmed or review-required incoming deposits. |
| `GET` | `/customer-wallets/{id}/transfers` | `200` | List merchant payouts and fee sweeps. |

History query fields are `limit` (default 20, maximum 100) and `offset` (default 0). See [customer wallets](/docs/wallets/customer-wallets).

## External wallet monitoring

| Method | Path | Success | Purpose |
| --- | --- | ---: | --- |
| `GET` | `/wallet/organization/external-wallet` | `200` | Find a registered external wallet by `address` and `network`. |
| `POST` | `/wallet/organization` | `200` | Register an existing address and optional event subscriptions. |
| `PUT` | `/wallet/organization/{walletId}/events` | `200` | Replace the wallet's complete event subscription set. |

See [external wallets](/docs/wallets/external-wallets) for the nested event subscription fields.

## Authentication

All endpoints on this page require:

```http
accesskey: YOUR_ORGANIZATION_API_KEY
```

The key selects the organization. Do not send an organization ID in an attempt to change tenant scope. See [authentication](/docs/getting-started/authentication).

## Success envelope

```json
{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "d01048f7-3874-4df5-8642-6ab07a66ea77"
  }
}
```

`data` can be an object, array, primitive value, or `null`, depending on the endpoint.

Paginated responses move the service's item list into `data` and add:

```json
{
  "meta": {
    "requestId": "d01048f7-3874-4df5-8642-6ab07a66ea77",
    "pagination": {
      "total": 47,
      "limit": 20,
      "offset": 20,
      "hasMore": true
    }
  }
}
```

## Error envelope

```json
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Asset is unavailable"
  },
  "meta": {
    "requestId": "c23db470-9ac0-492b-8be9-26cfe667b577"
  }
}
```

Validation errors can also include `error.details`, an array of `{ field, code }` objects. See [errors and retries](/docs/getting-started/errors).

## Compatibility rules

- Treat undocumented response fields as non-contractual and ignore them safely.
- Do not depend on object key order.
- Preserve decimal strings as strings or arbitrary-precision decimals.
- Accept new enum values without crashing; log and reconcile unknown states.
- Use `schemaVersion` for webhook payload evolution.
- Use the active-assets endpoint for availability rather than assuming every enum is enabled.

## Dashboard-only controls

Human administration uses the Relay dashboard's bearer-token session and permissions. This includes:

- settlement destination management;
- webhook endpoint creation, editing, secret rotation, delivery inspection, and replay;
- team membership and role controls;
- payment lists, analytics, and receipt download; and
- organization finance views.

These controls are not authenticated with `accesskey` and are not part of the embedded-customer server API above.