One request, from key to webhook.
The public API is a REST surface over payments, checkout, payouts and settlement. This page explains how a call is authenticated, routed and reported back.
1 · Your backend
Server-side requestAuthorization: Bearer olp_… · optional Idempotency-Key
2 · Authenticate
Key lookup and scope checkKeys are stored as hashes. Each call needs the scope its endpoint requires, e.g. payment_links:write
3 · Resource
Paymentslist, get, cancel, refund
Links & QRcreate checkout surfaces
Payoutsrequest, list, cancel
SettlementsJSON or CSV
4 · Outcome
Response now, webhook laterSynchronous JSON for the call; signed payment.succeeded, payout.completed and other events to your endpoint
Endpoints.
Every endpoint sits under the base URL https://merchant.olympuspay.co/api/v1. The base URL itself returns nothing: open the reference endpoint to test it, or read the developer portal.
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /payments | List payments | payments:read |
| GET | /payments/{id} | Get a payment | payments:read |
| POST | /payments/{id}/cancel | Cancel a pending payment | payments:cancel |
| POST | /payments/{id}/refund | Refund in full or in part | refunds:create_* |
| POST | /payment-links | Create a payment link | payment_links:write |
| POST | /qr-codes | Create a dynamic QR code | qr_codes:write |
| GET/POST | /split-recipients | List or register split recipients | recipients:* |
| GET/POST | /payouts | List or request payouts (live keys) | payouts:* |
| GET | /settlements | Settlements as JSON or CSV | settlements:read |
| GET | /account | Business profile and verification | account:read |
| GET/POST | /webhooks | List or register webhook endpoints | webhooks:* |
| GET | /reference | Status and event reference (no auth) | - |
Example request.
Bearer key, JSON body, optional idempotency key. The response is JSON. Anything that changes state later is reported by webhook.
# Create a payment link (sandbox key)
curl -X POST https://merchant.olympuspay.co/api/v1/payment-links \
-H "Authorization: Bearer olp_test_…" \
-H "Idempotency-Key: 7f3c1a52-order-1042" \
-H "Content-Type: application/json" \
-d '{
"title": "Invoice 1042",
"amount": 126.00,
"currency": "BWP",
"returnUrl": "https://example.com/thanks"
}'const res = await fetch("https://merchant.olympuspay.co/api/v1/payment-links", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OLYMPUS_KEY}`,
"Idempotency-Key": "7f3c1a52-order-1042",
"Content-Type": "application/json",
},
body: JSON.stringify({
title: "Invoice 1042",
amount: 126.00,
currency: "BWP",
}),
});
const link = await res.json();// 200 OK - the payment link object (fields shown are illustrative)
{
"id": "…",
"title": "Invoice 1042",
"amount": 126,
"currency": "BWP",
"url": "https://…"
}Scope of the public API.
Limits and availability
Rate limits and service levels are agreed per integration. Contact us for the limits that apply to your use case.
Coverage
The public API covers acceptance, payouts and settlement. Account, card and transfer operations run through the Olympus apps. Talk to us about embedding them.