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

# Quickstart

> Initiate your first M-Pesa payment in under 5 minutes.

# Quickstart

You will have a payment running in minutes. Follow the steps below.

**Prerequisites:**

* An active PalPluss API key — get one at [console.palpluss.com](https://console.palpluss.com) under **Settings → API Keys**
* Service wallet with enough balance to cover the transaction fee
* A publicly accessible HTTPS URL to receive callbacks

***

## Step 1 — Set your API key

```bash theme={null}
export PALPLUSS_API_KEY="pk_live_xxxxxxxxxxxxxxxxxxxx"
```

***

## Step 2 — Check your balance

Verify you have sufficient balance before initiating payments.

```bash theme={null}
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "$PALPLUSS_API_KEY:"
```

```json theme={null}
{
  "success": true,
  "data": {
    "currency": "KES",
    "availableBalance": 4250.00,
    "ledgerBalance": 4250.00
  }
}
```

If balance is low, [top up your service wallet](/api-reference/wallets/topup) first.

***

## Step 3 — Initiate an STK Push

Send a payment prompt to a customer's phone.

```bash theme={null}
curl -X POST https://api.palpluss.com/v1/payments/stk \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phone": "0712345678",
    "accountReference": "INV-001",
    "transactionDesc": "Payment",
    "channelId": "your-payment-channel-id",
    "callbackUrl": "https://yourserver.com/webhooks/mpesa"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "transactionId": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "status": "PENDING",
    "amount": 100,
    "currency": "KES",
    "phone": "254712345678"
  }
}
```

Save the `transactionId` — use it to track this payment.

***

## Step 4 — Handle the webhook callback

When the customer confirms or cancels, PalPluss sends a `POST` to your `callbackUrl`.

```json theme={null}
{
  "event": "transaction.updated",
  "event_type": "transaction.success",
  "transaction": {
    "id": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "status": "SUCCESS",
    "amount": 100,
    "currency": "KES",
    "phone_number": "254712345678",
    "result_code": "0",
    "result_desc": "The service request is processed successfully."
  }
}
```

Return a `2xx` status immediately. PalPluss retries failed deliveries up to 5 times.

***

## Step 5 — Poll status (optional)

Use polling as a fallback when webhooks are unavailable.

```bash theme={null}
curl https://api.palpluss.com/v1/transactions/fa98a577-95ea-4a8f-8467-1fbe74f5d6f4 \
  -u "$PALPLUSS_API_KEY:"
```

<Tip>
  Webhooks are faster and more reliable than polling. Use polling only as a backup.
</Tip>

***

## Next steps

<CardGroup cols={2}>
  <Card title="STK Push reference" icon="mobile-screen-button" href="/api-reference/stk/initiate">
    Full request and response reference.
  </Card>

  <Card title="Webhooks guide" icon="webhook" href="/guides/webhooks">
    Callback delivery, retries, and idempotent handling.
  </Card>

  <Card title="B2C Payouts" icon="money-bill-transfer" href="/api-reference/b2c/payout">
    Send money directly to customer M-Pesa numbers.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/guides/errors">
    Handle errors correctly in your integration.
  </Card>
</CardGroup>