Integration Guide for Developers

BlueZone integrates with payment providers and shipping companies through a separate Adapter per provider. The provider only needs an API meeting the minimum described here; we then build, test and approve the Adapter.

How to join

• Submit the "Join integration" form with a link to your documentation.
• We review your docs and contact you technically within a few business days.
• You give us a Sandbox environment and test keys.
• We build the Adapter and run the acceptance tests below.
• Once passed, we approve you and list your name and logo on the "Partners" page.

General requirements

• HTTPS (TLS 1.2 or later) and JSON for requests and responses.
• API-key authentication in the header: Authorization: Bearer <API_KEY>.
• A Sandbox separate from production.
• Clear HTTP status codes and JSON errors with code and message.
• Idempotency support via an Idempotency-Key header.

A. Payment gateways

1) Create a payment

POST /v1/payments
{
  "reference": "MK-1024",
  "amount": 150.000,
  "currency": "KWD",
  "customer": { "name": "Customer", "email": "a@b.com", "phone": "+96551234567" },
  "language": "en",
  "callback_url": "https://example.com/pay/return",
  "webhook_url": "https://example.com/pay/webhook"
}

Required response:

{ "id": "pay_8f2c", "status": "pending", "payment_url": "https://gateway.com/pay/pay_8f2c" }

We redirect the customer to payment_url to complete payment.

2) Get status

GET /v1/payments/{id}
{ "id": "pay_8f2c", "status": "paid", "reference": "MK-1024", "amount": 150.000, "currency": "KWD", "method": "knet", "paid_at": "2026-10-14T18:20:00Z" }

Supported statuses: pending, paid, failed, cancelled, refunded.

3) Webhook

When the status changes, POST the same body as the status call to webhook_url, signed in the X-Signature header as an HMAC-SHA256 of the request body with a shared secret. We verify the signature and reply 200.

4) Refunds (optional)

POST /v1/payments/{id}/refunds
{ "amount": 150.000, "reason": "customer_request" }

B. Shipping companies

1) Rates

POST /v1/rates
{ "from": { "country": "KW", "city": "Kuwait City" }, "to": { "country": "KW", "area": "Salmiya" }, "weight_kg": 1.2, "cod": 25.000 }

Response: a list of services with price and estimated time.

2) Create shipment

POST /v1/shipments
{
  "reference": "ORD-5531",
  "service": "express",
  "sender": { "name": "Store", "phone": "+965...", "address": "..." },
  "recipient": { "name": "Customer", "phone": "+965...", "address": "...", "area": "Salmiya" },
  "parcels": [ { "weight_kg": 1.2 } ],
  "cod_amount": 25.000
}

Response: { "id": "shp_123", "tracking_number": "KW123456", "label_url": "https://.../label.pdf" }

3) Tracking

GET /v1/shipments/{id}/tracking
{ "status": "out_for_delivery", "events": [ { "status": "picked_up", "at": "...", "note": "..." } ] }

Statuses: created, picked_up, in_transit, out_for_delivery, delivered, failed, returned, cancelled.

4) Cancel and Webhook

POST /v1/shipments/{id}/cancel cancels before pickup. A Webhook updates statuses with the same X-Signature signing.

Acceptance tests

• Payment success, failure and cancellation, with matching amount and currency.
• A correctly signed Webhook arrives, and a wrong signature is rejected.
• No duplicate operation when retrying with the same Idempotency-Key.
• Create, track, cancel a shipment and status updates via Webhook.
• Reasonable response time and clear error documentation.

Technical contact

After you apply, our technical team will contact you at the email you entered in the form.