Capture

POST
/ledger/capture

The path above is illustrative. You host this endpoint; Moov Money POSTs to the URL you register for this operation. See Setup.

Capture (settle) a previously-placed hold, moving funds out of the sender’s funding source.

The request body is a RequestEnvelope; the inner JWE payload conforms to CaptureRequestJWTPayload. The response body is a ResponseEnvelope; the inner JWE payload conforms to CaptureResponseJWTPayload.

Outcomes (200 OK; capture has no denied outcome):

  • approved: hold captured.
  • failed: you could not capture the hold (ledger error, etc.).

Idempotency: capture is idempotent by both idempotencyKey and holdReference.

  • A repeat capture with the same idempotencyKey must return the same outcome.
  • A capture of an already-captured holdReference (whether the idempotencyKey is the same or different) must return outcome=approved. Reuse the original captureReference if you can look it up.
  • If you cannot resolve a holdReference at all (e.g. it has aged out of your records), you must still return outcome=approved. Moov Money treats unknown holds as already captured; the alternative would strand funds. If this behavior does not fit your ledger model, escalate to Moov before implementing.

Retries: Moov Money will retry on 408, 429, 5xx, and transport errors. Return other 4xx for terminal validation failures.

Request
cURL
curl -X POST https://fi.example.com/ledger/capture \
  -H "Content-Type: application/json" \
  -d '{
  "request": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldUIiwiY3R5IjoiSldUIn0.…"
}'
Responses
200
The request has succeeded.
{
  "response": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldUIiwiY3R5IjoiSldUIn0.…"
}

Request

application/json
Every FI ledger endpoint accepts the same envelope: a single JWE string in the request field. All business fields (amounts, references, idempotency key) travel inside the JWE claims, not in the outer JSON.

request

string required
Compact-serialized JWE carrying the request claims.

Request claims

Inner JWT
Full JWT payload of the request JWE for POST capture.

exp

integer<int64> required
Expiration time (JWT NumericDate, Unix seconds).

moov

object required
Moov-namespaced claims for the operation.
Moov claims

moov

payoutID

string required
Moov payout ID this call relates to.

providerID

string required
Moov account ID identifying you as the provider being called.

holdReference

string required
The hold reference you originally returned on authorize.

idempotencyKey

string required
Moov-chosen idempotency nonce. Echo it back on your response. The dedupe scope of this key is per endpoint: don’t treat an idempotencyKey you saw on authorize as already processed if it turns up on release or capture, and vice versa. Moov Money currently derives per-payout keys that may collide across the three endpoints; treating them as endpoint-scoped is required for correctness.

typ

string<enum> required
Request type. Always capture on this operation.
Possible values: capture

iat

integer<int64> required
Issued-at time (JWT NumericDate, Unix seconds).

Response claims

Inner JWT
Full JWT payload of the response JWE for POST capture.

exp

integer<int64> required
Expiration time (JWT NumericDate, Unix seconds).

moov

object required
Moov-namespaced claims for the operation.
Moov claims

moov

reason

string
Human-readable reason. Required for denied/failed; optional for approved.

outcome

string<enum> required

High-level decision. Capture has no denied outcome: either you captured the hold (approved) or you did not (failed).

  • approved: the hold is captured (funds moved). captureReference is required. A repeat capture of an already-captured hold must also return approved; see the endpoint idempotency notes.
  • failed: you could not capture the hold.
Possible values: approved, failed

captureReference

string
FI-issued reference for the capture (settlement). Required when outcome=approved; omit when outcome=failed. On a repeat capture of an already-captured hold, return the original captureReference if it can look it up.

idempotencyKey

string required
Echoed from the request. Moov rejects the response if this does not match.

iat

integer<int64> required
Issued-at time (JWT NumericDate, Unix seconds).

Response

Every FI ledger endpoint returns the same envelope: a single JWE string in the response field. All business fields (outcome, references, echoed idempotency key) travel inside the JWE claims, not in the outer JSON.

response

string required
Compact-serialized JWE carrying the response claims.