Capture an authorized payment, optionally partially
Captures an authorized payment. amount defaults to the full authorization; capturing less releases the remainder of the hold back to the payer in the same posting.
/v1/payments/{paymentId}/captureCaptures an authorized payment. amount defaults to the full authorization; capturing less releases the remainder of the hold back to the payer in the same posting. Requires payments:write, an Idempotency-Key, and a merchant-side principal: a user token is refused insufficient_scope (403) even when it carries the scope, so no one can capture a stranger's hold by its id. Refuses payment_not_found (404), invalid_state (409) when the payment is not awaiting capture, and capture_exceeds_authorized (422).
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
Path Parameters
uuidHeader 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
# Capturing less than was authorized releases the difference.curl -sS -X POST "$WALLETD_API/v1/payments/$PAYMENT_ID/capture" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: capture-booking-771" \ -d '{"amount": 58000}'{ "id": "0191c2e0-1c93-7b46-8d57-40ae9b62f138", "status": "captured", "mode": "authorize", "payer_user_id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27", "merchant_id": "0191c2d6-1a44-7b09-8e73-2c5f9a08d641", "amount": 60000, "captured_amount": 58000, "refunded_amount": 0, "fee": 0, "commission": 0, "created_at": "2026-09-20T08:02:55Z"}