# Quickstart

Collect KES 10 from your own M-Pesa number and watch it land in your Payd account. It takes about ten minutes.

You need a Payd account, a Kenyan M-Pesa number, and a terminal with `curl`. Every request moves real money, so keep to small amounts.

## 1. Create an API key

In the [Payd app](https://app.payd.money), open **Settings**, then **API keys**, and create a key. Copy the **username** and **password**. Payd shows the password only once.

Keep both in environment variables on your server:

```bash
export PAYD_API_USERNAME="your_key_username"
export PAYD_API_PASSWORD="your_key_password"
```

## 2. Find your account id

Payins and payouts name the Payd account they belong to. Ask Payd for the account your key is linked to:

```bash
curl https://api.payd.money/api/v2/api_keys/$PAYD_API_USERNAME \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"
```

```json
{
  "api_key": {
    "account_id": "4f28836c-2f1e-4d9b-9a51-6f3c2b1d8e70",
    "name": "Online shop",
    "username": "your_key_username"
  }
}
```

Save `account_id`:

```bash
export PAYD_ACCOUNT_ID="4f28836c-2f1e-4d9b-9a51-6f3c2b1d8e70"
```

## 3. Get a webhook URL

Payd posts the result of each payment to a URL you choose. For this test, open [webhook.site](https://webhook.site) and copy your unique URL. In production, use an HTTPS endpoint on your own server.

## 4. Send the payment prompt

Replace the phone number with your own, in the form `2547XXXXXXXX`:

```bash
curl https://api.payd.money/api/v2/payments/payin \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "currency": "KES",
    "country": "KE",
    "transaction_channel": "mobile",
    "customer": {
      "first_name": "Amina",
      "last_name": "Wanjiru",
      "phone_number": "254712345678"
    },
    "vendor_config": { "account_id": "'"$PAYD_ACCOUNT_ID"'" },
    "provider_config": {},
    "payment_config": {
      "account_number": "254712345678",
      "remark": "Quickstart test",
      "reference": "quickstart-001",
      "callback_url": "https://webhook.site/your-unique-id"
    }
  }'
```

Payd answers within a few seconds:

```json
{
  "gateway_response": {
    "success": true,
    "merchant_reference": "9BD103350408eR",
    "checkout_request_id": "7c1e9a52d4b8"
  }
}
```

The response has more fields than shown here. [How payments work](./core-concepts.md#reading-responses) explains which ones to rely on.

Your phone shows an M-Pesa prompt. Enter your PIN to pay. Keep the `merchant_reference`: it is how you look the payment up.

## 5. Confirm the payment

After you approve the prompt, your webhook URL receives a `POST` like this:

```json
{
  "success": true,
  "status": "success",
  "reference": "9BD103350408eR",
  "external_reference": "quickstart-001",
  "amount": 10,
  "currency": "KES",
  "transaction_type": "receipt",
  "transaction_date": "2026-10-16T11:42:03Z",
  "message": "transaction processed successfully"
}
```

Then ask Payd directly, which is how you should confirm every payment in production:

```bash
curl https://api.payd.money/api/v2/payments/9BD103350408eR/status \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"
```

```json
{
  "success": true,
  "status": "success",
  "transaction_ref": "9BD103350408eR",
  "amount": 10,
  "currency": "KES"
}
```

The money is now in your Payd account. You can see it in the app or with the [balances endpoint](./balances.md).

## Before you go live

- [ ] Keys live only on your server, never in a browser, mobile app or repository.
- [ ] Your webhook endpoint answers `200` quickly and handles the same event more than once. See [webhooks](./webhooks.md).
- [ ] You confirm every payment with the [status endpoint](./transaction-status.md) before you ship goods or release funds.
- [ ] You never resend a payin or payout without checking whether the first one went through. See [retries and duplicates](./core-concepts.md#retries-and-duplicates).
- [ ] You store Payd's `merchant_reference` next to your own order id.
- [ ] For payouts, the account owner has set a withdrawal PIN in the Payd app, and you check fees with a [quote](./quotes.md).
- [ ] You show customers the options from [payment options by country](./network-discovery.md) instead of a hard-coded list.

## Next steps

- [Collect with mobile money](./pan-african-payins.md) in other countries
- [Pay out with M-Pesa](./kenya-payouts.md)
- [Handle webhooks](./webhooks.md)