Credit account

POST
/ledger/credit-account

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

Credit a request-for-payment’s funding destination from the provider wallet.

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

Outcomes (200 OK):

  • approved: the ledger entry is posted.
  • destination_unavailable: this destination cannot receive the deposit (closed/invalid account); retryable.
  • refused: you refuse the deposit itself; terminal.

Do not return 200 with an unmodeled outcome value. Moov Money treats that (and any transport error, 408, 429, or 5xx) as an internal unknown result and retries the same request with the same idempotencyKey.

Idempotency: you must return the same outcome (and same creditReference if approved) for repeated requests with the same idempotencyKey. The scope of a credit-account idempotencyKey is one disbursement attempt.

Retries: Moov Money retries on transport errors, 408, 429, and 5xx. Other 4xx are terminal. Moov Money never reverses while the credit outcome is ambiguous; only an explicit refused begins reversal.

Request
cURL
curl -X POST https://fi.example.com/ledger/credit-account \
  -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 credit-account.

exp

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

moov

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

moov

providerID

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

idempotencyKey

string required
Moov-chosen idempotency nonce; you must echo it back.

requesterExternalID

string required
The requester’s provider-scoped external ID.

fundingDestination

string required
The snapshotted funding destination where the deposit lands. Opaque to you.

amount

object required
Deposit amount.
Show child attributes

moov.amount

currency

object required
ISO 4217 currency descriptor.
Show child attributes

moov.amount.currency

decimalPlaces

integer<uint8> required
Number of minor-unit decimal places for code. Required.

numericCode

string
ISO 4217 numeric currency code, if known. Informational only.

name

string
Human-readable currency name, if known. Informational only.

code

string required
Uppercase 3-letter ISO 4217 currency code.

value

string required
Decimal amount as a string.

requestID

string required
Moov request-for-payment ID this credit settles.

typ

string<enum> required
Request type. Always credit-account on this operation.
Possible values: credit-account

iat

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

Response claims

Inner JWT
Full JWT payload of the response JWE for POST credit-account.

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
The explicit FI outcome.
Possible values: approved, destination_unavailable, refused, unknown

creditReference

string
FI-issued reference for the credit. Required when outcome=approved; omit otherwise.

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.