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

# Quickstart

> Take your first test payment with the PrimePay sandbox API.

This guide takes a mobile money payment in the sandbox: you ask a customer's number to pay, then check the result. It uses `curl`, so there is nothing to install.

## Before you begin

* A PrimePay account. Sign up on the [dashboard](https://dashboard.primepay.mw/).
* A **test secret key** (`sk_test_…`) from your account's API keys page.
* A **webhook endpoint** added under **Settings › Webhooks**: a public `https://` address on your server where PrimePay sends payment results. A payment is refused with `webhook_url_required` until you have one.

> [!NOTE]
>
> Keep secret keys on your server. Never put one in a mobile app, a web page or a public repository.

## Take a test payment

**1. List the operators**

Each mobile money operator has an id. You send that id as `provider` when you create a payment.

```bash theme={null}
curl "https://sandbox-api.primepay.mw/mobile-money/operators?country=MW" \
  -H "Authorization: Bearer sk_test_..."
```

Copy the `refId` of Airtel Money or TNM Mpamba from the response.

**2. Create the payment**

Send the amount, the customer's number, the operator and your own order number. The `Idempotency-Key` makes a retry safe: the same key never charges twice.

```bash theme={null}
curl -X POST "https://sandbox-api.primepay.mw/v1/payments/mobile-money" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: 6f1c2b9e8a6d4c1f9b0e3a7d5c2f8e10" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "MWK",
    "customerPhone": "+265991234567",
    "provider": "PASTE-THE-OPERATOR-REFID",
    "merchantOrderId": "ORDER-5531"
  }'
```

You get `202 Accepted` with a `reference` and `"status": "processing"`. On the live API the customer now sees a PIN prompt on their phone. In the sandbox any number pays, and the payment finishes on its own about 3 seconds later.

**3. Check the result**

Use the `reference` from the last step.

```bash theme={null}
curl "https://sandbox-api.primepay.mw/v1/payments/TXN-WRYF6S2W3DQW" \
  -H "Authorization: Bearer sk_test_..."
```

When `status` is `success`, the payment is complete and you can hand over the goods.

> [!WARNING]
>
> Never treat a timeout or an error as a failed payment. Check the payment's status, or wait for the webhook, before you decide.

## Next steps

> [card] [Payments](https://docs.primepay.mw/api-reference/payments-overview.md)
>
> Every field, the payment statuses and refunds.

> [card] [Webhooks](https://docs.primepay.mw/api-reference/webhooks.md)
>
> Receive results and check their signature.

> [card] [Testing in sandbox](https://docs.primepay.mw/api-reference/sandbox.md)
>
> What the sandbox does and doesn't cover.

> [card] [Payment links](https://docs.primepay.mw/api-reference/payment-links-overview.md)
>
> Take payments without building a checkout.

Need help? Visit [primepay.mw/help](https://primepay.mw/help).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.