# Quickstart

Collect a small payment from your own mobile money wallet and watch it land in your Payd account. It takes about ten minutes.

You need a Payd account, a mobile money wallet in a country Payd supports, and a terminal with `curl`. Every request moves real money, so keep to small amounts.

## 1. Create an API key

In the [Payd Money 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

Outside Kenya, first look up your network's `network_id` and `channel_id` with [payment options by country](./network-discovery.md). Use your own country code:

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

Then send the payin with your own phone number and details. M-Pesa in Kenya needs no network ids, and the number goes in the form `2547XXXXXXXX`:

::: code-group

```bash [Mobile money]
curl https://api.payd.money/api/v2/payments/payin \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20000,
    "currency": "UGX",
    "country": "UG",
    "transaction_channel": "mobile",
    "customer": {
      "first_name": "Grace",
      "last_name": "Namubiru",
      "phone_number": "+256771234567",
      "email": "grace@example.com",
      "country": "UG",
      "document_type": "national_id",
      "document_number": "CM94012345ABCD",
      "dob": "1994-03-12T00:00:00Z",
      "address": { "line_1": "Plot 12 Kampala Road", "city": "Kampala", "country": "UG" }
    },
    "vendor_config": { "account_id": "'"$PAYD_ACCOUNT_ID"'" },
    "provider_config": {
      "network_id": "04a3083a-567c-4a2b-aa39-fa8f19e64341",
      "channel_id": "e167def0-c4f0-46e2-aaa9-50046f13b0a7"
    },
    "payment_config": {
      "account_number": "+256771234567",
      "remark": "Quickstart test",
      "reference": "quickstart-001",
      "callback_url": "https://webhook.site/your-unique-id"
    }
  }'
```

```bash [M-Pesa in Kenya]
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"
    }
  }'
```

:::

Mobile money outside Kenya needs your ID, date of birth, email and address, as shown. See [who is paying](./core-concepts.md#who-is-paying).

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 a payment prompt. Approve it with your PIN. On some networks the request waits in your mobile money app instead. 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": 20000,
  "currency": "UGX",
  "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": 20000,
  "currency": "UGX"
}
```

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 Money 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 by bank transfer](./bank-payins.md), [card](./card-payments.md) or [stablecoin](./stablecoin-payments.md)
- [Pay out to mobile money or a bank](./pan-african-payouts.md)
- [Handle webhooks](./webhooks.md)