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.
/v1/paymentsCharges a wallet user and settles the merchant, in one balanced posting or not at all. mode: instant moves the money now; mode: authorize holds it on the payer's account until a capture or a void, and the hold expires by itself after hold_ttl_seconds (900 by default). Requires payments:write and an Idempotency-Key; an API key may pay for any user, a user token only for itself (forbidden, 403). Refuses payer_not_found or merchant_not_found (404), insufficient_funds (422), and idempotency_key_reuse (409) when the key comes back with a different body; a replay with the same body returns the original payment.
Authorization
bearerAuth 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
1 <= length <= 200Request 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
# mode "instant" settles now; "authorize" holds the money for a later capture.curl -sS -X POST "$WALLETD_API/v1/payments" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: payment-order-4471" \ -d '{"payer_user_id": "'$USER_ID'", "merchant_id": "'$MERCHANT_ID'", "amount": 1840, "mode": "instant"}'{ "id": "0191c2da-7d55-7a80-9143-6be2f08c5d97", "status": "captured", "mode": "instant", "payer_user_id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27", "merchant_id": "0191c2d6-1a44-7b09-8e73-2c5f9a08d641", "amount": 1840, "captured_amount": 1840, "refunded_amount": 0, "fee": 0, "commission": 0, "created_at": "2026-09-20T09:18:11Z"}