Preview

Update receiver configuration

PATCH
/providers/{providerID}/configuration

Store a new version of the outbound receiver configuration for your provider. Send expectedVersion from your latest read. Use 0 when no version is stored. A successful call stores the next version and returns it. Omitted fields keep their stored values. Send null for credentialReferenceID to clear that reference. Send an empty url to clear that endpoint.

The financial institution creates and updates a configuration whose receiver type is fi. The affiliated integrator creates and updates a configuration whose receiver type is integrator. After the integrator owns the receiver, only that integrator changes URLs, credential references, and timeouts. The financial institution can set the receiver back to fi only when those values stay the same.

Returns 200 with the new version. Returns 400 when the body is malformed, contains an unknown field, or names a URL, timeout, or receiver the service rejects. Returns 401 when your API key or bearer token is missing or invalid. Returns 403 when you cannot act for the provider, or when you do not own the routing values. Returns 404 when a credential reference is unknown. Returns a 409 with problem type version-conflict and currentVersion when expectedVersion is not the latest version. Returns a 409 when a credential reference is not active, or when the affiliation cannot accept the write. A rejected write leaves the stored version unchanged. You can call this while your affiliation with the provider is still being set up.

There is no idempotency key. After a successful write, send the returned version as expectedVersion on the next call.

Auth: API key or bearer token. An affiliated integrator needs the moov-money-config.write scope granted by the FI.

Request
cURL
curl -X PATCH https://api.moov.money/providers/{providerID}/configuration \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "Content-Type: application/json" \
  -d '{
  "authorize": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "capture": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "credit": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "expectedVersion": 3,
  "receiver": {
    "accountID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
    "type": "fi"
  },
  "release": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  }
}'
Responses
200 400 401 403 404 409
The request completed successfully.
{
  "authorize": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "capture": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "credit": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "providerID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
  "receiver": {
    "accountID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
    "type": "fi"
  },
  "receiverDeduplicatesAuthorize": false,
  "release": {
    "attemptTimeout": 2000000000,
    "credentialReferenceID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
    "deadline": 8000000000,
    "url": "https://fi.example.com/authorize"
  },
  "version": 0
}
Malformed request: the body or headers failed validation.
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.
Authentication missing, invalid, or insufficient.
Authentication present but the action is forbidden for this principal/claim.
The requested resource was not found.
The configuration write conflicts with the stored version or with the receiver state. A stale expectedVersion includes currentVersion. Read the configuration and retry. The stored version stays unchanged.
Response body application/problem+json
RFC 9457 Problem Details body of a 409 from the provider configuration routes. A stale expectedVersion uses problem type version-conflict and includes currentVersion. Other conflicts omit currentVersion.

detail

string
Human-readable explanation of this specific occurrence.

type

string required
URI that tells you which problem occurred.

title

string required
Short human-readable name of the problem type.

status

integer<int32> required
The HTTP status code of this response, always 409.

currentVersion

integer<int64>
Latest stored version when expectedVersion does not match. Read the configuration and retry with this value. Absent when the conflict is not a version mismatch. 0 means no version is stored.

Headers

X-Moov-Version

string
Set this header to the API version being targeted (e.g. v2026.10.00). When omitted, the server applies its default version.

Path parameters

providerID

string required
Your provider account ID.

Request

application/json
Fields to store as the next configuration version. Send expectedVersion from your latest read, or 0 when no version is stored. Omitted fields keep their stored values. On the first write, an omitted authorize, capture, or release operation receives the service default attempt timeout and deadline. An omitted credit operation receives that attempt timeout for both values.

expectedVersion

integer<int64> required
Version you read. Use 0 when no version is stored.

receiver

object
Receiver for outbound ledger calls. Omitted leaves the stored receiver unchanged.
Show child attributes

receiver

type

string<enum> required
Kind of receiver. fi is your provider account. integrator is the affiliated integrator.
Possible values: fi, integrator

accountID

string
Receiver account ID. For fi, omit this field or set it to your provider account ID. For integrator, set it to the affiliated integrator account ID.

authorize

object
Authorize endpoint changes. Omitted fields keep their stored values.
Show child attributes

