Non‑Checkout Flow

The Non‑Checkout Flow for card payments allows you to process card transactions directly through your backend without redirecting the customer to the Alexpay Standard Checkout page. This flow is ideal for merchants who want full control of the payment experience in a web application, mobile app, or custom UI.

How the Card Non‑Checkout Flow Works

1. Initialize the Payment: Make a server-side POST request to the payment initialization endpoint. Alexpay 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 triggers the 3D Secure (3DS) authentication flow, where the customer is redirected to their issuer bank’s verification page.

3. After 3DS Authentication: Once the customer authorizes or declines the transaction:

• You query the status endpoint, and/or

• Alexpay sends a webhook notification with the final transaction status.

Step 1: Initialize the Payment

Send a server‑side POST request to create the card payment.

POST /v1/payment/init

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

{
    "amount":120,
    "country":"GH",
    "currency":"GHS",
    "method":"card",
    "narration":"Test Narration",
    "operator":"mpgs",
    "redirect_success_url":"https://alexpay-mpgs.vercel.app/api/confirm",
    "redirect_failed_url":"https://alexpay-mpgs.vercel.app/api/failed",
    "webhook_url":"{{webhook_url}}",
    "integration_type":"DIRECT_API"
}

Request body

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

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

• currency (string): The currency for the payment

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

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

• operator (string): mpgs — Mastercard Payment Gateway Services.

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

• redirect_success_url / redirect_failed_url(string): Customers are redirected here after payment.

• integration_type(string): DIRECT_API — tells the system this is a backend-driven integration, not a hosted checkout-only flow.

• Response

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

Step 2: Complete the Payment

Immediately after receiving the payment_reference, call the Complete Payment endpoint.

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 Alexpay public-key

Request

For card payments using the Non‑Checkout Flow, you must collect and send device information required for 3D Secure (3DS) authentication.

This allows Alexpay to initiate a frictionless or challenge‑based 3DS flow with the card issuer.

Below is the sample payload your backend should submit, along with the response you may receive when a 3DS Challenge is required.

{
    "phone_number": "233551234567",
    "email": "[email protected]",
    "customer_first_name": "Jane",
    "customer_last_name": "Doe",
    "card_number": "530000000000000",
    "card_expiry_date": "0629",
    "card_cvv": "428",
    "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"
}

• card_number / expiry / cvv: Raw card details for initial authorization and 3DS enrollment.

• device + browser details: Required by EMV 3DS to determine risk level and trigger frictionless or challenge flow.

• ip_address: Must be the customer’s IP, not your server IP.

• language: For localization of issuer page.

• java_enabled: Whether Java is enabled in browser (3DS requirement).

Response

If the card issuer requires additional authentication, Alexpay returns a Challenge Required response containing a 3DS device storage token and challenge data.

{
    "status": "success",
    "code": 200,
    "message": "3DS Challenge Required",
    "data": {
        "message": "3DS Challenge Required",
        "device_storage_token": {
            "methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F**************nYXRld2F5Lm1hc3RlcmNhcmQuY29tL2NhbGxiYWNrSW50ZXJmYWNlL2dhdGV3YXkvY2FhMGNlNWY4NmE1YjJlNmE2OThkZDgxMDgwZGQ1NmZjYmQxNzNkNzU5M2VhMzYxZjBmNWY2ZDQ3YWNhYjc5NSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiN2U3ODRlNWYtYzMyMy00ZGRlLWE4YTMtNGFhNTJhYWU5OGZhIn0=",
            "methodUrl": "https://secure-acs2ui-b1.wibmo.com/v1/acs/services/threeDSMethod/8528?cardType=M"
        },
        "method": "",
        "payment_status": "challenge_required",
        "operator": ""
    }
}

• device_storage_token: Contains encoded data the issuer (ACS) needs to perform the 3DS method. methodPostData – Encoded payload your frontend must POST to the ACS Method URL. methodUrl – URL where the browser must submit the 3DS method data.

• payment_status: "challenge_required":

  Indicates that the customer must complete a 3D Secure Challenge, such as:

  • entering an OTP

  • approving via banking app

  • biometric confirmation

Step 3: After the Payment

Once the customer completes the 3DS authentication:

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: Alexpay automatically sends a webhook to your configured webhook URL whenever the transaction status changes.