# Payments - X-Radius API

> Base URL: https://x-radius.com/api/v1
> Auth: Authorization: Bearer xrt_...  (a manager API token)
> Envelope: {"data": ...}; lists add {"meta":{page,page_size,total,has_next}}
> Errors: {"error":{"code","message","request_id"}} - branch on code, never on message
> Timestamps: yyyy-MM-dd HH:mm:ss, UTC
> Money: a bare JSON number in major units, with an ISO-4217 currency code beside it
> Idempotency: redeem and activate endpoints take a client-supplied request_id (UUID)
>
> This page: https://x-radius.com/docs/api/payments
> Every group: https://x-radius.com/llms.txt

14 endpoints in 1 resource groups. 7 carry a hand-written reference entry with examples; the remaining 7 are generated from the running router and carry method, path, authentication, permission and rate-limit bucket, but no request or response example.

### List configured gateways

`GET /api/v1/admin/payments/config`

Just the tenant's configured rows, with credentials masked, for a page that already holds the catalogue.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger


### Configure a gateway

`POST /api/v1/admin/payments/config`

Upserts one gateway's credentials and settings. Every field is keep-existing, so a partial payload leaves unsent credentials alone rather than clearing them.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | body | string | yes | Driver id from the catalogue. |

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_VALIDATION` | 400 | an unknown gateway id, or a field the driver does not accept |


### Remove a gateway configuration

`DELETE /api/v1/admin/payments/config/{gateway}`

Deletes the tenant's credentials for one driver. Transactions already recorded against it are untouched.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Update one gateway's configuration

`PATCH /api/v1/admin/payments/config/{gateway}`

The same upsert as the POST, with the gateway named in the path. The PATH wins over any gateway field in the body, so a stale client cannot retarget an edit at a different gateway.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Test a gateway configuration

`POST /api/v1/admin/payments/config/{gateway}/test`

Checks the stored credentials against the provider.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger
- Rate limit bucket: `t_mutate`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |


### Read a gateway's callback URL

`GET /api/v1/admin/payments/config/{gateway}/webhook-url`

The exact URL to register with the provider, including the per-tenant secret path segment. Copy it verbatim.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gateway` | path | string | yes | Driver id. |

#### Note

The URL contains a secret. It is what proves an inbound callback came from the provider you configured, so treat the response as a credential and do not paste it into a ticket.


### Top up own wallet online

`POST /api/v1/admin/payments/deposit`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_self_deposit` (Top up own wallet online)
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Top up own wallet online

`GET /api/v1/admin/payments/deposit/gateways`

- Authentication: manager session (JWT) or API token
- Permission: `prm_managers_self_deposit` (Top up own wallet online)
- Risk: danger

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### List the gateway catalogue and what is configured

`GET /api/v1/admin/payments/gateways`

The drivers this build supports, the tenant's own configured rows with secrets masked, and the public base URL a gateway should call back to.

- Authentication: manager session (JWT) or API token
- Permission: `prm_settings` (Manage settings)
- Risk: danger

#### Response — 200 OK

```json
{
  "data": {
    "catalog": [
      {
        "id": "paymob",
        "label": "Paymob",
        "methods": [],
        "fields": [],
        "ttl_seconds": 900,
        "min_amount": 0,
        "implemented": true,
        "pollable": true
      }
    ],
    "configured": [],
    "public_base_url": "https://acme.example.com"
  }
}
```

#### Note

Read implemented and pollable before building against a driver. implemented false is a registry stub whose vendor contract is not verified; pollable false means the gateway has no merchant-readable status API, so its callback is the only channel and a lost callback is a lost payment. min_amount is the PSP's own floor in major units, and 0 means no floor.


### GET /api/v1/admin/payments/transactions/{id}

`GET /api/v1/admin/payments/transactions/{id}`

- Authentication: manager session (JWT) or API token
- Permission: any one of `prm_report_gateway_transactions`, `prm_report_gateway_transactions_all`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Re-check and write off gateway transactions

`POST /api/v1/admin/payments/transactions/{id}/recheck`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_manage` (Re-check and write off gateway transactions)
- Risk: write
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Mark gateway payments paid / refunded (moves money)

`POST /api/v1/admin/payments/transactions/{id}/refund`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_settle` (Mark gateway payments paid / refunded (moves money))
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Mark gateway payments paid / refunded (moves money)

`POST /api/v1/admin/payments/transactions/{id}/settle`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_settle` (Mark gateway payments paid / refunded (moves money))
- Risk: danger
- Rate limit bucket: `pay_init`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._


### Re-check and write off gateway transactions

`POST /api/v1/admin/payments/transactions/{id}/status`

- Authentication: manager session (JWT) or API token
- Permission: `prm_payments_manage` (Re-check and write off gateway transactions)
- Risk: write
- Rate limit bucket: `t_mutate`

_This endpoint has no hand-written reference entry yet. The method, path, authentication, permission and rate limit above are generated from the running router and are accurate; there is no request or response example._