# API reference
Source: https://paylinky.vercel.app/docs/reference

Every endpoint with request and response examples.

# API reference

Base URL: `https://paylinky.vercel.app/api/v1` · Auth: `Authorization: Bearer <key>` · Machine-readable spec: [`/openapi.json`](https://paylinky.vercel.app/openapi.json)

## GET /countries

Active countries, currencies and operators (after administrator filtering).

```json
[
  { "code": "CI", "name": "Côte d'Ivoire", "currency": "XOF",
    "operators": ["Orange Money", "MTN Mobile Money", "Moov Money", "Wave"],
    "unavailable_operators": [] }
]
```

## GET /crypto/assets

```json
[ { "asset_code": "USDT.TRC20", "name": "Tether (TRON)", "network": "TRC20", "symbol": "USDT" } ]
```

## GET /fees

```json
{
  "platform_fee_percent": 1,
  "withdrawal_fee_percent": 1,
  "minimum_amount": 100,
  "maximum_amount": 5000000,
  "sandbox_fee_percent": 5,
  "provider_fees": null,
  "note": "Final fees are always returned on each transaction (fee_amount, credited_amount)."
}
```

## POST /collect

See [Mobile Money](/docs/mobile-money) and [Payment flows](/docs/payment-flows).

## POST /crypto/collect

See [Crypto payments](/docs/crypto).

## GET /transaction/{id}

`id` can be `transaction_id`, `reference` or `merchant_reference`.

```json
{
  "transaction_id": "0b9c…", "reference": "PLK-7XK2M9QPLA", "merchant_reference": "order_cm_12345",
  "status": "success", "payment_method": "mobile_money",
  "amount": 5000, "fee_amount": 300, "credited_amount": 4700, "currency": "XAF",
  "country_code": "CM", "operator": "MTN Mobile Money", "phone": "+2376XXXXXXXX",
  "sandbox": false, "created_at": "2026-01-01T10:00:00.000Z", "expires_at": null
}
```

| `status` | Meaning |
| - | - |
| `pending` | Waiting for the customer / provider |
| `success` | Confirmed, wallet credited (live) |
| `failed` | Declined or failed |
| `cancelled` | Cancelled by the customer |
| `expired` | Crypto address expired |
| `refunded` | Refunded by an administrator |

## GET /transactions

Query: `limit` (max 100, default 20), `status`. Returns `{ "data": [ … ], "count": 20 }` for the environment of your key.

## POST /payment-links · GET /payment-links/{id}

See [Hosted Page API](/docs/hosted-page).

## GET /balance

```json
{ "balances": [ { "currency": "XAF", "available": 124500 }, { "currency": "USDT", "available": 24.5 } ], "sandbox": false }
```

## POST /sandbox/simulate

Sandbox keys only. Finishes a pending sandbox payment and dispatches the webhook.

```json
{ "transaction_id": "0b9c…", "status": "success" }
```

`status` ∈ `success`, `failed`, `cancelled`.