Checkout

The Checkout API provides hosted payment pages for your customers. Create a checkout session, redirect your customer to the hosted page, and ZuriPay handles the payment UI and processing.

The Checkout flow is the recommended way to accept payments for most integrations. It handles payment method selection, form validation, and 3D Secure authentication automatically.

POST/v1/checkout

Create checkout

Create a new checkout session. This generates a hosted checkout page URL where your customer can complete their payment.

The checkout page at checkout.zuripay.app supports:

International Cards (Visa/Mastercard via Zimswitch/DPO)
EcoCash (Zimbabwe mobile money)
Ozow (South African bank payments)

Required attributes

Name
amount
Type
integer
Description
Amount in the smallest currency unit.
Name
currency
Type
string
Description
Three-letter ISO currency code.
Name
email
Type
string
Description
Customer's email address for receipts.

Optional attributes

Name
success_url
Type
string
Description
URL to redirect after successful payment.
Name
failure_url
Type
string
Description
URL to redirect after failed payment.
Name
payment_method_type
Type
string
Description
Pre-select payment method: mobile_money or card.
Name
payment_method_code
Type
string
Description
Specific method: ecocash, innbucks, zimswitch, dpo, ozow.

Request

POST

/v1/checkout

curl -X POST https://api.zuripay.app/v1/checkout \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "email": "[email protected]",
    "success_url": "https://yoursite.com/success",
    "failure_url": "https://yoursite.com/failure"
  }'

Response

{
  "result": "success",
  "checkout_id": "zp_chk_a1b2c3d4e5",
  "checkout_url": "https://checkout.zuripay.app?checkout_id=zp_chk_a1b2c3d4e5",
  "transaction_reference": "ZURIPAYa1b2c3d4e5"
}

GET/v1/checkout/:checkoutId

Get checkout session

Retrieve the details and current status of a checkout session.

Request

GET

/v1/checkout/zp_chk_a1b2c3d4e5

curl https://api.zuripay.app/v1/checkout/zp_chk_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_your_api_key"

Response

{
  "result": "success",
  "checkout": {
    "checkoutId": "zp_chk_a1b2c3d4e5",
    "amount": 2500,
    "charges": 25,
    "total": 2525,
    "currency": "USD",
    "status": "pending",
    "emailAddress": "[email protected]",
    "transactionReference": "ZURIPAYa1b2c3d4e5",
    "paymentMethods": [
      {"name": "EcoCash", "code": "ecocash", "type": "mobile_money"},
      {"name": "Visa/Mastercard", "code": "zimswitch", "type": "card"},
      {"name": "Ozow", "code": "ozow", "type": "bank_transfer"}
    ]
  }
}

POST/v1/checkout/process

Process payment

Process a payment for an existing checkout session. This endpoint is typically called by the hosted checkout page after the customer selects a payment method and provides their details.

Required attributes

Name
checkout_id
Type
string
Description
The checkout session ID.
Name
payment_method_code
Type
string
Description
The payment method to use: ecocash, innbucks, zimswitch, dpo, ozow.

Conditional attributes

Name
mobile_money_number
Type
string
Description
Required for ecocash and innbucks. Customer's mobile number starting with 0.

Request

POST

/v1/checkout/process

curl -X POST https://api.zuripay.app/v1/checkout/process \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "zp_chk_a1b2c3d4e5",
    "payment_method_code": "ecocash",
    "mobile_money_number": "0771234567"
  }'

Response

{
  "result": "success",
  "message": "Payment is being processed.",
  "status": "processing",
  "transaction_reference": "ZURIPAYa1b2c3d4e5"
}