> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payin/submit-a-payin/africa/mobile-money.md).

# Mobile Money

Mobile Money allows customers to pay from a mobile wallet linked to their phone number. All supported countries use the same API and request structure. Set `order_currency` according to the selected market and provide the customer's registered Mobile Money phone number in `customer.phone`.

### How It Works

1. Submit a payin request with the customer's Mobile Money phone number.
2. Redirect the customer to the URL returned in `pay_url`.
3. The customer completes the required authorization on the checkout page or mobile device.
4. Use the payment notification sent to `notify_url` as the final payment result.

### Supported Countries

| Country                          | Region code | Order currency |
| -------------------------------- | ----------- | -------------- |
| Benin                            | `BEN`       | `XOF`          |
| Burkina Faso                     | `BFA`       | `XOF`          |
| Cameroon                         | `CMR`       | `XAF`          |
| Côte d'Ivoire                    | `CIV`       | `XOF`          |
| Democratic Republic of the Congo | `COD`       | `CDF`          |
| Rwanda                           | `RWA`       | `RWF`          |
| Senegal                          | `SEN`       | `XOF`          |
| Tanzania                         | `TZA`       | `TZS`          |
| Togo                             | `TGO`       | `XOF`          |
| Uganda                           | `UGA`       | `UGX`          |
| Zambia                           | `ZMB`       | `ZMW`          |

### Submit a Payin

<mark style="color:green;">`POST`</mark> `https://gateway-test.pagsmile.com/trade/pay`

This endpoint allows you to submit a Mobile Money payin in a supported African market.

#### Headers

| Name            | Type   | Required | Constraints                                     | Description                  |
| --------------- | ------ | -------- | ----------------------------------------------- | ---------------------------- |
| `Content-Type`  | string | Yes      | Fixed value: `application/json; charset=UTF-8`. | Request content type.        |
| `Authorization` | string | Yes      | Basic Base64(`app_id:security_key`).            | Request authorization value. |

#### Request Body

| Name                   | Type    | Required    | Constraints                                                                                                                           | Description                                                                      |
| ---------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `app_id`               | string  | Yes         | Use the App ID assigned by Pagsmile.                                                                                                  | Merchant application ID.                                                         |
| `out_trade_no`         | string  | Yes         | Maximum length: 64 characters. Must be unique for the merchant application.                                                           | Merchant order number.                                                           |
| `method`               | string  | Yes         | Fixed value: `MOBILEMONEY`.                                                                                                           | Payment method.                                                                  |
| `order_amount`         | decimal | Yes         | Must be greater than zero and contain no more than two decimal places.                                                                | Payment amount in the currency specified by `order_currency`.                    |
| `order_currency`       | string  | Yes         | Three-letter currency code. Use the currency assigned to the selected country in the supported-country table.                         | Payment currency.                                                                |
| `subject`              | string  | Yes         | Maximum length: 128 characters.                                                                                                       | Payment reason or order title.                                                   |
| `content`              | string  | No          | Maximum length: 255 characters.                                                                                                       | Payment or order details.                                                        |
| `notify_url`           | string  | Yes         | Must not be empty. Use an HTTPS URL in production.                                                                                    | Merchant endpoint that receives payment result notifications.                    |
| `return_url`           | string  | No          | Must be a valid merchant URL when provided.                                                                                           | URL to which the customer is redirected after checkout.                          |
| `buyer_id`             | string  | Yes         | Maximum length: 128 characters.                                                                                                       | Merchant-defined customer ID.                                                    |
| `timestamp`            | string  | Yes         | Format: `yyyy-MM-dd HH:mm:ss`.                                                                                                        | Time when the request is submitted.                                              |
| `version`              | string  | No          | Fixed value: `2.0`. Defaults to `2.0` when omitted.                                                                                   | API version.                                                                     |
| `region`               | string  | Conditional | Required when using a Global App. Use the ISO 3166-1 alpha-3 region code shown in the supported-country table.                        | Country or region in which the payment is processed.                             |
| `customer.phone`       | string  | Yes         | Provide the phone number registered with the customer's Mobile Money account, including the country calling code.                     | Customer's Mobile Money account number.                                          |
| `timeout_express`      | string  | No          | Supports minutes (`m`), hours (`h`), days (`d`), or end of day (`c`). The effective value is limited to between 1 minute and 15 days. | Period for which the payin request remains available.                            |
| `cancellation_express` | string  | No          | Use a positive number followed by `m`, `h`, or `d`. The effective automatic-cancellation interval does not exceed 3 days.             | Period after which a processing order is automatically cancelled, if applicable. |

#### &#x20;Request Sample

The following example submits a Mobile Money payin in Benin. For another market, update `region`, `order_currency`, and `customer.phone` according to the supported-country table.

```json
{
  "app_id": "17***150",
  "out_trade_no": "out_t***16",
  "method": "MOBILEMONEY",
  "order_amount": "5",
  "order_currency": "XOF",
  "subject": "Mobile Money payin",
  "content": "Mobile Money payin request",
  "notify_url": "https://merchant.example.com/payment/notify",
  "return_url": "https://merchant.example.com/payment/return",
  "buyer_id": "buyer_22_041302",
  "timestamp": "2026-10-23 09:42:17",
  "version": "2.0",
  "region": "BEN",
  "timeout_express": "15d",
  "cancellation_express": "3d",
  "customer": {
    "phone": "229********"
  }
}
```

#### Response Sample

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "QnE***c5",
  "trade_no": "2026***5",
  "out_trade_no": "out_t***16",
  "web_url": "",
  "pay_url": "https://checkout.pagsmile.com/checkout?prepay_id=QnE***c5",
  "trade_status": "PROCESSING",
  "due_date": "2026-10-23 09:57:17"
}
```

Redirect the customer to `pay_url` to complete the payment.

{% hint style="warning" %}
A successful API response means that the payin request has been accepted for processing. It does not mean that the payment has been completed. Use the notification sent to `notify_url` or the Payin Detail API to determine the final payment result.
{% endhint %}

#### Error Response Sample

```json
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "duplicate-out_trade_no",
  "sub_msg": "out_trade_no is duplicate"
}
```