authorize

url

string
HTTPS URL Moov Money calls for this operation. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters. The host is one approved for this receiver. An empty string clears the URL.

credentialReferenceID

string | null
Credential reference for this operation. The reference belongs to the receiver and is active. Send null to clear the stored reference. Omitted leaves the stored reference unchanged.

attemptTimeout

integer<int64>
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64>
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

capture

object
Capture endpoint changes. Omitted fields keep their stored values.
Show child attributes

capture

url

string
HTTPS URL Moov Money calls for this operation. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters. The host is one approved for this receiver. An empty string clears the URL.

credentialReferenceID

string | null
Credential reference for this operation. The reference belongs to the receiver and is active. Send null to clear the stored reference. Omitted leaves the stored reference unchanged.

attemptTimeout

integer<int64>
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64>
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

release

object
Release endpoint changes. Omitted fields keep their stored values.
Show child attributes

release

url

string
HTTPS URL Moov Money calls for this operation. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters. The host is one approved for this receiver. An empty string clears the URL.

credentialReferenceID

string | null
Credential reference for this operation. The reference belongs to the receiver and is active. Send null to clear the stored reference. Omitted leaves the stored reference unchanged.

attemptTimeout

integer<int64>
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64>
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

credit

object
Credit endpoint changes. Omitted fields keep their stored values.
Show child attributes

credit

url

string
HTTPS URL Moov Money calls for this operation. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters. The host is one approved for this receiver. An empty string clears the URL.

credentialReferenceID

string | null
Credential reference for this operation. The reference belongs to the receiver and is active. Send null to clear the stored reference. Omitted leaves the stored reference unchanged.

attemptTimeout

integer<int64>
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64>
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

receiverDeduplicatesAuthorize

boolean
Whether the receiver treats a repeated authorize for the same payment as the same hold. Omitted leaves the stored value unchanged. The first write uses false.

Response

The latest outbound receiver configuration for your provider.

providerID

string required
Your provider account ID.

version

integer<int64> required
A value of 0 means no configuration version is stored. Send this value as expectedVersion on the next update.

receiver

object required
Account that receives outbound ledger calls.
Show child attributes

receiver

type

string<enum> required
Kind of receiver. fi is your provider account. integrator is the affiliated integrator.
Possible values: fi, integrator

accountID

string required
Account ID of the receiver. For fi, this is your provider account ID.

authorize

object required
Authorize endpoint settings.
Show child attributes

authorize

url

string required
HTTPS URL Moov Money calls for this operation. Empty when no URL is stored. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters.

credentialReferenceID

string | null required
Credential reference for this operation. Null when none is set.

attemptTimeout

integer<int64> required
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64> required
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

capture

object required
Capture endpoint settings.
Show child attributes

capture

url

string required
HTTPS URL Moov Money calls for this operation. Empty when no URL is stored. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters.

credentialReferenceID

string | null required
Credential reference for this operation. Null when none is set.

attemptTimeout

integer<int64> required
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64> required
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

release

object required
Release endpoint settings.
Show child attributes

release

url

string required
HTTPS URL Moov Money calls for this operation. Empty when no URL is stored. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters.

credentialReferenceID

string | null required
Credential reference for this operation. Null when none is set.

attemptTimeout

integer<int64> required
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64> required
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

credit

object required
Credit endpoint settings.
Show child attributes

credit

url

string required
HTTPS URL Moov Money calls for this operation. Empty when no URL is stored. Use port 443 or omit the port. The URL has no user information and no fragment. Maximum length is 2048 characters.

credentialReferenceID

string | null required
Credential reference for this operation. Null when none is set.

attemptTimeout

integer<int64> required
Time Moov Money waits for one attempt, in nanoseconds. The value is greater than zero and no greater than deadline.

deadline

integer<int64> required
Time Moov Money waits for the whole operation, including retries, in nanoseconds. The value is greater than or equal to attemptTimeout.

receiverDeduplicatesAuthorize

boolean required
Whether the receiver treats a repeated authorize for the same payment as the same hold. Moov Money uses this when an authorize response does not arrive.