Cowdidocs
API ReferencePayees

Create a payee

POST
/v1/user/payees

Create a payee with one initial account for the caller, verified inline against Confirmation of Payee. The required destination fields depend on type (SEND_MONEY, POCHI, PAY_BILL, BUY_GOODS, or BANK_ACCOUNT), and an unlinked destination needs an account_holder_name. Saving a destination the caller already has returns that existing payee instead of a duplicate. A partial or no name match, or a provider outage, returns 422 PAYEE_ACCOUNT_CONFIRMATION_REQUIRED. Resubmit with confirm=true to save the account anyway. Requires an authenticated, active user.

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

Request Body

application/json

Request to create a new payee with an initial account. The required account fields depend on type.

Create a send-money payee

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/user/payees" \  -H "Content-Type: application/json" \  -d '{    "type": "SEND_MONEY",    "mobile_number": "254712345678",    "account_holder_name": "John Doe",    "label": "My Brother"  }'
{  "id": "550e8400-e29b-41d4-a716-446655440000",  "label": "string",  "display_name": "string",  "is_favorite": false,  "is_blocked": false,  "block_reasons": [    "UNWANTED_PAYMENTS"  ],  "block_details": "string",  "is_cowdi_user": false,  "cowdi_user_id": "660e8400-e29b-41d4-a716-446655440111",  "cowdi_user_tag": "@johnd123456",  "accounts": [    {      "resource_id": "string",      "id": "660e8400-e29b-41d4-a716-446655440001",      "type": "SEND_MONEY",      "account_holder_name": "string",      "linked_user_id": "660e8400-e29b-41d4-a716-446655440111",      "linked_user_tag": "@johnd123456",      "mobile_number": "254712345678",      "transaction_count": 15,      "last_used_at": "2026-02-10T14:00:00Z",      "verification_status": "VERIFIED",      "verified_at": "2026-02-01T08:00:00Z",      "verification": {        "resolved_name": "John Doe",        "account_valid": true,        "requires_confirmation": false,        "message": "string"      }    }  ],  "created_at": "2026-01-15T10:30:00Z",  "updated_at": "2026-02-01T08:00:00Z",  "resource_id": "string"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "PAYEE_ACCOUNT_CONFIRMATION_REQUIRED",  "description": "string",  "resolved_name": "John Doe",  "verification_status": "UNVERIFIED",  "message": "string"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List payees GET

Get a keyset-paginated page of the caller's saved payees. Payees come favourites first, then newest first, and each payee's accounts come most-used first. Requires an authenticated, active user. Filter the page to one account `type` (`SEND_MONEY`, `POCHI`, `PAY_BILL`, `BUY_GOODS`, or `BANK_ACCOUNT`) or to `favorite` payees only. Page through the results with the `after` or `before` cursor.

Get payees by id POST

Get the caller's payees for a list of ids, in the order requested. The response omits any id that does not exist or does not belong to the caller. It never returns 404 for a missing id. Accepts 1 to 100 ids per request. Requires an authenticated, active user.