Changelog

16 October 2026

New docs

These docs were rewritten to match how the Payd API works today. Requests, responses and errors follow the live API. You also get:

• Code samples in cURL, Node.js, Python and PHP.
• Webhooks, errors and how payments work, each on its own page.
• New guides for bank transfers, stablecoin payments and limits and settlement times.
• Files for AI coding assistants, and an OpenAPI file. See Build with AI.

Endpoints that moved

If your integration was built on the older docs, move these calls. The old paths now return 501 not_implemented, except the M-Pesa collection endpoint, which still works.

Old call	Use now
POST /api/v2/payments (M-Pesa collection)	Still works. New work should use POST /api/v2/payments/payin.
POST /api/v2/withdrawal	POST /api/v2/payments/payout
POST /api/v3/payments (cards)	POST /api/v2/payments/payin with transaction_channel card
GET /api/v1/status/{reference}	GET /api/v2/payments/{reference}/status
GET /api/v1/accounts/{username}/all_balances	GET /api/v1/balances/accounts/{account_id}
GET /v2/networks/grouped	GET /api/v2/payments/discovery/{country}
POST /api/v2/p2p	No API replacement. Send Payd to Payd transfers from the Payd Money App.

What changes when you move:

• Account id. New endpoints name your account by id, not username. Find your account id once and keep it in your configuration.
• Errors. New endpoints return error_code, error_message, status_code and request_id. See errors.
• Webhooks. New endpoints send a new webhook body. See webhooks.
• Payouts. One call sends the payout. Check its status to confirm it arrived.

Pages removed

• Paybill and Till payouts. The API pays out to M-Pesa numbers, mobile money wallets and bank accounts. It does not pay Paybill or Till numbers.
• Payd to Payd transfers. Use the Payd Money App.
• Bank account lookup. Ask the recipient to confirm their details before you pay out.

API changes

• Failed payments now show as failed on the status endpoint. Before, they returned 404.
• M-Pesa payouts in Kenya no longer need a provider. Send provider_config as {}.
• Payment options by country list only the networks and banks you can use with an API key. Groups are keyed by route ids.
• A key can read balances only for its own account.
• Webhooks are signed. Check the X-Payd-Signature header with the secret from GET /api/v2/webhooks/secret. See verify the signature.
• Webhooks have an event field, such as payin.succeeded or payout.failed.
• Payd now sends a webhook when a payout succeeds, not only when it fails.
• Payd retries a webhook that does not get a 2xx, up to 12 hours after the first try.
• Payins and payouts take an idempotency_key, so a resend after a timeout is safe. See retries and duplicates.
• Bank transfer payins return gateway_response.bank_instructions with the account to pay.
• Payment options by country show settlement_type and settlement_seconds for each network.
• merchant_reference on a payin response is always Payd's reference, the one the status endpoint takes.
• Responses, errors and webhooks name routes by id. They no longer name the companies Payd works with behind the scenes.