Rechargely - Payment Gateway for Zimbabwe

Authentication

All API requests require your merchant credentials passed as HTTP headers. Generate these from the API Keys page in your merchant portal.

HTTP Headers

X-API-Key:     pk_live_your_api_key
X-API-Secret:  sk_live_your_api_secret
Content-Type:  application/json

Security: Never expose your API Secret in client-side code, mobile apps, or public repositories. Use it only from your backend server.

Checkout Widget

The fastest way to start accepting payments. Add our pre-built, customizable checkout UI to any website.

                
              <!-- Add before </body> -->
<script src="https://cdn.rechargely.co.zw/checkout.iife.js"></script>
            
              npm install @rechargely/payment-checkout

import { checkout } from '@rechargely/payment-checkout';

Basic Usage

JavaScript

PayGateway.checkout({
  // Required
  apiKey:        'pk_live_your_api_key',
  apiSecret:     'sk_live_your_api_secret',
  apiUrl:        'https://gateway.rechargely.co.zw/api/pg',
  amount:        25.00,
  currency:      'USD',
  transactionId: 'order_abc123',

  // Optional
  merchantName:  'My Store',
  description:   'Payment for Order #123',
  customerPhone: '263771234567',
  customerEmail: 'customer@example.com',
  callbackUrl:   'https://mystore.com/webhook',

  // Restrict methods (optional)
  methods: ['ECOCASH', 'VISA', 'MASTERCARD'],

  // Callbacks
  onSuccess: (result) => {
    console.log('Payment complete!', result);
    // result.transactionId, result.status, result.amount
  },
  onError: (error) => {
    console.error('Payment failed:', error);
    // error.code, error.message
  },
  onCancel: () => {
    console.log('User cancelled');
  }
});

Theming

Customize appearance

theme: {
  primaryColor: '#4F46E5',    // Your brand color
  fontFamily:   'Inter, sans-serif',
  borderRadius: '12px'
}

Configuration Reference

All available options for the checkout widget.

Parameter	Type		Description
apiKey	string	required	Your public API key.
apiSecret	string	required	Your secret API key.
apiUrl	string	required	Payment gateway API base URL.
amount	number	required	Amount to charge (e.g. 25.00).
currency	"USD" \| "ZWG"	required	Payment currency.
transactionId	string	required	Your unique order/transaction ID.
merchantName	string	optional	Displayed in the checkout header.
description	string	optional	Payment description shown to customer.
customerPhone	string	optional	Pre-fill phone for mobile money (263...).
customerEmail	string	optional	Customer email for receipts.
callbackUrl	string	optional	Webhook URL for payment notifications.
methods	string[]	optional	Restrict to specific methods, e.g. ["ECOCASH","VISA"].
theme	object	optional	Custom colors, fonts, border radius.
onSuccess	function	optional	Callback on successful payment.
onError	function	optional	Callback on payment failure.
onCancel	function	optional	Callback when customer cancels.
onStatusChange	function	optional	Called on every status poll update.

API Endpoints

Use these REST endpoints directly if you want to build your own custom checkout UI.

Base URL: https://gateway.rechargely.co.zw/api/pg

POST /v1/payments/checkout Create checkout session

Initiates a payment session. For mobile money this triggers a USSD push or returns a QR code. For cards this returns a redirect URL.

Request Body

{
  "transactionId": "order_abc123",
  "paymentMethod": "ECOCASH",
  "amount": 25.00,
  "currency": "USD",
  "customerPhone": "263771234567",
  "description": "Payment for Order #123",
  "callbackUrl": "https://mystore.com/webhook"
}

Response

{
  "success": true,
  "data": {
    "transactionRef": "order_abc123",
    "orderId": "EC-78901234",
    "message": "Checkout initiated successfully",
    "currency": "USD",
    "amount": 25.00,
    "additionalInfo": {
      "CUSTOMER_MOBILE_NUMBER": "263771234567"
    }
  },
  "timestamp": "2026-03-24T10:30:00"
}

GET /v1/payments/status Check payment status

Poll this endpoint to check the current status of a payment. Recommended interval: every 5 seconds.

Query Parameters

Name	Type		Description
transactionId	string	required	Your unique transaction ID
paymentMethod	string	required	Payment method code (e.g. ECOCASH)
externalRef	string	optional	Provider reference from checkout

