Cowdidocs
API ReferenceTransactions

Create an M-Pesa buy-goods payment

POST
/v1/transactions/mpesa/buy-goods

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.

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 buy-goods 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/buy-goods" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "account_id": "550e8400-e29b-41d4-a716-446655440000",    "amount": {      "value": 100000,      "currency": "KES"    },    "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": "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"}

Send the transaction OTP POST

Send or resend the OTP for a pending transaction. Requires an authenticated, active user. The transaction must be `PENDING_OTP` or `PENDING_OTP_CONFIRMATION`. OTP applies only to transactions on the Choice payment route; other transactions return 400. Returns 404 when the transaction does not exist, or its account does not belong to the caller. Confirm the code with `POST /v1/transactions/{id}/confirm`.

Create an M-Pesa pay-bill payment POST

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.