# 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](./webhooks.md), [errors](./errors.md) and [how payments work](./core-concepts.md), each on its own page.
- New guides for [bank transfers](./bank-payins.md), [stablecoin payments](./stablecoin-payments.md) and [limits and settlement times](./limits-and-settlement.md).
- Files for AI coding assistants, and an OpenAPI file. See [Build with AI](./ai.md).

### 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`](./kenya-payins.md). |
| `POST /api/v2/withdrawal` | [`POST /api/v2/payments/payout`](./kenya-payouts.md) |
| `POST /api/v3/payments` (cards) | [`POST /api/v2/payments/payin`](./card-payments.md) with `transaction_channel` `card` |
| `GET /api/v1/status/{reference}` | [`GET /api/v2/payments/{reference}/status`](./transaction-status.md) |
| `GET /api/v1/accounts/{username}/all_balances` | [`GET /api/v1/balances/accounts/{account_id}`](./balances.md) |
| `GET /v2/networks/grouped` | [`GET /api/v2/payments/discovery/{country}`](./network-discovery.md) |
| `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](./authentication.md#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](./errors.md).
- **Webhooks.** New endpoints send a new webhook body. See [webhooks](./webhooks.md).
- **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.md#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](./core-concepts.md#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.