Zimswitch Online Developer Documentation

Getting Started

1. Request your Merchant ID or Acquirer ID from your Zimswitch-enabled bank.
2. Download the sample code for PHP, HTML, and more.
3. Configure your credentials in auth.json.
4. Test your integration in the sandbox before going live.

Authentication & Configuration

All API requests require authentication using credentials from your auth.json file. This file contains your entityId, authorizationBearer, and endpoint URLs for each payment method.

{
  "ZIMSWITCH": {
    "entityId": "YOUR_ENTITY_ID",
    "authorizationBearer": "Bearer ...",
    "oppwaUrl": "https://gateway.zimswitch.co.zw/v1/checkouts",
    "checkoutUrl": "gateway.zimswitch.co.zw/v1/paymentWidgets.js?checkoutId=",
    ...
  },
  ...
}
                

Replace YOUR_ENTITY_ID and other values with those provided by your bank or Zimswitch.

Initiating a Payment

To start a payment, send a POST request to the oppwaUrl endpoint with your entityId, amount, currency, and paymentType:

POST /v1/checkouts
entityId=YOUR_ENTITY_ID&amount=10.00¤cy=USD&paymentType=DB
                

The response will include a checkoutId. Use this to load the payment widget in your frontend (see index.html or pay.php in the sample code):

<script src="https://gateway.zimswitch.co.zw/v1/paymentWidgets.js?checkoutId=YOUR_CHECKOUT_ID"></script>
<form action="/pay_result" class="paymentWidgets" data-brands="VISA MASTER PRIVATE_LABEL"></form>
                

Handling Payment Results

After payment, the gateway redirects to your pay_result.php (or Laravel route). Use the resourcePath parameter to query the transaction result:

GET /v1/checkouts/{checkoutId}/payment
Headers: Authorization: Bearer ...
                

Parse the response to confirm payment status and update your records. See pay_result.php in the sample code for a working example.

Multi-language Support

Sample code and SDKs are available for PHP, Python, Java, C#, and Node.js. Switch between languages in the E-Commerce Sandbox to view and download code for your stack.

E-Commerce Sandbox & Testing

Use the E-Commerce Sandbox to simulate payments and verify your integration before going live. No real funds are moved in sandbox mode.