POST /checkout/order-api-gateway

For API Gateway products you set the price on each request. Zenofy returns a checkout URL; the buyer pays on pay.zenofy.io. Webhooks are configured on the product, not in the API body.

Base URL: your Zenofy API host (for example https://api.zenofy.io). Path: <code>/checkout/order-api-gateway</code> (POST).

Use the same Checkout API key as other checkout endpoints (merchant app → Settings → Checkout API key). Header: <code>Api-Key</code> (plain text, not Bearer).

The product must be type API payment gateway, belong to your account, have a webhook URL saved on the product, and be active. There is no public product page — checkout is API-only.

Product setup (dashboard)

Create a product and choose API payment gateway. In the webhook section enter your Webhook URL (required) and optional Webhook secret for HMAC. Enable the payment methods you want on the product. Variable amount and currency come from each API call.

Authentication

Header Api-Key: your full checkout API secret. Missing or invalid keys return HTTP 401.

HTTP request

POST · Content-Type: application/json · Api-Key

Sample request (illustrative)

POST /checkout/order-api-gateway HTTP/1.1
Host: api.zenofy.io
Api-Key: YOUR_CHECKOUT_API_KEY
Content-Type: application/json

{ ... }

JSON body (fields)

Field	Type	Notes
productId	string	Required. API Gateway product id.
amount	integer	Required. Amount in minor units (e.g. 2500 = 25.00).
currency	string	Optional. ISO 4217 (3 letters). Defaults to product main currency.
reference	string	Optional. Your id (stored on the order; echoed in webhooks).
description	string	Optional. Line label on checkout; defaults to product name.
customer	object	Required. name, email, phone (E.164, e.g. +258840000000).
payment_methods	array	Optional. Aliases: card, mpesa, emola, emis, payfast, stripe, flutterwave. Omit to allow all gateways enabled on the product.
success_url	string	Optional. HTTPS redirect after successful payment. Used exactly as you send it (include any query string you need).
cancel_url	string	Optional. HTTPS URL for the Cancel button. Used exactly as you send it.
language	string	Optional. Checkout UI language (e.g. en, pt).

Sample JSON body

{
  "productId": "507f1f77bcf86cd799439011",
  "amount": 2500,
  "currency": "MZN",
  "reference": "inv-2026-0042",
  "description": "Pro plan — March 2026",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com",
    "phone": "+258840000000"
  },
  "payment_methods": ["mpesa", "card"],
  "success_url": "https://your-app.com/paid?ref=inv-2026-0042",
  "cancel_url": "https://your-app.com/cancelled",
  "language": "pt"
}

Successful response

HTTP 200 JSON: checkout_id (same value as the order id in MongoDB), checkout_url (absolute URL, path /c/{checkout_id}), and expires_at (ISO 8601 UTC). Errors return JSON with success: false and message (often HTTP 400).

HTTP 200 — success

{
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "checkout_url": "https://pay.zenofy.io/c/673f92b2c3d94a0012abcd01",
  "expires_at": "2026-05-20T14:30:00.0000000Z"
}

Payment page &amp; redirects

Open checkout_url for the buyer. If cancel_url is set, the payment page shows a cancel control that sends the buyer to that URL unchanged (order stays pending). After payment, if success_url is set, the buyer is redirected to that URL unchanged. Confirm payment via webhooks or GET /checkout/order-status?orderId={checkout_id}.

Related guides

• API gateway webhooks (payment.succeeded, payment.refunded, payment.chargeback)
• Check order status (GET)

All tutorials