# Direct API overview
Source: https://paylinky.vercel.app/docs/direct-api

Build your own checkout with the Direct API.

# Direct API

The Direct API keeps your UI, forms and business logic while Paylinky and its payment partners handle the payment rails.

## Endpoints

| Method | Endpoint | Purpose |
| - | - | - |
| `GET` | `/api/v1/countries` | Active countries, currencies and Mobile Money operators |
| `GET` | `/api/v1/crypto/assets` | Active crypto assets and networks |
| `GET` | `/api/v1/fees` | Platform fee configuration |
| `POST` | `/api/v1/collect` | Create a Mobile Money collection |
| `POST` | `/api/v1/crypto/collect` | Create a crypto payment (address + network) |
| `GET` | `/api/v1/transaction/{id}` | Status of one transaction |
| `GET` | `/api/v1/transactions` | List transactions (`?limit=20&status=success`) |
| `POST` | `/api/v1/payment-links` | Hosted page link (see [Hosted Page API](/docs/hosted-page)) |
| `GET` | `/api/v1/payment-links/{id}` | Link status |
| `GET` | `/api/v1/balance` | Wallet balances (live) |
| `POST` | `/api/v1/sandbox/simulate` | Sandbox only: finish a pending test payment |

## Integration principles

1. Load `/countries` (and `/crypto/assets`) at startup or periodically; never hard-code operators.
2. Generate a **unique `reference`** per order on your server.
3. Store the returned `transaction_id`.
4. Wait for the **webhook**, or poll `GET /transaction/{id}`.
5. Never credit an order from a browser callback.
6. Handle all flows: `pending` (USSD push), `wave_url` (redirect), `otp_required` (OTP).

## Admin-controlled availability

Administrators can switch off whole payment methods, individual countries, operators or crypto assets at any time. A disabled item disappears from `/countries` and `/crypto/assets`, and `/collect` returns `country_not_supported`, `operator_not_supported`, `asset_not_supported` or `method_disabled`.

## Fees

Every transaction returns the exact `fee_amount` and `credited_amount`:

```text
credited_amount = amount − fee_amount
fee_amount      = provider fee + Paylinky platform fee
```

Display the values returned by the API rather than calculating them yourself.