Push an order

Record one order and how its money splits across the restaurant, the courier and your commission.

POST https://zovopay.com/api/partner/v1/orders

Rate limit: 60 requests/minute. Authenticated with X-Client-Id / X-Client-Secret.

The split model

You send the order total and a list of splits. Each split names a beneficiary type and its share. ZovoPay credits each party from your clearing wallet at settlement.

Request body

Field	Type	Description
`partner_order_ref` required	string	Your order id. Idempotent: re-sending the same ref returns the existing order.
`payment_source` required	enum	One of `zovopay`, `card`, `paypal`, `cod`.
`total_amount` required	number	Gross order amount, greater than 0.
`currency` required	string(3)	ISO currency code, e.g. `USD`.
`splits` required	array	At least one split (see below).
`splits[].beneficiary_type` required	enum	`merchant`, `courier` or `partner` (your commission).
`splits[].beneficiary_ref` optional	integer	The link id of the specific merchant/courier (from your dashboard). Omit for your own commission.
`splits[].amount` required	number	This beneficiary’s share (0 or more).
`idempotency_key` optional	string	Extra safeguard against duplicate submissions.
`is_shadow` optional	boolean	True if the restaurant is NOT on ZovoPay (tracked in your shadow ledger instead).
`shadow_merchant_ref` / `shadow_merchant_name` optional	string	Identify the off-platform restaurant when is_shadow is true.

Example request

{
  "partner_order_ref": "D-1001",
  "payment_source": "zovopay",
  "total_amount": 25.00,
  "currency": "USD",
  "splits": [
    { "beneficiary_type": "merchant", "beneficiary_ref": 12, "amount": 20.00 },
    { "beneficiary_type": "courier",  "beneficiary_ref": 34, "amount": 3.00 },
    { "beneficiary_type": "partner",  "amount": 2.00 }
  ]
}

Success — 201 Created

{
  "status": true,
  "data": {
    "order_id": 9001,
    "partner_order_ref": "D-1001",
    "currency": "USD",
    "order_amount": 25.00,
    "payment_method": "zovopay",
    "payment_status": "pending",
    "settlement_status": "unsettled",
    "is_shadow": false
  }
}

🔁 Idempotency: orders are unique per (company, partner_order_ref). Re-sending the same ref will not create a duplicate.