Authentication

Base URL

https://api.peerpayment.org
# Local development typically uses http://localhost:3000

There is no separate sandbox API mode. Approved merchants use one runtime; the first 150 successful deposits/withdrawals are credit-covered.

API key

Send your key with either header (both are accepted):

Authorization: Bearer $PEERPAY_API_KEY
# or: x-api-key: $PEERPAY_API_KEY
PeerPay-Version: 2026-06-01

• Authorization: Bearer <api_key> (recommended)
• x-api-key: <api_key>

Create keys in the merchant dashboard. Required scopes for public routes:

• deposits:create — POST /v1/deposits
• deposits:read — get/list deposits and events
• withdrawals:create — POST /v1/withdrawals
• withdrawals:read — get/list withdrawals and events

API version

Supported value: PeerPay-Version: 2026-06-01. The header is optional on most requests (defaults to 2026-06-01) and is validated on create deposit / withdrawal. An unsupported version returns 400 invalid_api_version.

Idempotency

Idempotency-Key is required on POST /v1/deposits and POST /v1/withdrawals (1–256 characters). Use an opaque internal order ID or persisted UUID, such as deposit_order_784291, and reuse the exact value for every retry of that logical order. Do not generate a new timestamp while retrying.

• Same key + same body → 200 with the stored response (replay).
• First successful create → 201.
• Same key + different body → 409 idempotency_conflict.
• Keys are retained for 24 hours.

Discover Supported Methods

Any active API key can call GET /v1/capabilities; no additional scope is required. Use the returned codes when preselecting a deposit method or withdrawal destination.

curl "https://api.peerpayment.org/v1/capabilities" \
  -H "Authorization: Bearer $PEERPAY_API_KEY"

{
  "data": {
    "currency": "ETB",
    "deposits": {
      "payment_methods": [
        { "code": "telebirr", "display_name": "Telebirr", "account_type": "mobile_wallet" }
      ]
    },
    "withdrawals": {
      "destination_institutions": [
        { "code": "cbe", "display_name": "Commercial Bank of Ethiopia", "account_type": "bank_account" }
      ]
    }
  },
  "meta": { "requestId": "req_9f3a2c1b", "apiVersion": "2026-06-01" }
}

Capabilities are advisory. Account capacity can change after discovery; the create response and hosted checkout options are authoritative.

Request tracing

Every response includes PeerPay-Request-Id. Log it with your merchant-side correlation IDs. Error bodies also include meta.requestId.