Non‑Checkout Flow

The Non‑Checkout Flow allows you to collect mobile money payments without redirecting the customer to the Vesicash checkout page.

In this method, you initiate the payment from your backend and then complete it by making a direct API call using the payment reference.

This flow is ideal when you want full control of the payment experience within your website, mobile app, or custom UI.

How the Non‑Checkout Mobile Money Flow Works

1. Initialize the Payment: Make a server-side POST request to the payment initialization endpoint. Vesicash returns a paymentReference that uniquely identifies the transaction.

2. Complete the Payment: Using the paymentReference returned during initiation, your server immediately calls the Complete Payment endpoint. Vesicash will use this reference to trigger the Mobile Money push prompt on the customer’s device.

3. After the Payment: Once the payment is completed you can check the status on the status check endpoint and a webhook notification will be sent.

Step 1: Initialize the Payment

Send a server‑side POST request to the payment initialization endpoint.

POST: /v1/payment/init

Headers

Name	Type	Description
secret-key	string	Your Vesicash secret key
public-key	string	Your Vesicash public key

Request body

• currency (string): The currency for the payment.

• country (string): The country for the payment.

• narration (string): Description or reason for the payment.

• method (string): The payment method to be used.

• amount (number): The amount of the payment.

• webhook_url (string): A URL where notifications about the payment status will be sent.

• redirect_url (sting):

Request

For example, you can make a post request to the endpoint above and pass in the raw json data below to create a one-off transaction.

{
"currency": "ZMW",
    "country": "ZM",
    "narration": "payment for rice",
    "method": "mobilemoney", //"card"
    "amount": 1.3,
    "webhook_url: "",
    "redirect_url": "",
}

Response

{
    "status": "success",
    "code": 200,
    "message": "success",
    "data": {
        "payment_link": "",
        "reference": "",
        "payment_id": "",
        "status": "pending"
    }
}

Step 2: Complete the Payment

Immediately after receiving the paymentReference, your server must complete the transaction.

This call triggers the Mobile Money push prompt on the customer’s device.

POST: /v1/payment/pay/:payment_reference

Params

Name	Type	Description
payment_reference	string	The payment reference that was generated when initializing payment

Headers

Name	Type	Description
public-key	string	Your Vesicash public key

Request

{
    "account_number":"{{phone_number}}",
    "customer_first_name":"Greghh",
    "customer_last_name": "Greg",
    "phone_number":"{{phone_number}}",
    "email":"[email protected]",
    "method":"mobilemoney"

}

Response

{
    "status": "success",
    "code": 200,
    "message": "payment sent for processing",
    "data": {
        "message": "payment sent for processing",
        "device_storage_token": null,
        "method": "mobilemoney",
        "payment_status": "pending",
        "operator": "MTNGhana"
    }
}

The customer receives a Mobile Money prompt and approves the payment using their PIN.

Once approval is completed, Vesicash processes the transaction.

Step 3: After the Payment

Once the customer completes the payment on the Vesicash checkout page:

1. Query Payment Status: Your server should call the Payment Status endpoint to confirm the final state of the transaction (e.g., success, failed, pending).

2. Receive Webhook Notification: Vesicash automatically sends a webhook to your configured webhook URL whenever the transaction status changes.