> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/collections/server-to-server-integration-overview/s2s-mobile-money.md).

# S2S — Mobile Money

Initialize a mobile-money collection through the server-to-server API.

See [Authentication](/startbutton-product-api/getting-started/authentication.md) before making requests.

### Endpoint

`POST /transaction/initialize/s2s/mobile_money`

### Headers

| Header        | Value               |
| ------------- | ------------------- |
| Authorization | `Bearer PUBLIC_KEY` |
| Content-Type  | `application/json`  |

To test this flow in sandbox, see [Test Numbers for Collections](/startbutton-product-api/testing/test-numbers-for-collections.md).

{% tabs %}
{% tab title="KES and GHS" %}
For KES, use `MPESA` as `provider`.

```json
{
  "provider": "mpesa",
  "phone": "+254710000000",
  "email": "kass1-pms@customer.com",
  "amount": 3000,
  "currency": "KES"
}
```

For GHS, use `MTN`, `ATL`, or `VOD` as `provider`.

```json
{
  "provider": "MTN",
  "phone": "0551234987",
  "amount": 300000,
  "currency": "GHS",
  "email": "test-pms@customer.com"
}
```

Optional parameters included (KES):

```json
{ 
    "provider": "mpesa", 
    "phone": "+254710000000", 
    "email": "kass1-pms@customer.com", 
    "amount": 3000, 
    "currency": "KES", 
    "reference": "de432cr4d34e" // this is an optional field
}
```

Optional parameters included (GHS):

```json
{ 
    "provider": "MTN", 
    "phone": "0551234987", 
    "amount": 300000, 
    "currency": "GHS", 
    "reference": "de432cr4d34e", 
    "email": "test-pms@customer.com" //this is an optional field
}
```

{% endtab %}

{% tab title="TZS and UGX" %}
TZS:

```json
{ 
    "phone": "+255121212121", 
    "email": "johndoe@startbutton.africa", 
    "amount": 12000, 
    "currency": "TZS", 
    "reference": "765jhgfyt6" //optional
}
```

To mock a failed Scenario (TZS):

```json
{ 
    "phone": "+255750000020", 
    "email": "johndoe@startbutton.africa", 
    "amount": 12000, 
    "currency": "TZS" 
}
```

UGX:

```json
{ 
    "phone": "+256101010111", 
    "email": "johndoe@startbutton.africa", 
    "amount": 120000, 
    "currency": "UGX", 
    "reference": "jhgfdew4567" // optional
}
```

Failed Scenario (UGX):

```json
{ 
    "phone": "+256760000010", 
    "email": "johndoe@startbutton.africa", 
    "amount": 120000, 
    "currency": "UGX" 
}
```

| Currency     | Minimum | Maximum     |
| ------------ | ------- | ----------- |
| TZS          | `20000` | `300000000` |
| UGX          | `50000` | `500000000` |
| {% endtab %} |         |             |

{% tab title="RWF" %}
Use `MTN` or Airtel as the provider.

Optional parameters:

```json
{ 
    "provider": "MTN", 
    "phone": "250785283918", 
    "amount": 2000, 
    "email": "RWF-momo-test@customer.com", 
    "currency": "RWF", 
    "reference": "eybr34muxk" //optional
}
```

To simulate a failed scenario:

```json
{ 
    "provider": "MTN", 
    "phone": "740000030", 
    "amount": 2000, 
    "email": "RWF-momo-test@customer.com", 
    "currency": "RWF" 
}
```

{% endtab %}

{% tab title="XOF" %}

#### XOF: Supported Countries & Providers

XOF is shared by several countries, each with its own supported providers. Always send `"currency": "XOF"`. The country is identified by the provider code, whose suffix is the country code (for example `_SN` for Senegal), and by the dialing code on the customer's phone number.

| Country       | Dialing code | Provider | `provider` value |
| ------------- | ------------ | -------- | ---------------- |
| Benin         | +229         | Moov     | `MOOV_BJ`        |
|               |              | MTN      | `MTN_BJ`         |
| Côte d'Ivoire | +225         | Moov     | `MOOV_CI`        |
|               |              | MTN      | `MTN_CI`         |
|               |              | Orange   | `ORANGE_CI`      |
|               |              | Wave     | `WAVE_CI`        |
| Mali          | +223         | Orange   | `ORANGE_ML`      |
|               |              | Moov     | `MOOV_ML`        |
| Senegal       | +221         | Expresso | `EXPRESSO_SN`    |
|               |              | Wave     | `WAVE_SN`        |
|               |              | Orange   | `ORANGE_SN`      |
|               |              | Free     | `FREE_SN`        |
| Burkina Faso  | +226         | Moov     | `MOOV_BF`        |
|               |              | Orange   | `ORANGE_BF`      |
|               |              | Wave     | `WAVE_BF`        |