Response

{
  "success": true,
  "data": {
    "transactionId": "order_abc123",
    "externalRef": "EC-78901234",
    "status": "COMPLETED",
    "amount": 25.00,
    "currency": "USD",
    "paymentMethod": "ECOCASH",
    "processedAt": "2026-03-24T10:30:05",
    "statusDescription": "Payment completed successfully"
  }
}

POST /v1/payments/refund Refund a payment

Initiate a refund for a completed payment. Not all payment methods support refunds.

Query Parameters

Name	Type		Description
transactionId	string	required	Transaction ID to refund
reason	string	required	Reason for the refund
paymentMethod	string	required	Original payment method

Response

{
  "success": true,
  "data": {
    "transactionId": "order_abc123",
    "status": "REFUNDED",
    "statusDescription": "Refund processed successfully"
  }
}

GET /v1/payments/active-methods Get active payment methods

Returns the payment methods currently enabled for your merchant account.

Response

{
  "success": true,
  "message": "Active payment methods retrieved",
  "data": ["ECOCASH", "ONEMONEY", "VISA", "MASTERCARD"]
}

GET /v1/payments/health/{paymentMethod} Check provider health

Check if a specific payment provider is currently available and operational.

Response

{
  "paymentMethod": "ECOCASH",
  "available": true
}

Webhooks

When a payment reaches a terminal status (COMPLETED, FAILED, CANCELLED, EXPIRED), we'll POST the transaction details to your callbackUrl.

Webhook Payload

{
  "transactionId": "order_abc123",
  "externalRef": "EC-78901234",
  "status": "COMPLETED",
  "amount": 25.00,
  "currency": "USD",
  "paymentMethod": "ECOCASH",
  "processedAt": "2026-03-24T10:30:05",
  "statusDescription": "Payment completed successfully"
}

Best Practices

✓ Return a 2xx response promptly. Process asynchronously if needed.

✓ Make your handler idempotent. Webhooks retry up to 5 times (every 60s).

✓ Verify server-side by calling the status endpoint before fulfilling orders.

✓ Use status polling as a fallback in case webhooks are delayed.

Payment Statuses

A payment will transition through these statuses during its lifecycle.

Status	Description	Terminal?
PENDING	Payment initiated, awaiting customer action.	No
PROCESSING	Being processed by the payment provider.	No
COMPLETED	Payment was successful.	Yes
FAILED	Payment failed. Check statusDescription for details.	Yes
CANCELLED	Cancelled by the customer.	Yes
EXPIRED	Payment timed out before completion.	Yes
REFUNDED	Payment was refunded to the customer.	Yes

Error Handling

When a request fails, the response will have success: false with error details.

{
  "success": false,
  "data": null,
  "errorCode": "ECOCASH_CHECKOUT_FAILED",
  "errorMessage": "Insufficient balance",
  "timestamp": "2026-03-24T10:30:00",
  "httpStatusCode": 400
}

Always check the success field before processing the data object. Common error codes include:

Code	Description
CHECKOUT_FAILED	The checkout could not be initiated.
NETWORK_ERROR	Could not reach the payment provider.
INVALID_PHONE	Phone number format is invalid.
INSUFFICIENT_BALANCE	Customer has insufficient funds.
TIMEOUT	Payment was not completed within the allowed time.
REFUND_FAILED	Refund could not be processed.

Accept every payment in Zimbabwe

Everything you need to get paid

One Integration

Drop-in Checkout

Secure by Default

Real-time Dashboard

Webhooks

Fully Customizable

Every way Zimbabweans pay

EcoCash

OneMoney

InnBucks

Omari

Visa

Mastercard

MPGS

ZIPIT

POS

Wallet

Start accepting payments in minutes

Create Account

Get API Keys

Add the Widget

Get Paid

Integration Guide

Authentication

Checkout Widget

Basic Usage

Theming

Configuration Reference

API Endpoints

Request Body

Response

Query Parameters

Response

Query Parameters

Response

Response

Response

Webhooks

Webhook Payload

Best Practices

Payment Statuses

Error Handling

Simple, transparent pricing

Pay as you go

Ready to start accepting payments?