Release

POST
/ledger/release

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

Release a previously-placed hold, returning the held funds to the sender.

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

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

  • approved: hold released.
  • failed: you could not release the hold.

Idempotency: you must return the same outcome (and same releaseReference if approved) for repeated requests with the same idempotencyKey. Releasing an already-released hold must return approved; reuse the original releaseReference if you can look it up.

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/release \
  -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 release.

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.

reason

string
Why the hold is being released. Non-normative: Moov currently sends values like cancelled (user-initiated) or expired (hold TTL exceeded). Lets you distinguish these in your ledger.

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 release on this operation.
Possible values: release

iat

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

Response claims

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

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. Release has no denied outcome: either you released the hold (approved) or you did not (failed).

  • approved: the hold is released. releaseReference is required.
  • failed: you could not release the hold.
Possible values: approved, failed

releaseReference

string
FI-issued reference for the release. Required when outcome=approved; omit when outcome=failed.

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.