Zyrix — The Payment Operating System

API Reference

Everything you need to integrate Zyrix. Every endpoint, with copy-paste examples in five languages

Base URLhttps://api.zyrix.co

Authentication

POST/api/auth/request-otpPublic

Request a one-time password for merchant authentication.

Request Body

{
  "email": "merchant@example.com"
}

Response · 200

{
  "request_id": "req_8f2a1c",
  "expires_in": 300
}

Error Codes

400 · Invalid request body429 · Rate limit exceeded (100/min)

curl -X POST https://api.zyrix.co/api/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{
  "email": "merchant@example.com"
}'

POST/api/auth/verify-otpPublic

Verify the OTP and receive an access token.

Request Body

{
  "request_id": "req_8f2a1c",
  "otp": "482913"
}

Response · 200

{
  "token": "eyJhbGci...",
  "merchant_id": "mer_1a2b3c"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "req_8f2a1c",
  "otp": "482913"
}'

Payments

POST/api/payments/create🔒 Auth required

Create a payment. Zyrix routes it to the optimal provider via AI.

Request Body

{
  "amount": 10000,
  "currency": "SAR",
  "routing": "smart",
  "payment_method": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "123"
    }
  },
  "customer": {
    "email": "ahmed@example.com",
    "name": "Ahmed Al-Farsi",
    "phone": "+966501234567"
  },
  "metadata": {
    "order_id": "ORD-12345"
  }
}

Response · 200

{
  "id": "pay_1a2b3c4d5e6f",
  "status": "succeeded",
  "amount": 10000,
  "currency": "SAR",
  "provider": "hyperpay",
  "routing_decision": {
    "strategy": "smart",
    "reason": "Highest approval rate for SA Visa cards",
    "alternatives_considered": [
      "stripe",
      "paytabs"
    ],
    "latency_ms": 145
  },
  "risk_score": 12,
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

400 · Invalid request body401 · Invalid API key402 · Payment declined429 · Rate limit exceeded (100/min)500 · Internal server error

curl -X POST https://api.zyrix.co/api/payments/create \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 10000,
  "currency": "SAR",
  "routing": "smart",
  "payment_method": {
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "123"
    }
  },
  "customer": {
    "email": "ahmed@example.com",
    "name": "Ahmed Al-Farsi",
    "phone": "+966501234567"
  },
  "metadata": {
    "order_id": "ORD-12345"
  }
}'

GET/api/payments/:id🔒 Auth required

Retrieve a single payment by its ID.

Response · 200

