Docs

Appearance

MarkdownAsk ClaudeAsk ChatGPT

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, 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 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. 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:

bash
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
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.

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 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.

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.
  • [ ] You confirm every payment with the status endpoint 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.
  • [ ] 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.
  • [ ] You show customers the options from payment options by country instead of a hard-coded list.

Next steps ​