Build on Payixay

REST APIs, hosted checkout, signed webhooks and a full sandbox. This page covers the integration model; the complete API reference lives in the developer documentation.

Open API reference Request sandbox access

Integration paths

Three ways to integrate

1. Hosted payment page

Redirect the customer to a Payixay-hosted checkout. No card data touches your systems, which keeps you out of PCI scope. Most merchants go live this way in days.

2. Hosted fields

Embed card fields served from gateway infrastructure inside your own checkout design — your look, our PCI scope.

3. Server-to-server API

Full API integration for platforms with their own certified card capture. Requires your own PCI compliance evidence during onboarding.

Authentication

Bearer keys, sandbox and live

Every account gets separate sandbox and live API keys. Send the key in the Authorization header. Keys are shown once at creation — store them in your secrets manager, never in client-side code or repositories.

# Create a payment session (sandbox)
curl -X POST https://api.sandbox.payixay.example/v1/sessions
  -H “Authorization: Bearer sk_test_…”
  -H “Content-Type: application/json”
  -d ‘{“amount”: 13700, “currency”: “USD”,
      “reference”: “order-8471”,
      “success_url”: “https://yourstore.com/thanks”}’

Response

Sample response

# 201 Created
{
  “id”: “ses_9f27c1”,
  “status”: “pending”,
  “amount”: 13700,
  “currency”: “USD”,
  “checkout_url”: “https://pay.payixay.example/s/9f27c1”,
  “expires_at”: “2026-07-10T19:30:00Z”
}

Redirect the customer to checkout_url. The result comes back on your success_url and — authoritatively — via webhook.

Webhooks

Signed events, not polling

Payixay sends a signed HTTP POST to your endpoint on every state change. Verify the signature header with your webhook secret before trusting the payload, respond with HTTP 200, and treat webhooks as the source of truth for reconciliation. Deliveries retry with backoff for 24 hours.

✓ payment.created · payment.authorized · payment.captured
✓ payment.failed · refund.requested · refund.completed
✓ dispute.opened · chargeback.resolved · payout.settled

Errors

Error codes

Code	Meaning
401 unauthorized	Missing or invalid API key
402 card_declined	Issuer declined — reason in decline_code
409 duplicate_reference	Reference already used — safe idempotency signal
422 validation_error	Invalid field — details in errors[]
429 rate_limited	Too many requests — respect Retry-After

Platform behavior

Rate limits, versioning, sandbox

Rate limits

Default 60 requests/second per key. 429 responses include a Retry-After header. Contact us for higher sustained limits before a launch.

API versioning

Versioned via the URL path (/v1/). Breaking changes ship as a new version with a migration window — v1 endpoints are not changed under you.

Sandbox

Full-fidelity test environment with test cards for approve/decline/3DS-challenge paths and simulated M-Pesa STK pushes. Sandbox keys are issued at onboarding.

Integration checklist: verify webhook signatures · use idempotent references · handle card_declined gracefully at checkout · test 3-D Secure challenge flows in sandbox · reconcile from webhooks, not redirects.

Get sandbox credentials

Apply for a merchant account and our team will issue sandbox keys with your onboarding review.

Create merchant account