{
  "id": "pay_1a2b3c4d5e6f",
  "status": "succeeded",
  "amount": 10000,
  "currency": "SAR",
  "provider": "hyperpay",
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X GET https://api.zyrix.co/api/payments/:id \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/payments/list🔒 Auth required

List payments with pagination and optional filters.

Response · 200

{
  "data": [
    {
      "id": "pay_1a2b3c4d5e6f",
      "status": "succeeded",
      "amount": 10000,
      "currency": "SAR"
    }
  ],
  "has_more": false,
  "total": 1
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/payments/list \
  -H "Authorization: Bearer sk_live_xxxxx"

POST/api/payments/:id/capture🔒 Auth required

Capture a previously authorized payment.

Request Body

{
  "amount": 10000
}

Response · 200

{
  "id": "pay_1a2b3c4d5e6f",
  "status": "captured",
  "amount": 10000
}

Error Codes

400 · Invalid request body401 · Invalid API key404 · Resource not found

curl -X POST https://api.zyrix.co/api/payments/:id/capture \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 10000
}'

POST/api/payments/:id/void🔒 Auth required

Void an authorized payment before capture.

Response · 200

{
  "id": "pay_1a2b3c4d5e6f",
  "status": "voided"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X POST https://api.zyrix.co/api/payments/:id/void \
  -H "Authorization: Bearer sk_live_xxxxx"

POST/api/payments/:id/refund🔒 Auth required

Refund a captured payment, fully or partially.

Request Body

{
  "amount": 5000,
  "reason": "requested_by_customer"
}

Response · 200

{
  "id": "pay_1a2b3c4d5e6f",
  "status": "refunded",
  "refund_id": "ref_9z8y7x",
  "amount": 5000
}

Error Codes

400 · Invalid request body401 · Invalid API key404 · Resource not found

curl -X POST https://api.zyrix.co/api/payments/:id/refund \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "reason": "requested_by_customer"
}'

Payment Links

POST/api/payment-links🔒 Auth required

Create a shareable payment link.

Request Body

{
  "amount": 25000,
  "currency": "SAR",
  "description": "Invoice #1024",
  "expires_at": "2026-04-01T00:00:00Z"
}

Response · 200

{
  "id": "lnk_3c4d5e",
  "url": "https://pay.zyrix.co/l/3c4d5e",
  "status": "active",
  "amount": 25000,
  "currency": "SAR"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/payment-links \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 25000,
  "currency": "SAR",
  "description": "Invoice #1024",
  "expires_at": "2026-04-01T00:00:00Z"
}'

GET/api/payment-links🔒 Auth required

List all payment links.

Response · 200

{
  "data": [
    {
      "id": "lnk_3c4d5e",
      "url": "https://pay.zyrix.co/l/3c4d5e",
      "status": "active"
    }
  ],
  "has_more": false
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/payment-links \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/payment-links/:id🔒 Auth required

Retrieve a single payment link.

Response · 200

{
  "id": "lnk_3c4d5e",
  "url": "https://pay.zyrix.co/l/3c4d5e",
  "status": "active",
  "amount": 25000,
  "currency": "SAR",
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X GET https://api.zyrix.co/api/payment-links/:id \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/payment-links/:id/cancel🔒 Auth required

Cancel an active payment link.

Response · 200

{
  "id": "lnk_3c4d5e",
  "status": "cancelled"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/payment-links/:id/cancel \
  -H "Authorization: Bearer sk_live_xxxxx"

Subscriptions

POST/api/subscriptions🔒 Auth required

Create a recurring subscription for a customer.

Request Body

{
  "customer_id": "cus_1a2b3c",
  "plan": "pro_monthly",
  "amount": 9900,
  "currency": "SAR",
  "interval": "month"
}

Response · 200

{
  "id": "sub_7h8i9j",
  "status": "active",
  "next_billing": "2026-04-25"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/subscriptions \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_1a2b3c",
  "plan": "pro_monthly",
  "amount": 9900,
  "currency": "SAR",
  "interval": "month"
}'

GET/api/subscriptions🔒 Auth required

List all subscriptions.

Response · 200

{
  "data": [
    {
      "id": "sub_7h8i9j",
      "status": "active",
      "next_billing": "2026-04-25"
    }
  ],
  "has_more": false
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/subscriptions \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/subscriptions/:id/pause🔒 Auth required

Pause an active subscription.

Response · 200

{
  "id": "sub_7h8i9j",
  "status": "paused"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/subscriptions/:id/pause \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/subscriptions/:id/resume🔒 Auth required

Resume a paused subscription.

Response · 200

{
  "id": "sub_7h8i9j",
  "status": "active"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/subscriptions/:id/resume \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/subscriptions/:id/cancel🔒 Auth required

Cancel a subscription permanently.

Response · 200

{
  "id": "sub_7h8i9j",
  "status": "cancelled"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/subscriptions/:id/cancel \
  -H "Authorization: Bearer sk_live_xxxxx"

Invoices

POST/api/invoices🔒 Auth required

Create an invoice with automatic tax calculation.

Request Body

{
  "customer_id": "cus_1a2b3c",
  "items": [
    {
      "name": "Consulting",
      "amount": 50000,
      "quantity": 1
    }
  ],
  "currency": "SAR",
  "due_date": "2026-04-10",
  "tax_rate": 15
}

Response · 200

{
  "id": "inv_2k3l4m",
  "number": "INV-1024",
  "status": "draft",
  "total": 57500,
  "pdf_url": "https://pay.zyrix.co/i/2k3l4m.pdf"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/invoices \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_1a2b3c",
  "items": [
    {
      "name": "Consulting",
      "amount": 50000,
      "quantity": 1
    }
  ],
  "currency": "SAR",
  "due_date": "2026-04-10",
  "tax_rate": 15
}'

GET/api/invoices🔒 Auth required

List all invoices.

Response · 200

{
  "data": [
    {
      "id": "inv_2k3l4m",
      "number": "INV-1024",
      "status": "draft",
      "total": 57500
    }
  ],
  "has_more": false
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/invoices \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/invoices/:id🔒 Auth required

Retrieve a single invoice.

Response · 200

{
  "id": "inv_2k3l4m",
  "number": "INV-1024",
  "status": "draft",
  "total": 57500,
  "pdf_url": "https://pay.zyrix.co/i/2k3l4m.pdf",
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X GET https://api.zyrix.co/api/invoices/:id \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/invoices/:id/send🔒 Auth required

Send an invoice by email or WhatsApp.

Request Body

{
  "channel": "whatsapp"
}

Response · 200

{
  "id": "inv_2k3l4m",
  "status": "sent",
  "sent_to": "+966501234567"
}

Error Codes

400 · Invalid request body401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/invoices/:id/send \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "whatsapp"
}'

PUT/api/invoices/:id/mark-paid🔒 Auth required

Mark an invoice as paid.

Response · 200

{
  "id": "inv_2k3l4m",
  "status": "paid",
  "paid_at": "2026-03-26T08:00:00Z"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/invoices/:id/mark-paid \
  -H "Authorization: Bearer sk_live_xxxxx"

Routing

GET/api/routing/rules🔒 Auth required

List all routing rules.

Response · 200

{
  "data": [
    {
      "id": "rul_5n6o7p",
      "name": "SA cards to HyperPay",
      "strategy": "smart",
      "priority": 1
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/routing/rules \
  -H "Authorization: Bearer sk_live_xxxxx"

POST/api/routing/rules🔒 Auth required

Create a routing rule.

Request Body

{
  "name": "SA cards to HyperPay",
  "strategy": "smart",
  "conditions": [
    {
      "field": "country",
      "operator": "equals",
      "value": "SA"
    }
  ],
  "provider": "hyperpay"
}

Response · 200

{
  "id": "rul_5n6o7p",
  "name": "SA cards to HyperPay",
  "strategy": "smart",
  "status": "active"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/routing/rules \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "SA cards to HyperPay",
  "strategy": "smart",
  "conditions": [
    {
      "field": "country",
      "operator": "equals",
      "value": "SA"
    }
  ],
  "provider": "hyperpay"
}'

PUT/api/routing/rules/:id🔒 Auth required

Update a routing rule.

Request Body

{
  "name": "SA cards to Moyasar",
  "priority": 2
}

Response · 200

{
  "id": "rul_5n6o7p",
  "name": "SA cards to Moyasar",
  "strategy": "smart",
  "priority": 2
}

Error Codes

400 · Invalid request body401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/routing/rules/:id \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "SA cards to Moyasar",
  "priority": 2
}'

Customers

POST/api/customers🔒 Auth required

Create a customer.

Request Body

{
  "email": "ahmed@example.com",
  "name": "Ahmed Al-Farsi",
  "phone": "+966501234567",
  "metadata": {
    "tier": "vip"
  }
}

Response · 200

{
  "id": "cus_1a2b3c",
  "email": "ahmed@example.com",
  "name": "Ahmed Al-Farsi",
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/customers \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ahmed@example.com",
  "name": "Ahmed Al-Farsi",
  "phone": "+966501234567",
  "metadata": {
    "tier": "vip"
  }
}'

GET/api/customers/:id🔒 Auth required

Retrieve a single customer.

Response · 200

{
  "id": "cus_1a2b3c",
  "email": "ahmed@example.com",
  "name": "Ahmed Al-Farsi",
  "phone": "+966501234567",
  "created_at": "2026-03-25T10:30:00Z"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X GET https://api.zyrix.co/api/customers/:id \
  -H "Authorization: Bearer sk_live_xxxxx"

PUT/api/customers/:id🔒 Auth required

Update a customer.

Request Body

{
  "name": "Ahmed F. Al-Farsi",
  "phone": "+966509876543"
}

Response · 200

{
  "id": "cus_1a2b3c",
  "email": "ahmed@example.com",
  "name": "Ahmed F. Al-Farsi",
  "phone": "+966509876543"
}

Error Codes

400 · Invalid request body401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/customers/:id \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ahmed F. Al-Farsi",
  "phone": "+966509876543"
}'

Balance & Settlements

GET/api/balance🔒 Auth required

Retrieve your current balance.

Response · 200

{
  "available": [
    {
      "amount": 1250000,
      "currency": "SAR"
    }
  ],
  "pending": [
    {
      "amount": 340000,
      "currency": "SAR"
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/balance \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/settlements🔒 Auth required

List settlements.

Response · 200

{
  "data": [
    {
      "id": "set_8q9r0s",
      "amount": 1250000,
      "currency": "SAR",
      "status": "paid",
      "arrival_date": "2026-03-27"
    }
  ],
  "has_more": false
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/settlements \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/settlements/:id🔒 Auth required

Retrieve a single settlement.

Response · 200

{
  "id": "set_8q9r0s",
  "amount": 1250000,
  "currency": "SAR",
  "status": "paid",
  "arrival_date": "2026-03-27",
  "transactions": 412
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X GET https://api.zyrix.co/api/settlements/:id \
  -H "Authorization: Bearer sk_live_xxxxx"

Analytics

GET/api/analytics🔒 Auth required

Retrieve an analytics overview.

Response · 200

{
  "volume": 3410000,
  "transactions": 1284,
  "approval_rate": 97.8,
  "period": "30d"
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/analytics \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/analytics/revenue🔒 Auth required

Retrieve revenue analytics over time.

Response · 200

{
  "total": 3410000,
  "currency": "SAR",
  "by_day": [
    {
      "date": "2026-03-24",
      "amount": 112000
    },
    {
      "date": "2026-03-25",
      "amount": 138000
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/analytics/revenue \
  -H "Authorization: Bearer sk_live_xxxxx"

GET/api/analytics/providers🔒 Auth required

Compare performance across providers.

Response · 200

{
  "data": [
    {
      "provider": "hyperpay",
      "volume": 1840000,
      "approval_rate": 98.1,
      "latency": 145
    },
    {
      "provider": "moyasar",
      "volume": 980000,
      "approval_rate": 97.2,
      "latency": 160
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/analytics/providers \
  -H "Authorization: Bearer sk_live_xxxxx"

Webhooks

POST/api/webhooks/configure🔒 Auth required

Configure a webhook endpoint and events.

Request Body

{
  "url": "https://mystore.com/webhook",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "subscription.renewed"
  ]
}

Response · 200

{
  "id": "whk_4t5u6v",
  "url": "https://mystore.com/webhook",
  "status": "active",
  "secret": "whsec_xxx"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/webhooks/configure \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://mystore.com/webhook",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "subscription.renewed"
  ]
}'

GET/api/webhooks/events🔒 Auth required

List recent webhook delivery events.

Response · 200

{
  "data": [
    {
      "id": "evt_7w8x9y",
      "event": "payment.succeeded",
      "delivered": true,
      "created_at": "2026-03-25T10:31:00Z"
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/webhooks/events \
  -H "Authorization: Bearer sk_live_xxxxx"

POST/api/webhooks/test🔒 Auth required

Send a test webhook to your endpoint.

Request Body

{
  "event": "subscription.renewed"
}

Response · 200

{
  "delivered": true,
  "status_code": 200,
  "latency_ms": 230
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/webhooks/test \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "subscription.renewed"
}'

API Keys

GET/api/api-keys🔒 Auth required

List your API keys.

Response · 200

{
  "data": [
    {
      "id": "key_0z1a2b",
      "prefix": "sk_live_",
      "mode": "live",
      "created_at": "2026-03-01T00:00:00Z",
      "last_used": "2026-03-25T10:30:00Z"
    }
  ]
}

Error Codes

401 · Invalid API key

curl -X GET https://api.zyrix.co/api/api-keys \
  -H "Authorization: Bearer sk_live_xxxxx"

POST/api/api-keys🔒 Auth required

Create a new API key.

Request Body

{
  "name": "Production server",
  "mode": "live"
}

Response · 200

{
  "id": "key_0z1a2b",
  "key": "sk_live_4f8a2c9d1e6b",
  "prefix": "sk_live_",
  "mode": "live"
}

Error Codes

400 · Invalid request body401 · Invalid API key

curl -X POST https://api.zyrix.co/api/api-keys \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production server",
  "mode": "live"
}'

PUT/api/api-keys/:id/revoke🔒 Auth required

Revoke an API key.

Response · 200

{
  "id": "key_0z1a2b",
  "status": "revoked"
}

Error Codes

401 · Invalid API key404 · Resource not found

curl -X PUT https://api.zyrix.co/api/api-keys/:id/revoke \
  -H "Authorization: Bearer sk_live_xxxxx"