POST/v1/checkout/create

Create payment session

Creates a hosted or redirect checkout session for card, mobile money, or Zimswitch payments.

Authentication

Secret Key — send Authorization: Bearer YOUR_KEY header.

Request parameters

Parameter	Type	Required	Description
`amount`	string	Yes	Amount in "10.00" format (2 decimal places)
`currency`	string	Yes	USD or ZWG
`merchantTransactionId`	string	Yes	Your unique reference (max 64 chars)
`returnUrl`	string	Yes	URL to redirect customer after payment
`customerEmail`	string	No	Customer email
`customerName`	string	No	Customer display name
`customerPhone`	string	No	Required for mobile money (+2637XXXXXXXX)
`walletType`	string	No	ecocash \| innbucks \| onemoney
`description`	string	No	Payment description shown to customer
`metadata`	object	No	Your own key-value pairs (strings; up to 50 keys, keys up to 40 and values up to 500 characters). Returned on the payment and in its webhook events.

walletType and customerPhone must be sent together for mobile money payments.

Response fields

Field	Type	Description
`checkout_id`	string	Watenga checkout session ID
`payment_url`	string	URL to complete payment (hosted checkout)
`gateway_name`	string	Gateway adapter used (eftpay, zimswitch, ecocash, etc.)
`requires_polling`	boolean	True for mobile money — poll mobile-status endpoint
`metadata`	object	The metadata you sent (or the checkout session, payment link or invoice’s own)

Code examples

bash

curl -X POST https://api.watenga.africa/v1/checkout/create \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "USD",
    "merchant_transaction_id": "INV-001",
    "return_url": "https://yoursite.com/thank-you",
    "customer_name": "Tendai Moyo",
    "customer_email": "tendai@example.com"
  }'

Response example

json

{
  "success": true,
  "data": {
    "checkout_id": "chk_01HQXYZ",
    "payment_url": "https://checkout.watenga.africa/pay/chk_01HQXYZ",
    "gateway_name": "eftpay",
    "requires_polling": false
  }
}