> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Flow Guide

> Step-by-step guide for the hosted Afriex Checkout payment experience

<Warning>
  **Coming soon.** Hosted checkout is not yet generally available in production, but you can already try it end-to-end in the **sandbox/staging** environment today. Use sandbox to validate your integration while we finish the production rollout, which we expect to ship in the coming weeks.
</Warning>

## 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](/api-reference/endpoint/checkout-sessions/create) 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

<Frame caption="Afriex Checkout payment method selection screen">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/payment-select.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=44453a6664820baabcc7d84edfdde7f1" alt="Afriex Checkout payment method selection screen" width="1351" height="1164" data-path="images/checkout-flow/payment-select.png" />
</Frame>

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.

<Frame caption="Afriex Checkout card payment form">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/card-payment.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=aaf81047e4a9c1f0accd0baa0075d0ed" alt="Afriex Checkout card payment form" width="1126" height="1397" data-path="images/checkout-flow/card-payment.png" />
</Frame>

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.

<Frame caption="Afriex Checkout bank transfer payment details screen">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/bank-transfer.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=efcc3f86abd430e43b0fddd82ba7c00d" alt="Afriex Checkout bank transfer payment details screen" width="1310" height="1200" data-path="images/checkout-flow/bank-transfer.png" />
</Frame>

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.

<Warning>
  The customer must send the exact amount shown. Incorrect amounts may cause delays or require a refund.
</Warning>

## Pay by mobile money

When Mobile Money is selected, the customer enters their mobile money details.

<Frame caption="Afriex Checkout mobile money payment form">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/mobile-money.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=699e56ee11ea2c43feef5ed3b07a239d" alt="Afriex Checkout mobile money payment form" width="1307" height="1203" data-path="images/checkout-flow/mobile-money.png" />
</Frame>

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.

<Frame caption="Afriex Checkout mobile money authorization pending screen">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/check-phone.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=e5036251afa155739f33b02c66c12c8f" alt="Afriex Checkout mobile money authorization pending screen" width="1417" height="1110" data-path="images/checkout-flow/check-phone.png" />
</Frame>

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.

<Frame caption="Afriex Checkout payment successful confirmation screen">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/payment-success.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=861833437becc180ee6eac5f43584004" alt="Afriex Checkout payment successful confirmation screen" width="1393" height="1129" data-path="images/checkout-flow/payment-success.png" />
</Frame>

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.

<Frame caption="Afriex Checkout payment failed screen">
  <img src="https://mintcdn.com/afriex-5d97ad2e/ulv7qvmC5TFs2ZRr/images/checkout-flow/payment-failed.png?fit=max&auto=format&n=ulv7qvmC5TFs2ZRr&q=85&s=44f42e2a76b2f3bede8eb40c5928f994" alt="Afriex Checkout payment failed screen" width="1398" height="1125" data-path="images/checkout-flow/payment-failed.png" />
</Frame>

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

Checkout sessions have an expiration timer. Customers should complete payment before the session expires.

If the session 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 back to the merchant application depending on the checkout configuration.

When payment is confirmed, Afriex also fires a `CHECKOUT_SESSION.CREATED` [webhook](/api-reference/endpoint/webhooks/introduction) to your configured callback URL, so your system can reconcile the payment independently of the redirect.

## Notes for merchants

* Customers should pay the exact amount shown on the checkout page.
* Checkout sessions should be tested in sandbox before going live.
* The redirect URL should be configured correctly so customers return to the merchant application after payment.

## Related

<CardGroup cols={2}>
  <Card title="Create Checkout Session" icon="plus" href="/api-reference/endpoint/checkout-sessions/create">
    Create a hosted checkout session and get the `checkoutUrl` to redirect your customer to.
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/endpoint/webhooks/introduction">
    Receive real-time notifications when a checkout session is completed.
  </Card>
</CardGroup>
