WalletD developers
Transfers

P2P transfer between users in the tenant loop

Moves cash between two users inside the same tenant loop, in one balanced posting or not at all.

POST/v1/transfers

Moves cash between two users inside the same tenant loop, in one balanced posting or not at all. Requires transfers:write and an Idempotency-Key. Name the recipient either by to_user or by a single to_alias (phone, email or handle). The sender must be the caller when a user token is used (forbidden, 403). Refuses self_transfer (400), sender_not_found or recipient_not_found (404), insufficient_funds (422), tier_limit_exceeded (422) when the sender's tier cap is reached, and idempotency_key_reuse (409) when the key comes back with a different body; a replay with the same body returns the original transfer.

Authorization

bearerAuth
AuthorizationBearer <token>

A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.

In: header

Header Parameters

Idempotency-Key*string
Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

curl -sS -X POST "$WALLETD_API/v1/transfers" \  -H "Authorization: Bearer $WALLETD_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: transfer-order-8891" \  -d '{"from_user": "'$SENDER'", "to_alias": {"handle": "ada"}, "amount": 1500}'
{  "id": "0191c2d8-4c0f-7d12-b845-91e3a7f6c204",  "status": "completed",  "from_user": "0191c2d5-2b18-7e63-8f4a-05c7b9d1e832",  "to_user": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27",  "amount": 1500,  "fee": 0,  "created_at": "2026-09-20T09:16:40Z"}

Inbound payment-processor callback (processors only, never called by an integrator)

Inbound. This is where the payment processor tells WalletD that a top-up succeeded or failed; an integrator never calls it.

Pay a merchant, instantly or as an authorization hold

Charges a wallet user and settles the merchant, in one balanced posting or not at all.