Documentation

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.

View as Markdown

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	Take a one-off payment on a hosted page	Secret or publishable key
Webhooks	Get notified when a payment settles	Signed with a `whsec_` secret
Personal access tokens	Read your own balance and transactions	`pat_` token
OAuth2 apps	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 and it carries across all of them.

Base URL

There is a single base URL for every request:

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.

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:

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"
  }'

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 or — better — register a webhook 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 — we onboard in small batches.