# Payer API

One payments platform for the Maldives, over REST and GraphQL. Take payments, read your own money, let other apps act on your behalf, and get notified when things happen.

The Payer API lets you move and read money in the Maldives from your own code. It is organised into a few focused surfaces — pick the one that matches what you're building.

| API | Use it to | Auth |
| --- | --- | --- |
| [Checkout](/developers/docs/checkout) | Take a one-off payment on a hosted page | Secret or publishable key |
| [Webhooks](/developers/docs/webhooks) | Get notified when a payment settles | Signed with a `whsec_` secret |
| [Personal access tokens](/developers/docs/personal-tokens) | Read *your own* balance and transactions | `pat_` token |
| [OAuth2 apps](/developers/docs/oauth) | Let another app act for a Payer user | `oat_` access token |

Every surface shares one credential model, one scope catalogue, and one audit trail. Learn it once in [Authentication](/developers/docs/authentication) and it carries across all of them.

## Base URL

There is a single base URL for every request:

```bash title="Base URL"
https://api.payer.app
```

You don't switch hosts to reach the sandbox. The key you send decides the environment — a `_test_` key runs against the sandbox, a `_live_` key against production. See [Authentication → Environments](/developers/docs/authentication#environments).

## Money and amounts

All amounts are in **Maldivian rufiyaa (MVR)**. The REST APIs work in **laari**, the smallest unit, where **100 laari = 1 MVR**. So MVR 24.90 is `2490`.

> [!NOTE]
> The GraphQL `checkoutSession` query is the one exception — it returns `amount` in major MVR units (`24.90`), because it drives the hosted checkout page. Every REST body and webhook payload is in laari.

## Your first request

Create a checkout session and get back a hosted payment link. This is the whole "take a payment" flow in one call:

```bash title="Create a checkout session"
curl https://api.payer.app/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order_10482" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2490,
    "title": "Order #10482",
    "reference": "order_10482"
  }'
```

```json title="200 OK"
{
  "id": "9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69",
  "reference": "order_10482",
  "url": "https://api.payer.app/9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69"
}
```

Send the customer to `url`, then either [poll the session](/developers/docs/checkout#retrieve-a-session) or — better — register a [webhook](/developers/docs/webhooks) so Payer tells you the moment it's paid.

## Build with AI

Every page here has a Markdown twin: add `.md` to any docs URL and you get the raw source, made for pasting into an LLM. The **Build with AI** button at the top of each page hands your assistant a ready-made prompt that points it at those specs.

## Getting a key

Keys are issued from the **Developers** page in your Payer dashboard. Don't have access yet? [Join the developer waitlist](/developers#waitlist) — we onboard in small batches.