# M-Pesa Paybill / Till Setup

To accept M-Pesa payments through Slade Advantage, you need an active Safaricom Paybill or Till (Buy Goods) shortcode and Daraja API credentials from the Safaricom Developer Portal.

If you already have a Paybill or Till shortcode, skip to [Step 2: Get your Daraja API credentials](#step-2-get-your-daraja-api-credentials).

---

## Step 1: Apply for a Paybill or Till

### Documents required

Have all of these ready before you apply, and note that every document must be stamped.

1. Paybill Application Form (or Till Application Form)
2. Tariff Guide
3. Account Opening Form
4. Admin Account Creation Form
5. Administrator Letter
6. Bank letter or cancelled cheque (must be signed or stamped by your bank)
7. KRA PIN Certificate
8. Copy of ID or Passport of the business owner / authorized signatory

### Application methods

**Option A: M-PESA Business Portal (recommended)**

1. Go to the [M-PESA Business Portal](https://business.safaricom.co.ke) and create or log in to your account.
2. Open the application section for Paybill or Till.
3. Upload all required documents as PDFs.
4. Submit the application.

Safaricom usually processes an application within 72 hours.

**Option B: email**

1. Compile all required documents into a single PDF.
2. Send the email to M-PESABusiness@safaricom.co.ke with a CC to paybill@safaricom.co.ke.
3. Use the subject line: `Paybill Application` or `Till Application`.
4. Include your business contact details in the email body.

Once the application is approved, Safaricom issues you a shortcode, for example `123456`. Keep it somewhere safe, because you need it when you configure Slade Advantage.

---

## Step 2: Get your Daraja API credentials

The credentials live on the Safaricom Developer Portal, and you can set them up as soon as the shortcode has been issued.

### 2.1 Create a developer account

1. Go to [https://developer.safaricom.co.ke](https://developer.safaricom.co.ke).
2. Register for a developer account using your business email address.
3. Verify your email and log in.

### 2.2 Create an app

1. In the portal, navigate to **My Apps** and click **Create App**.
2. Give the app a descriptive name (e.g., `Slade Advantage Production`).
3. Enable the APIs your integration requires:
   - **M-Pesa Express (STK Push)** starts the payment prompt.
   - **C2B** receives payments on your Paybill or Till.
   - **B2C**, which is optional, sends money out.

### 2.3 Retrieve OAuth credentials

From the app details page, copy both of these and store them somewhere safe:

| Credential | Description |
|---|---|
| **Consumer Key** | Your client ID for OAuth 2.0 authentication |
| **Consumer Secret** | Your client secret. Treat it like a password |

### 2.4 Retrieve your PassKey

- For sandbox, the PassKey sits in the portal under your test app credentials.
- For production, Safaricom emails you the PassKey once it approves your Paybill or Till application.

### 2.5 Generate a security credential (B2C / B2B only)

If your integration handles B2C or B2B transactions:

1. In **My Apps**, open the dropdown for your app and select **Test Credentials**.
2. Use the portal to generate an encrypted security credential.
3. For production, encrypt your M-Pesa API Initiator password with Safaricom's public certificate.

---

## Credentials summary

By the end of both steps you should have:

| Credential | Where to find it |
|---|---|
| **Shortcode** | Issued by Safaricom after Paybill/Till approval |
| **Consumer Key** | Safaricom Developer Portal → My Apps |
| **Consumer Secret** | Safaricom Developer Portal → My Apps |
| **PassKey** | Portal (sandbox) / Email from Safaricom (production) |
| **Security Credential** | Generated in the portal (B2C/B2B only) |

---

If something goes wrong with the application or with the credentials, Safaricom support is at M-PESABusiness@safaricom.co.ke.

---

**Additional references:**
- [Safaricom Daraja Developer Portal](https://developer.safaricom.co.ke)