Checkout Integration (Zanga Checkout)

Zanga Checkout is a standalone, high-performance payment service that allows developers to securely accept payments via Mobile Money and Card without building complex UI.

Integration Lifecycle

The integration follows a simple 3-step process:

Create a Payment Intent: Your backend creates a session on the Zanga Ledger.
Redirect to Checkout: Send the customer to the Zanga Checkout URL.
Handle Completion: Zanga redirects the customer back to your app and sends a webhook.

1. Create a Payment Intent

To initiate a checkout session, call the Zanga API from your backend using your Secret API Key.

POST /v1/payments/create

Request Headers

Header	Value
`Authorization`	`Bearer <YOUR_SECRET_KEY>`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`amountNgwe`	`BigInt`	Yes	Total amount in minimal units (e.g., 1000 for 10.00 ZMW).
`currency`	`String`	Yes	"ZMW" (currently supported).
`externalRef`	`String`	Yes	Your unique internal order/transaction ID.
`payerId`	`String`	Yes	Customer identifier (phone number or email).
`payeeId`	`String`	Yes	Your Merchant Wallet ID.
`idempotencyKey`	`UUID`	Yes	Unique UUID to prevent duplicate charges.
`successUrl`	`URL`	Yes	Where to redirect after successful payment.
`cancelUrl`	`URL`	Yes	Where to redirect if the payment is cancelled.
`isEscrow`	`Boolean`	No	If true, funds will be held in escrow until release.

Example Request:

{
  "amountNgwe": 50000,
  "currency": "ZMW",
  "externalRef": "ORDER_12345",
  "payerId": "+260970000000",
  "payeeId": "wallet_abc123",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "successUrl": "https://myapp.com/success",
  "cancelUrl": "https://myapp.com/cancel"
}

Response:

{
  "success": true,
  "data": {
    "id": "int_987654321",
    "status": "PROCESSING",
    "amountNgwe": 50000,
    ...
  }
}

2. Redirect to Checkout

Once you have the id from the response, redirect your customer to the Zanga Checkout service:

https://checkout.zanga.africa/checkout/{intentId}

For local development: http://localhost:4005/checkout/{intentId}

3. Handle Completion

Success & Cancel Redirects

Zanga will automatically redirect the customer to your successUrl or cancelUrl once the flow is finished.

[!WARNING] Do NOT rely solely on the browser redirect for order fulfillment. Always wait for the Webhook confirmation.

Webhook Confirmation

Zanga will send a POST request to your configured webhook endpoint with the payment status.

Event: payment.success

{
  "id": "evt_123...",
  "event": "payment.success",
  "data": {
    "intentId": "int_987654321",
    "externalRef": "ORDER_12345",
    "amount": 500,
    "currency": "ZMW"
  }
}

For more details on security and signature verification, see the Webhooks documentation.