The Checkout Integration Lifecycle

1. Setup Core Routes: Define your default global return destination paths inside the Astragate Merchant Portal.
2. Initialize Intent: Your backend server passes order parameters (lineItems, currency, correlatorId) to generate a unique checkout token instance.
3. Transition the Client: Send the custom checkoutUrl to your frontend application to securely transition the client context onto our interface.
4. Authorize Settlement: The customer initiates payment processing securely via mobile operator protocols or Card instruments.
5. Dynamic Return Redirect: Astragate auto-forwards the response back to your portal loop with explicit transactional state payloads appended URL parameters.

API Reference

Create Checkout Session

POST

https://api.dev.astragate.africa/v1/payment/checkout-sessions

Securely generates an isolated checkout session context token payload.

Headers

Request Payload Body (application/json)

{
  "lineItems": [
    {
      "itemId": "prod_9018",
      "name": "Premium Plan Subscription",
      "quantity": 1,
      "unitPrice": 250.00
    }
  ],
  "currency": "ZMW",
  "correlatorId": "invoice_zmw_7781290",
  "description": "Astragate API Core Access Provisioning Billing",
  "paymentMode": "CARD",
  "metadata": {
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+260970000000",
  }
}

Fields Reference

• lineItems [Array] *Required — A itemized break-down stack representing the components constituting the cart balance checkout loop.

• currency String *Required — The ISO currency format tracker symbol representing base invoice rules. Supported target market variables include ZMW (Zambian Kwacha).

• correlatorId String *Required — A unique, internal checkout session reference ID key generated on your framework to trace mapping indexes.

• paymentMode String Optional — Specifies the preferred payment method to display on the hosted checkout.

  Accepted values: "CARD" or "MOBILE_MOBILE".

  • When "CARD" is provided, only the card payment option is shown.
  • When "MOBILE_MOBILE" is provided, only the mobile money option is shown.
  • [Default] If omitted or left empty, both Card and Mobile Money payment options are displayed.

• metadata [Object] Optional — A collection of key-value pairs used to store custom contextual data or integration state metrics.

  • To optimize user experience by automatically pre-populate fields on the Astragate hosted checkout, include customer_name and customer_email.

  Important Pre-population Notes:

  Casing is Strict: Object keys inside metadata are case-sensitive. You must use exact snake_case parameters (customer_name and customer_email) for pre-population to successfully map to the checkout fields.

  Phone Number Exception: Even if customer_phone is passed in the metadata array, it will not be pre-populated on the hosted checkout page. This intentional barrier requires the payer to manually enter or verify their mobile money number to prevent accidental or incorrect carrier billing selections.

API Session Response Matrix

Upon processing checkout requirements parameters, the API endpoint responds with standard session payload tokens.

Response Object (200 OK)

{
  "success": true,
  "message": "SUCCESS",
  "statusCode": 200,
  "data": {
    "checkoutUrl": "https://checkout.dev.astragate.africa/r/checkout?session=agt-cs_fImYVh5yVhoHUhk9W1YX3Ie3VSKtYp",
    "sessionId": "agt-cs_fImYVh5yVhoHUhk9W1YX3Ie3VSKtYp",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5VkM5..."
  }
}

Execution Guide Implementation Step-through

Step 1: How to Redirect the Customer to Checkout

After you successfully create a checkout session, the API returns a checkoutUrl and a token.
Redirect the customer like this:

if (apiResponse.success && apiResponse.data) {
  const { checkoutUrl, token } = apiResponse.data;

  // Add the token to the checkout URL
  const url = new URL(checkoutUrl);
  url.searchParams.append('token', token);

  // Redirect the customer
  window.location.href = url.toString();
} else {
  console.error("Failed to start checkout session");
}

Important:

The token is required for the checkout session to work. Always append it to the checkoutUrl before redirecting the customer. Without the token, the payment page will not load correctly.

Step 2: In-flight Processing Redirect Hook

• Once processing flows finalize over either Mobile Money wallets or Cards, the system automatically redirects customer using your pre-configured Merchant Portal base URL targets, appending key validation tracking matrices straight into the browser query params context:
  HTTP
  https://yourmerchantwebsite.com/callback/checkout-success?correlatorId=SO004

Testing Payments

This section explains how to test card and mobile money payments in the Astragate payment gateway.

Card Payment Testing

When testing card payments, complete the payment form using the following details:

Test Card

Use the following card number for successful test transactions:

Card Number: 4111 1111 1111 1111

Note: Any values may be used for the First Name, Last Name, Phone Number, Expiry Date, and CVV required fields during testing.

Mobile Money Testing

When testing mobile money payments, complete the payment form using the following details:

Note: Any values may be used for the First Name, Last Name, and Mobile Money Number required fields during testing.