Cowdidocs
API ReferenceTransactions

Create an M-Pesa pay-bill payment

POST
/v1/transactions/mpesa/pay-bill

Create an M-Pesa pay-bill payment from one of the caller's accounts. Requires an authenticated, active user. Returns the transaction. It starts PENDING and moves to CONFIRMED or FAILED as M-Pesa, and any required OTP, confirm it. For a FLEX_CREDIT account, get GET /v1/accounts/flex/{account_id}/tenure/options and send the chosen option's tenure. Omit tenure for other account types. A repeated request with the same Idempotency-Key header replays the first response instead of creating a second payment, and reusing the key with a different request body returns 409. Returns 404 when account_id does not belong to the caller, and 422 when the pay bill and account number match a payee the caller has blocked. Returns 409 LOAN_REPAYMENT_PAYBILL_NOT_SUPPORTED when the pay bill and account number are a Cowdi loan repayment destination.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Header Parameters

Idempotency-Key*string

Unique key that de-duplicates retries of this request: the first call executes and its response is stored, identical retries replay it, and reusing a key with a different request body is rejected with 409 Conflict.

Lengthlength <= 255

Request Body

application/json

Request to create an M-Pesa pay-bill payment.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/transactions/mpesa/pay-bill" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "account_id": "550e8400-e29b-41d4-a716-446655440000",    "amount": {      "value": 250000,      "currency": "KES"    },    "paybill_number": "400200",    "account_number": "ACC123456"  }'
{  "id": "01a11715-7b0d-7e3f-9c2a-4d5e6f708192",  "resource_id": "trx_01m4bhayrdfrzsrajdbsqq10cj",  "mpesa_transaction_id": "ABCDE12345",  "amount": {    "value": 100000,    "currency": "KES"  },  "fee_amount": {    "value": 5000,    "currency": "KES"  },  "status": "COMPLETED",  "failure_reason": null,  "transacted_at": "2026-01-20T10:30:00Z",  "confirmed_at": "2026-01-20T10:30:05Z",  "posted_at": "2026-01-20T10:30:10Z",  "failed_at": null,  "details": {    "type": "BUY_GOODS",    "till_number": "12345"  }}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "id": "01a11715-7b0d-7e3f-9c2a-4d5e6f708192",  "resource_id": "trx_01m4bhayrdfrzsrajdbsqq10cj",  "mpesa_transaction_id": "ABCDE12345",  "amount": {    "value": 100000,    "currency": "KES"  },  "fee_amount": {    "value": 5000,    "currency": "KES"  },  "status": "COMPLETED",  "failure_reason": null,  "transacted_at": "2026-01-20T10:30:00Z",  "confirmed_at": "2026-01-20T10:30:05Z",  "posted_at": "2026-01-20T10:30:10Z",  "failed_at": null,  "details": {    "type": "BUY_GOODS",    "till_number": "12345"  }}
{  "id": "01a11715-7b0d-7e3f-9c2a-4d5e6f708192",  "resource_id": "trx_01m4bhayrdfrzsrajdbsqq10cj",  "mpesa_transaction_id": "ABCDE12345",  "amount": {    "value": 100000,    "currency": "KES"  },  "fee_amount": {    "value": 5000,    "currency": "KES"  },  "status": "COMPLETED",  "failure_reason": null,  "transacted_at": "2026-01-20T10:30:00Z",  "confirmed_at": "2026-01-20T10:30:05Z",  "posted_at": "2026-01-20T10:30:10Z",  "failed_at": null,  "details": {    "type": "BUY_GOODS",    "till_number": "12345"  }}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Create an M-Pesa buy-goods payment POST

Create an M-Pesa buy-goods payment from one of the caller's accounts. Requires an authenticated, active user. Returns the transaction. It starts `PENDING` and moves to `CONFIRMED` or `FAILED` as M-Pesa, and any required OTP, confirm it. For a `FLEX_CREDIT` account, get `GET /v1/accounts/flex/{account_id}/tenure/options` and send the chosen option's `tenure`. Omit `tenure` for other account types. A repeated request with the same `Idempotency-Key` header replays the first response instead of creating a second payment, and reusing the key with a different request body returns 409. Returns 404 when `account_id` does not belong to the caller, and 422 when the till number matches a payee the caller has blocked.

Pay a Pochi la Biashara wallet POST

Pay the Pochi la Biashara business wallet of a mobile number from one of the caller's credit accounts. Requires an authenticated, active user. Returns the transaction with type `POCHI`. It starts `PENDING` and moves to `COMPLETED` or `FAILED` when M-Pesa sends the result. For a `FLEX_CREDIT` account, get `GET /v1/accounts/flex/{account_id}/tenure/options` and send the chosen option's `tenure`. Omit `tenure` for other account types. Cowdi cannot reverse a Pochi la Biashara payment. A repeated request with the same `Idempotency-Key` header replays the first response, and reusing the key with a different request body returns 409. Returns 404 when `account_id` does not belong to the caller, and 422 when the mobile number matches a payee the caller has blocked. Returns 422 `POCHI_NOT_SUPPORTED_FOR_ACCOUNT` for an account that is not a credit account, 422 `POCHI_NOT_AVAILABLE` when the organization of the account has no Pochi la Biashara service, and 422 `POCHI_AMOUNT_OUT_OF_RANGE` for an amount less than KES 10 or more than KES 250,000.