okePay REST API

Authentication

All requests are authenticated with a per-merchant API key passed as a Bearer token. Sandbox and production keys are issued from your merchant dashboard after KYB approval.

Authorization: Bearer {API_KEY}
Content-Type:  application/json
X-Merchant-Id: m_3892
X-Idempotency-Key: 0c1b1d2e-...   # optional, recommended on POST

Create a payment

POST /v1/payments — the orchestration engine scores up to 12 routing factors and picks the best provider for this transaction.

POST /v1/payments
{
  "order_ref":     "ORDER-100234",
  "amount":        129.90,
  "currency":      "EUR",
  "customer": {
    "email":       "buyer@example.com",
    "country":     "DE",
    "ip":          "203.0.113.42"
  },
  "payment_method": "card",          // card | apm | wallet | crypto | paylink
  "return_url":    "https://your-shop.example/return",
  "webhook_url":   "https://your-shop.example/okepay/ipn"
}

200 OK
{
  "payment_id":   "pay_8b1e...",
  "status":       "pending",
  "redirect_url": "https://pay.okepay.biz/checkout/8b1e...",
  "selected_route": {
    "acquirer":   "ACQ-EU-1",
    "score":      0.94,
    "factors":    ["bin_country_match","mcc_fit","recent_auth_rate"]
  }
}

Cascading retry

Soft declines are retried automatically through alternative providers. You don't need to call anything — the API returns status: "succeeded" with attempts describing the cascade.

{
  "payment_id": "pay_8b1e...",
  "status":     "succeeded",
  "attempts": [
    { "n": 1, "acquirer": "ACQ-EU-1",  "result": "soft_decline", "code": "05" },
    { "n": 2, "acquirer": "ACQ-EU-2",  "result": "soft_decline", "code": "do_not_honor" },
    { "n": 3, "acquirer": "ACQ-APM-DE","result": "approved" }
  ]
}

Paylink (Email / QR)

POST /v1/paylinks — generate a hosted-checkout URL the customer can open from email, SMS or a QR code. Used by the okePay vPOS mobile flow and as the fallback fourth attempt of the cascade.

POST /v1/paylinks
{
  "order_ref":  "ORDER-100234",
  "amount":     129.90,
  "currency":   "EUR",
  "expires_in": 86400,
  "send_email": "buyer@example.com"
}

Webhooks (IPN)

Every payment lifecycle event is POSTed to your webhook_url, signed with HMAC-SHA256 over the raw body using your webhook secret.

POST https://your-shop.example/okepay/ipn
X-Okepay-Signature: t=1715342812,v1=8f3c...

{
  "event":      "payment.succeeded",   // .pending | .succeeded | .failed | .refunded | .chargeback
  "payment_id": "pay_8b1e...",
  "order_ref":  "ORDER-100234",
  "amount":     129.90,
  "currency":   "EUR",
  "occurred_at":"2026-05-10T12:46:52Z"
}

HTTP status codes