Checkout Flow Guide

​

Overview

Afriex Checkout is a hosted payment experience that allows customers to complete payments using supported methods such as Card, Bank Transfer, and Mobile Money. After a merchant creates a checkout session through the API, the customer is redirected to the hosted checkout page to complete payment.

​

Before you begin

A checkout session must already be created by the merchant or application. The hosted checkout page displays the payment amount, available payment methods, session timer, and payment instructions.

​

Select a payment method

The customer sees the available payment methods on the checkout page. Available methods may include:

• Card
• Bank Transfer
• Mobile Money

The customer:

• Reviews the payment amount
• Selects a preferred payment method

The checkout session also displays an expiration timer. After selecting a method, the customer follows one of the payment paths below.

​

Pay by card

When Card is selected, Afriex displays a secure card payment form for the payment. The page displays:

• Amount to pay
• Card number field
• Card expiry field
• CVC field
• Cardholder name field
• Billing address fields
• Pay button

Customer actions:

1. Enter the card number.
2. Enter the card expiry date and CVC.
3. Enter the cardholder name and billing address.
4. Click Pay.
5. Complete any card authorization prompt if required.

Afriex confirms the card payment and updates the checkout page automatically.

​

Pay by bank transfer

When Bank Transfer is selected, Afriex displays one-time bank transfer details for the payment. The page displays:

• Amount to pay
• Bank name
• Account number
• Account name
• Copy account number action
• Payment instructions
• Session expiration timer

Customer actions:

1. Open a banking app, internet banking, or USSD.
2. Transfer the exact amount shown.
3. Return to the checkout page.
4. Wait for automatic payment confirmation.

​

Pay by mobile money

When Mobile Money is selected, the customer enters their mobile money details. The page displays:

• Network selector
• Account holder name field
• Mobile money phone number field
• Pay now button

Customer actions:

1. Select a mobile money network.
2. Enter the account holder name.
3. Enter the mobile money phone number.
4. Click Pay now.

Afriex sends a payment authorization prompt to the customer’s phone.

​

Approve the payment on your phone

After the customer clicks Pay now, the checkout page enters a pending state while waiting for payment authorization. The customer:

• Checks their phone
• Approves the mobile money payment prompt
• Waits for the checkout page to update automatically

The session timer continues while Afriex waits for confirmation from the network or payment provider.

​

Payment outcomes

Regardless of the payment method, the checkout session ends in one of two outcomes.

​

Successful payment

When payment is confirmed, the customer sees a success message. At this stage:

• The payment has been confirmed
• The customer sees a success confirmation
• The customer is redirected back to the merchant’s redirect URL automatically

​

Failed payment

If payment cannot be confirmed, the customer sees a failed payment screen. Possible failure reasons include:

• Declined or failed card payment
• Incorrect transfer amount
• Declined mobile money authorization
• Expired checkout session
• Network or payment provider issue
• Payment could not be confirmed

The customer may:

• Contact support
• Return to the merchant
• Retry payment if the merchant provides a new checkout session

​

Checkout session expiration

A checkout stays open for 24 hours by default. Customers should complete payment before it expires. A checkout also closes once its payment is credited, so a paid checkout can’t be opened again. If the checkout expires, the customer may need to restart checkout or request a new checkout session.

​

Redirect behavior

After a successful or failed payment, Afriex redirects the customer to the redirectUrl you set on the session, with these query parameters added: A customer can change these values, so use the redirect to show a result page, not to confirm payment. To reconcile the payment independently of the redirect, subscribe to TRANSACTION.UPDATED on the transaction the session produces. That is the event that reports payment progress and completion.

​

What the payer sees in sandbox

When a checkout session is created with a sandbox API key, the hosted page opens in test mode with a few in-page helpers so the payer can drive different outcomes without leaving the flow:

• A Test mode badge in the page header.
• On the mobile-money screen, the sandbox test numbers are listed inline (0001 fails, 0002 asks for an OTP, 0005 is declined). Any other valid mobile number succeeds.
• The OTP hint (123456) is shown whenever an OTP step is triggered.
• On the bank-transfer screen, Simulate transfer and Simulate failed transfer buttons finalize the deposit without needing to move money from a real bank.
• The card form is pre-filled with a valid test card in read-only fields, so a Pay click is enough.

These helpers only appear in sandbox; the production checkout looks identical to a real payment.

​

Notes for merchants

• Customers should pay the exact amount shown on the checkout page.
• Checkout sessions should be tested in sandbox before going live. See the Testing in Sandbox guide for the outcome-selection table (last four digits of the payer’s account, phone, or card) and how to speed up settlement.
• The redirect URL should be configured correctly so customers return to the merchant application after payment.

​

Related