**Sample request:**\
\
Côte d'Ivoire (**CI**)

```json
{
  "provider": "WAVE_CI",
  "phone": "+2250111111111",
  "amount": 25000,
  "currency": "XOF",
  "email": "xof-pms@customer.com"
}
```

| Currency     | Minimum | Maximum     |
| ------------ | ------- | ----------- |
| XOF          | `20000` | `150000000` |
| {% endtab %} |         |             |

{% tab title="XAF" %}

```
{
  "phone": "+2370707000200",
  "amount": 50000,
  "email": "xaf-momo-test@customer.com",
  "currency": "XAF"
}
```

| Currency      | Minimum | Maximum     |
| ------------- | ------- | ----------- |
| XAF           | `20000` | `150000000` |
| {% endtab %}  |         |             |
| {% endtabs %} |         |             |

### Sample responses

<details>

<summary>GHS, KES, and TZS</summary>

#### GHS

```json
{ 
    "success": true, 
    "message": "Charge attempted, requery to get status", 
    "data": { 
        "nextStep": "PIN", 
        "reference": "610ae86889ee" 
    } 
}
```

#### KES

```json
{ 
    "success": true, 
    "message": "Charge attempted, requery to get status", 
    "data": { 
        "nextStep": "PIN", 
        "reference": "42452be51db0" 
    } 
}
```

```json
{ 
    "success": false, 
    "message": "unknown provider" 
}
```

#### TZS

```json
{ 
    "success": true, 
    "message": "Payment initiated successfully!", 
    "data": { 
        "reference": "ffeaf8d13f71", 
        "nextStep": "PIN" 
    }
}
```

</details>

<details>

<summary>UGX, RWF, and XOF/XAF</summary>

#### UGX

```json
{ 
    "success": true, 
    "message": "Payment initiated successfully!", 
    "data": { 
        "reference": "ccefb5efd193", 
        "nextStep": "PIN" 
    }
}
```

```json
{ 
    "success": false, 
    "message": "unknown provider" 
}
```

#### RWF

```json
{ 
    "success": true, 
    "message": "Payment Request Successful", 
    "data": { 
        "reference": "a76b2d362692", 
        "nextStep": "PIN" 
    } 
}
```

```json
{ 
    "success": false, 
    "message": "Payment failed", 
    "data": {} 
}
```

#### XOF/XAF

```json
{ 
    "success": true, 
    "message": "Payment Request Successful", 
    "data": { 
        "reference": "cc7f3971826e", 
        "nextStep": "PIN" 
    } 
}
```

```json
{ 
    "success": true, 
    "message": "Payment Request Successful", 
    "data": { 
        "reference": "a0bxxxxxxxxe", 
        "nextStep": "UOTP", 
        "meta": { 
            "beforePaymentInstruction": "<p>How to Pay</p>\n<ol><li><b>Generate Voucher/OTP:</b> Dial <b>*144*82#</b> using your mobile number 2250111111111 to receive an OTP/Voucher.</li><li><b>Submit Voucher/OTP:</b> Enter the code in the input field below to proceed with your payment.</li></ol>" 
        } 
    } 
}
```

```json
{ 
    "success": true, 
    "message": "Payment Request Successful", 
    "data": { 
        "reference": "82XXXXXXXX07", 
        "nextStep": "URL", 
        "paymentUrl": "https://pay.wave.com/c/cos-24tfdam1g1pb6?a=250&c=XOF&m=point%20touch%20%2A%20Into", 
        "meta": {} 
    } 
}
```

```json
{ 
    "success": false, 
    "message": "Failed to process payment request" 
}
```

</details>

{% hint style="info" %}
Next step: [OTP Verify](/startbutton-product-api/collections/server-to-server-integration-overview/s2s-mobile-money/otp-verify.md)
{% endhint %}

Amounts use fractional units.

See [Test Numbers for Collections](/startbutton-product-api/testing/test-numbers-for-collections.md) for sandbox scenarios.