Cowdidocs
API ReferencePayees

Add a payee account

POST
/v1/user/payees/{payeeId}/accounts

Add a payable account to one of the caller's payees, 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. Returns 404 when the payee does not exist, or 409 when it already has an account for that destination. 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

Path Parameters

payeeId*string

Unique identifier of the payee.

Formatuuid

Request Body

application/json

Request to add an account to an existing payee. The required account fields depend on type.

Add a send-money account to a payee

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/user/payees/550e8400-e29b-41d4-a716-446655440000/accounts" \  -H "Content-Type: application/json" \  -d '{    "type": "SEND_MONEY",    "mobile_number": "254712345678",    "account_holder_name": "John Doe"  }'
{  "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": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "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"}

Delete a payee DELETE

Delete one of the caller's payees and all of its accounts. Requires an authenticated, active user. Returns 404 when the payee does not exist or does not belong to the caller.

Delete a payee account DELETE

Remove one account from one of the caller's payees. The payee remains even when this was its last account. Requires an authenticated, active user. Returns 404 when the payee or the account does not exist.