Checkout - flow

The Standard Checkout integration allows you to generate a unique, secure payment URL that your customers can use to complete their transactions on the Vesicash-hosted payment page. 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.

STEPs

1. Initialize the Payment: Make a server-side POST request to the payment initialization endpoint:

2. Redirect the Customer: Upon a successful request, we’ll return a unique link for the payment page. Redirect your customer to this page to complete their payment.

3. After the Payment: Once the payment is completed, the customer will be redirected back to your provided redirectUrl. You can use this event to confirm the transaction and update your records.

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. Expected value is usually card..

• 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.

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

2. 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",
    "refence": "**************"
    "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"
}

Step 2: Redirect the Customer

Upon a successful request, we’ll return a paymentLink for the payment page.Redirect the customer to this URL in your browser or mobile app.

Response

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

Step 3: After the Payment

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

1. Customer Redirect: The customer is redirected to the redirectUrl you provided in the initialization request.

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..

3. Query Payment Status: Your server should call the Payment Status endpoint to confirm the final state of the transaction (e.g., success, failed, or pending) if webhook notifications are delayed.