Cowdidocs
API ReferencePayees

List payees

GET
/v1/user/payees

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.

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

Query Parameters

size?integer

Maximum number of payees to return. Defaults to 50. Capped at 100.

Range0 < value
Default50
after?string

Opaque cursor for the page after the last result of a previous response, from that response's links.next. Omit to get the first page.

before?string

Opaque cursor for the page before the first result of a previous response, from that response's links.prev. Omit to get the first page.

type?|

Filter to payees that have an account of this type.

Value in

  • "SEND_MONEY"
  • "POCHI"
  • "PAY_BILL"
  • "BUY_GOODS"
  • "BANK_ACCOUNT"
favorite?boolean

Filter to favourite payees when true, or to non-favourite payees when false. Omit to return both.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/user/payees?size=50&after=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9&before=eyJpZCI6IjZiYTdiODEwLTlkYWQtMTFkMS04MGI0LTAwYzA0ZmQ0MzBjOCJ9&type=SEND_MONEY&favorite=true"
{  "data": [    {      "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"    }  ],  "links": {    "next": "/v1/payees?after=eyJpZCI6MX0",    "prev": "/v1/payees?before=eyJpZCI6MX0"  }}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Transfer between the caller's accounts POST

Transfer money between two of the caller's own accounts. The current version supports one pair: a current account pays a lending account. Requires an authenticated, active user. The custodian sends the caller an OTP, and the transaction waits in `PENDING_OTP_CONFIRMATION` until the caller confirms it with `POST /v1/transactions/{id}/confirm`. Both accounts record the transfer, with the counterparty account, in their transaction details. A repeated request with the same `Idempotency-Key` header replays the first response instead of creating a second transfer, and reusing the key with a different request body returns 409. Returns 404 when `from_account_id` or `to_account_id` does not belong to the caller, and 400 when the accounts are not a current-to-lending pair, use different currencies, or the amount exceeds the destination's outstanding balance.

Create a payee POST

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.