Non‑Checkout Flow

The Non‑Checkout Flow allows you to recieve card 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.

The flow supports two active operators depending on the currency of the transaction.

1. GTI - Exclusively for USD payments.

2. MPGS - Exclusively for GHS payments.

How the Non‑Checkout Card payment 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. This returns a bank card payment link. Load this link and the customer will complete the transaction.

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.

• reference (string, optional): Transaction reference. If not supplied, the system will internally generate a value. Must be at least 10 characters long.

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

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

• operator(string): The payment gateway operator to use. Expected values are gti or mpgs.

• redirect_success_url(string): The absolute URL where the user will be redirected to upon a successful payment.

• redirect_failed_url(string):The absolute URL where the user will be redirected to if the payment fails.

• integration_type(string): Required when operator is mpgs. The expected value is DIRECT_API.

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

Request

1. GTI (USD Payments)

The GTI operator is strictly used for payments in USD.

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.

{
    "amount": 1,
    "currency": "USD",
    "country": "US",
    "method": "card",
    "operator": "gti",
    "narration": "Checkout GTI Test",
    "reference": "***********"
    "redirect_success_url": "https://www.yourdomain.com/success",
    "redirect_failed_url": "https://merchant.yourdomain.com/login",
    "webhook_url": "https://api.yourdomain.com/webhooks/checkout"
}

1. MPGS (GHS Payments)

The MPGS operator is used for payments in GHS. Notice the inclusion of the integration_type attribute.

{
    "amount": 1,
    "country": "GH",
    "currency": "GHS",
    "method": "card",
    "narration": "Test Narration",
    "reference": "*************"
    "operator": "mpgs",
    "redirect_success_url": "https://alexpay-mpgs.yourdomain.app/api/confirm",
    "redirect_failed_url": "https://alexpay-mpgs.yourdomain.app/api/failed",
    "webhook_url": "https://api.yourdomain.com/webhooks/checkout",
    "integration_type": "DIRECT_API"
}

Response

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

Step 2: Complete the Payment

Using the paymentReference returned during initiation, your server immediately calls the Complete Payment endpoint. This returns a bank card payment link. Load this link and the customer will complete the transaction

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

1. GTI Payload Requirements

The GTI operator requires basic card details, standard billing information, and redirect URLs to handle the payment outcome.

{
    "card_number": "5399839213647612",
    "card_cvv": "208",
    "card_expiry_date": "0929",
    "email": "[e-mail]",
    "phone_number": "[phone]",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "method": "card",
    "operator": "gti",
    "billing_address_line1": "123 Business Way",
    "billing_city": "Lagos",
    "billing_province": "Lagos",
    "billing_postal_code": "100001",
    "billing_country": "NG",
    "redirect_url": "https://google.com",
    "redirect_success_url": "https://www.google.com/",
    "redirect_failed_url": "https://merchant.vesicash.com/login"
}

1. MPGS Payload Requirements

The MPGS operator requires detailed client metadata and network info (likely for 3D Secure verification) but excludes the billing and redirection information found in the GTI payload.

{
    "phone_number": "111111111",
    "email": "[e-mail]",
    "customer_first_name": "Jane",
    "customer_last_name": "Doe",
    "card_number": "111111111111111111",
    "card_expiry_date": "0629",
    "card_cvv": "222",
    "java_enabled": false,
    "language": "en-GB",
    "screen_height": 1080,
    "screen_width": 1920,
    "color_depth": 24,
    "time_zone": -60,
    "ip_address": "{{clientIPAddress}}",
    "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36"
}

Response

{
    "status": "success",
    "code": 200,
    "message": "Success. Redirect to 3DS.",
    "data": {
        "message": "Success. Redirect to 3DS.",
        "device_storage_token": null,
        "method": "card",
        "payment_status": "processing",
        "operator": "gti",
        "reference": "",
        "redirect_url": "https://checkout.gtipayglobal.com/checkout//mp"
    }
}

Then load the payment link provided in the response, allowing the customer to authorize the card payment.

Once approval is completed, Vesicash processes the transaction.

Step 3: After the Payment

Once the customer completes the payment on the bank 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 webhook notifications to your configured URL whenever a transaction status changes, provided your webhook secret is properly generated and verified.

Webhook Notification

Once the payment is processed, Vesicash sends a POST request to your webhook_url with the final payment outcome. Use this event — not the initial API response — to update your system's payments state.

{
"amount":1,
"business_id":"56b2f01d-75e4-46e4-b8ec-c79441844001",
"charge":0,"created_at":"2026-04-30T16:46:23.060208Z",
"currency":"ZMW",
"customer":
{
"id":"690bf0df-d187-42a8-9137-dc7402f2d080",
"email":"[e-mail]",
"phone_number":"260968832801",
"firstname":"Ademola",
"environment":"live",
"lastname":"Ayeola",
"details":null,
"business_id":"56b2f01d-75e4-46e4-b8ec-c79441844001",
"blacklisted":false,
"no_payments":34,
"last_payment":"2026-04-30T16:46:23.060208Z",
"created_at":"2025-12-04T10:03:47.870978Z",
"updated_at":"2026-04-30T16:46:35.914213Z"
},
"environment":"live","event":"payment_successful","id":"99c6bf3a-4092-4dad-bf32-22ab3cb394e3","method":"mobilemoney","narration":"payment for the purchase of seven doors","provider_transaction_id":"99c6bf3a-4092-4dad-bf32-22ab3cb394e3","redirect_url":"https://www.google.com","reference":"PY_VM_08c04dac73","status":"successful","type":"payment"}