{ "openapi": "3.1.0", "info": { "title": "Monterey Client API", "description": "Org-scoped, token-authenticated account, borrower, and payment endpoints for Monterey Financial clients.", "version": "1.0.0" }, "servers": [ { "url": "https://api.montereyfinancial.app", "description": "Production" } ], "paths": { "/v1/oauth/token": { "post": { "tags": [ "Authentication" ], "summary": "Mint an access token", "description": "Exchange an API key prefix and plaintext secret for a 3600-second bearer token.", "operationId": "mint_token_v1_oauth_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "The request does not use the client_credentials grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The client ID or API key is invalid or cannot mint tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The source IP exceeded the token-exchange rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List organizations", "description": "Paginated list of organizations the calling access token is scoped to.", "operationId": "list_organizations_v1_organizations_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_OrganizationRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "organizations:read" ] } }, "/v1/organizations/{party_id}": { "get": { "tags": [ "Organizations" ], "summary": "Get an organization", "description": "Returns a single organization by ID. Returns 404 if the organization isn't reachable by this key.", "operationId": "get_organization_v1_organizations__party_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "party_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Party Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "organizations:read" ] } }, "/v1/persons": { "get": { "tags": [ "Persons" ], "summary": "List persons", "description": "Paginated list of persons (borrowers) visible to the calling access token's organization allowlist.", "operationId": "list_persons_v1_persons_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PersonRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "persons:read" ] } }, "/v1/persons/{party_id}": { "get": { "tags": [ "Persons" ], "summary": "Get a person", "description": "Returns an enriched person with active contact methods and current addresses. Returns 404 if the person isn't reachable by this token.", "operationId": "get_person_v1_persons__party_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "party_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Party Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDetailRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "persons:read" ] } }, "/v1/persons/{party_id}/accounts": { "get": { "tags": [ "Persons" ], "summary": "List a person's accounts", "description": "Returns accounts on which the person identified by `party_id` is the primary borrower or appears in AccountPartyRole, filtered to the calling access token's organization allowlist. Returns 404 if the person isn't visible to this key (out-of-scope party IDs are indistinguishable from non-existent ones).", "operationId": "list_accounts_for_person_v1_persons__party_id__accounts_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "party_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Party Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AccountRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "accounts:read" ] } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts", "description": "Paginated list of accounts scoped to the calling access token's organization allowlist. Filter by `organization_id` (returns 403 if out of scope).", "operationId": "list_accounts_v1_accounts_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AccountRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`) or the supplied `organization_id` is outside the access token's allowlist (`organization_out_of_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "accounts:read" ] } }, "/v1/accounts/by-external-id/{external_id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account by external ID", "description": "Returns an account by its source loan-management account identifier. Pass `organization_id` to disambiguate identifiers reused across organizations. Returns 404 if no matching account is reachable by this key and 409 when multiple visible accounts match.", "operationId": "get_account_by_external_id_v1_accounts_by_external_id__external_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "External Id" } }, { "name": "organization_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional organization used to disambiguate reused identifiers.", "title": "Organization Id" }, "description": "Optional organization used to disambiguate reused identifiers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetailRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`) or the supplied `organization_id` is outside the access token's allowlist (`organization_out_of_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "409": { "description": "Multiple visible accounts use this identifier. Retry with organization_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "accounts:read" ] } }, "/v1/accounts/by-external-contract-id/{external_contract_id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account by external contract ID", "description": "Returns an account by its client-supplied contract ID. Pass `organization_id` to disambiguate contract IDs reused across organizations. Returns 404 if no matching account is reachable by this key and 409 when multiple visible accounts match.", "operationId": "get_account_by_external_contract_id_v1_accounts_by_external_contract_id__external_contract_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "external_contract_id", "in": "path", "required": true, "schema": { "type": "string", "title": "External Contract Id" } }, { "name": "organization_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional organization used to disambiguate reused identifiers.", "title": "Organization Id" }, "description": "Optional organization used to disambiguate reused identifiers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetailRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`) or the supplied `organization_id` is outside the access token's allowlist (`organization_out_of_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "409": { "description": "Multiple visible accounts use this identifier. Retry with organization_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "accounts:read" ] } }, "/v1/accounts/{account_id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account", "description": "Richer per-account snapshot than GET /v1/accounts. Includes restored balance fields, audit timestamps, additional payment terms, plus a nested `contract` block and a unified `borrowers` list carrying roles and primary-borrower identity. Returns 404 if the account isn't in the calling access token's organization allowlist.", "operationId": "get_account_v1_accounts__account_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetailRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "accounts:read" ] } }, "/v1/accounts/{account_id}/transactions": { "get": { "tags": [ "Accounts" ], "summary": "List account transactions", "description": "Paginated list of transactions for a single account. Optionally filter with inclusive `from` and `to` dates. Omit both `from` and `to` to return the full history; results place null-dated transactions after dated transactions. Supplying either bound excludes null-dated transactions. Returns 404 if the account isn't reachable by this key.", "operationId": "list_account_transactions_v1_accounts__account_id__transactions_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "To" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_TransactionRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "transactions:read" ] } }, "/v1/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "description": "Paginated list of transactions scoped to the calling access token's organization allowlist. Optionally filter with inclusive `from` and `to` dates or by `organization_id`. Omit both `from` and `to` to return the full history; results place null-dated transactions after dated transactions. Supplying either bound excludes null-dated transactions. Returns 403 if the organization is out of scope.", "operationId": "list_transactions_v1_transactions_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "To" } }, { "name": "organization_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_TransactionRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`) or the supplied `organization_id` is outside the access token's allowlist (`organization_out_of_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "transactions:read" ] } }, "/v1/payment-methods": { "get": { "tags": [ "Payment Methods" ], "summary": "List payment methods", "description": "Paginated list of stored payment methods belonging to borrowers visible to the calling access token. Filter to one borrower with `party_id`. Only display-safe metadata is returned \u2014 never full card or account numbers.", "operationId": "list_payment_methods_v1_payment_methods_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "party_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Party Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PaymentMethodRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "payment_methods:read" ] } }, "/v1/payment-methods/{payment_method_id}": { "get": { "tags": [ "Payment Methods" ], "summary": "Get a payment method", "description": "Returns a single payment method by ID. Returns 404 if it isn't reachable by this key.", "operationId": "get_payment_method_v1_payment_methods__payment_method_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "payment_method_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payment Method Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "payment_methods:read" ] }, "patch": { "tags": [ "Payment Methods" ], "summary": "Update a payment method", "description": "Updates the editable display fields (`nickname`, `holder_name`). Instrument data is immutable \u2014 to change cards or bank accounts, create a new payment method and deactivate the old one. Returns 404 if the payment method isn't reachable by this key.", "operationId": "update_payment_method_v1_payment_methods__payment_method_id__patch", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "payment_method_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payment Method Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "payment_methods:write" ] }, "delete": { "tags": [ "Payment Methods" ], "summary": "Remove a payment method", "description": "Deactivates the payment method so it can no longer be attached to autopay or payments. The record remains visible (with `is_active: false`) so historical payments stay auditable. Returns 409 if an active or paused autopay schedule still uses it \u2014 cancel the schedule first. Idempotent.", "operationId": "delete_payment_method_v1_payment_methods__payment_method_id__delete", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "payment_method_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payment Method Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "409": { "description": "An active or paused autopay schedule still uses this payment method." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "payment_methods:write" ] } }, "/v1/accounts/{account_id}/payment-methods": { "get": { "tags": [ "Payment Methods" ], "summary": "List an account's payment methods", "description": "Paginated list of stored payment methods belonging to the borrowers on this account \u2014 the methods eligible to be attached to autopay or payments for it. Only active methods are returned; use the top-level list to see deactivated ones. Returns 404 if the account isn't reachable by this key.", "operationId": "list_account_payment_methods_v1_accounts__account_id__payment_methods_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PaymentMethodRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "payment_methods:read" ] } }, "/v1/accounts/{account_id}/autopay": { "get": { "tags": [ "Autopay" ], "summary": "List an account's autopay schedules", "description": "Paginated list of autopay schedules on this account, including paused and cancelled schedules. Returns 404 if the account isn't reachable by this key.", "operationId": "list_account_autopay_v1_accounts__account_id__autopay_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AutopayRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "autopay:read" ] } }, "/v1/autopay": { "post": { "tags": [ "Autopay" ], "summary": "Create an autopay schedule", "description": "Creates a recurring payment schedule for an account using a stored payment method. The first run lands on `start_date`; subsequent runs advance by `frequency_interval` \u00d7 `frequency_unit`. The payment method must belong to a borrower on the account and must be active.", "operationId": "create_autopay_v1_autopay_post", "security": [ { "BearerToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopayCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopayRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "autopay:write" ] }, "get": { "tags": [ "Autopay" ], "summary": "List autopay schedules", "description": "Paginated list of autopay schedules on accounts visible to the calling access token, including paused and cancelled schedules. Filter to one account with `account_id` (returns 404 if the account isn't reachable by this key).", "operationId": "list_autopay_v1_autopay_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AutopayRow_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "autopay:read" ] } }, "/v1/autopay/{autopay_id}": { "get": { "tags": [ "Autopay" ], "summary": "Get an autopay schedule", "description": "Returns a single autopay schedule by ID. Returns 404 if it isn't reachable by this key.", "operationId": "get_autopay_v1_autopay__autopay_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "autopay_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Autopay Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopayRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "autopay:read" ] }, "patch": { "tags": [ "Autopay" ], "summary": "Update an autopay schedule", "description": "Updates the payment method, amount, end date, or pause state of a schedule. Cadence and start date are fixed \u2014 cancel and recreate the schedule to change them. Returns 409 if the schedule has been cancelled.", "operationId": "update_autopay_v1_autopay__autopay_id__patch", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "autopay_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Autopay Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopayUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopayRow" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "409": { "description": "The schedule has been cancelled and can no longer be updated." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "autopay:write" ] }, "delete": { "tags": [ "Autopay" ], "summary": "Cancel an autopay schedule", "description": "Cancels the schedule. The record remains visible (with `status: cancelled`) so payment history stays auditable; cancelled schedules cannot be reactivated. Idempotent.", "operationId": "delete_autopay_v1_autopay__autopay_id__delete", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "autopay_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Autopay Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "autopay:write" ] } }, "/v1/accounts/{account_id}/payments": { "post": { "tags": [ "External Payments" ], "summary": "Post a payment collected outside Monterey", "description": "Records a payment your organization collected itself against one of its accounts. Requires an `Idempotency-Key` header; replaying the same key and body returns the original response. Returns 201 when the payment is posted and 202 when the outcome is still being confirmed (`pending_confirmation`).", "operationId": "post_external_payment_v1_accounts__account_id__payments_post", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentOut" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account or payment not in scope or does not exist." }, "202": { "description": "Outcome not yet confirmed (`pending_confirmation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentOut" } } } }, "409": { "description": "`idempotency_conflict` (key reused with a different body), `idempotency_in_progress`, or `duplicate_external_reference` (your organization already has a payment with this `external_reference`; `payment_id` names it)." }, "422": { "description": "Invalid request, `account_not_payable`, `amount_exceeds_payoff` or a rejected posting (`omega_rejected`, with a `reason`)." }, "503": { "description": "Payment posting is temporarily unavailable." } }, "x-required-scopes": [ "external_payments:write" ] }, "get": { "tags": [ "External Payments" ], "summary": "List payments posted to an account through the API", "description": "Newest first. Lists only payments posted through this API, not every payment on the account. Returns 404 if the account is not reachable by this key.", "operationId": "list_account_external_payments_v1_accounts__account_id__payments_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalPaymentOut_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account or payment not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "external_payments:read" ] } }, "/v1/payments/{payment_id}/reversal": { "post": { "tags": [ "External Payments" ], "summary": "Reverse a payment your organization posted", "description": "Reverses a payment posted through this API. Requires an `Idempotency-Key` header; replaying the same key and body returns the original response. Returns 201 when reversed and 202 when the outcome is still being confirmed (`reversal_pending`).", "operationId": "reverse_external_payment_v1_payments__payment_id__reversal_post", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payment Id" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentReversalCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentOut" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account or payment not in scope or does not exist." }, "202": { "description": "Outcome not yet confirmed (`reversal_pending`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentOut" } } } }, "409": { "description": "`payment_not_reversible` (only `posted` payments can be reversed), `idempotency_conflict` or `idempotency_in_progress`." }, "422": { "description": "Invalid request or a rejected reversal (`omega_rejected`)." }, "503": { "description": "Payment reversal is temporarily unavailable." } }, "x-required-scopes": [ "external_payments:write" ] } }, "/v1/payments": { "get": { "tags": [ "External Payments" ], "summary": "Find payments your organization posted by your own reference", "description": "Looks up payments posted through this API by the `external_reference` you sent. A reference identifies at most one payment that may have posted; earlier attempts that definitely failed are also returned.", "operationId": "find_external_payments_v1_payments_get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "external_reference", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "title": "External Reference" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page.", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's `page.next_cursor`. Omit on the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages.", "title": "Limit" }, "description": "Page size for cursor pagination. Default 100, minimum 1, maximum 1000. Requests above the maximum return 422 \u2014 narrow your page size and use the returned `next_cursor` to walk additional pages." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExternalPaymentOut_" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account or payment not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "The `cursor` is malformed or was tampered with (`invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-required-scopes": [ "external_payments:read" ] } }, "/v1/payments/{payment_id}": { "get": { "tags": [ "External Payments" ], "summary": "Get a payment your organization posted", "description": "Returns 404 for payments posted by other organizations.", "operationId": "get_external_payment_v1_payments__payment_id__get", "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Payment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalPaymentOut" } } } }, "401": { "description": "Missing or invalid access token." }, "403": { "description": "Authenticated token lacks the required scope (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account or payment not in scope or does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scopes": [ "external_payments:read" ] } }, "/v1/payment-methods/cards": { "post": { "tags": [ "Payment Methods" ], "summary": "Create a card payment method", "description": "Create a stored card payment method without sending PAN or CVC to `api.montereyfinancial.app`. Send raw card requests only to `secure-api.montereyfinancial.app`, which forwards tokenized card data through the Basis Theory inbound proxy.", "operationId": "createCardPaymentMethod", "x-required-scopes": [ "payment_methods:write" ], "servers": [ { "url": "https://secure-api.montereyfinancial.app" } ], "security": [ { "BearerToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique client-generated key for this create-card attempt. Re-use the same value only when retrying the same request.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "account_id", "card" ], "not": { "required": [ "billing_address_id", "billing_address" ] }, "properties": { "account_id": { "type": "string" }, "party_id": { "type": "string" }, "cardholder_name": { "type": "string", "maxLength": 255 }, "billing_address_id": { "type": "string" }, "nickname": { "type": "string", "maxLength": 100 }, "set_default": { "type": "boolean", "default": false }, "billing_address": { "type": "object", "additionalProperties": false, "required": [ "address_line1", "city", "state", "postal_code" ], "properties": { "address_line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "minLength": 2, "maxLength": 120 }, "postal_code": { "type": "string", "minLength": 3, "maxLength": 20 }, "country": { "type": "string", "minLength": 2, "maxLength": 120, "default": "US" } } }, "card": { "type": "object", "additionalProperties": false, "required": [ "number", "expiration_month", "expiration_year", "cvc" ], "properties": { "number": { "type": "string", "minLength": 12, "maxLength": 19 }, "expiration_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "expiration_year": { "type": "integer", "minimum": 2000, "maximum": 9999 }, "cvc": { "type": "string", "minLength": 3, "maxLength": 4 } } } }, "description": "Raw card payload accepted only on the secure card-capture hostname. At most one billing-address input may be supplied: use `billing_address_id` to re-use an existing party address, send `billing_address` to use a transient address for this card, or omit both so Monterey falls back to the selected borrower's current billing address." } } } }, "responses": { "400": { "description": "Proxy request shape invalid before tokenization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "201": { "description": "Card payment method created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodRow" } } } }, "401": { "description": "Bearer token invalid, expired, or proxy signature invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated token lacks `payment_methods:write` (`insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Account not found or not visible to the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate card, idempotency conflict, or in-progress retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Billing address selection invalid or request validation failed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "502": { "description": "Gateway tokenization or token-intent conversion failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Gateway-side or token-intent conversion failure. Retry only when `detail.retryable` is true.", "required": [ "detail" ], "properties": { "detail": { "type": "object", "additionalProperties": false, "required": [ "error_code", "retryable" ], "properties": { "error_code": { "type": "string", "enum": [ "gateway_tokenization_failed", "token_intent_conversion_failed" ] }, "retryable": { "type": "boolean" } } } } } } } }, "503": { "description": "Card capture is disabled or upstream capture is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "AccountBorrower": { "properties": { "party_id": { "type": "string", "title": "Party Id", "description": "The borrower's unique party ID." }, "display_name": { "type": "string", "title": "Display Name", "description": "The borrower's display name." }, "role": { "type": "string", "title": "Role", "description": "Open role string. Known values include primary, borrower, co_borrower, and co_signer." }, "is_primary": { "type": "boolean", "title": "Is Primary", "description": "Whether this party is the account's primary borrower." } }, "type": "object", "required": [ "party_id", "display_name", "role", "is_primary" ], "title": "AccountBorrower", "description": "One borrower relationship in an account list response." }, "AccountBorrowerDetail": { "properties": { "party_id": { "type": "string", "title": "Party Id", "description": "The borrower's unique party ID." }, "display_name": { "type": "string", "title": "Display Name", "description": "The borrower's display name." }, "role": { "type": "string", "title": "Role", "description": "Open role string. Known values include primary, borrower, co_borrower, and co_signer." }, "is_primary": { "type": "boolean", "title": "Is Primary", "description": "Whether this party is the account's primary borrower." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "The borrower's first name." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "The borrower's last name." }, "date_of_birth": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Date Of Birth", "description": "The borrower's date of birth." }, "ssn_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ssn Last Four", "description": "Last four SSN digits; the full hash is never exposed." } }, "type": "object", "required": [ "party_id", "display_name", "role", "is_primary" ], "title": "AccountBorrowerDetail", "description": "Borrower identity and role fields returned on account detail." }, "AccountDetailRow": { "properties": { "id": { "type": "string", "title": "Id" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "The organization the account belongs to." }, "contract_id": { "type": "string", "title": "Contract Id" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "Source loan-management account identifier." }, "external_contract_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Contract Id", "description": "Client-supplied contract identifier." }, "status_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Code", "description": "Current account status code." }, "current_balance_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Balance Cents", "description": "Current outstanding balance in cents." }, "past_due_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Past Due Amount Cents", "description": "Amount currently past due in cents." }, "payoff_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payoff Amount Cents", "description": "Current payoff amount in cents." }, "payment_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payment Amount Cents", "description": "Scheduled payment amount in cents." }, "payment_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Frequency", "description": "Scheduled payment cadence." }, "last_payment_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Last Payment At", "description": "Date of the most recent payment." }, "next_payment_due_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Next Payment Due At", "description": "Next scheduled payment due date." }, "payments_made": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payments Made" }, "interest_rate_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interest Rate Bps", "description": "Annual interest rate in basis points." }, "apr_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Apr Bps", "description": "Annual percentage rate in basis points." }, "interest_start_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Interest Start At" }, "days_past_due_30": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 30", "description": "Days in the 1-30 day delinquency bucket." }, "days_past_due_60": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 60", "description": "Days in the 31-60 day delinquency bucket." }, "days_past_due_90": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 90", "description": "Days in the 61-90 day delinquency bucket." }, "nsf_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nsf Count", "description": "Number of non-sufficient-funds events." }, "opened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Opened At", "description": "Date the account opened." }, "closed_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Closed At", "description": "Date the account closed, when applicable." }, "borrowers": { "items": { "$ref": "#/components/schemas/AccountBorrowerDetail" }, "type": "array", "title": "Borrowers", "description": "Enriched borrower parties, with the primary borrower first." }, "accrued_interest_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Accrued Interest Cents", "description": "Accrued unbilled interest in cents." }, "accrued_late_charge_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Accrued Late Charge Cents", "description": "Accrued late charges in cents." }, "last_payment_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Payment Amount Cents", "description": "Most recent payment amount in cents." }, "first_payment_made_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "First Payment Made At", "description": "Date the first payment was received." }, "final_payment_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Final Payment Amount Cents", "description": "Scheduled final payment in cents." }, "last_extension_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Last Extension At", "description": "Date of the most recent term extension." }, "interest_base_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interest Base Days", "description": "Interest day-count convention." }, "over_short_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Over Short Cents", "description": "Over/short adjustment balance in cents." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "contract": { "$ref": "#/components/schemas/ContractSummary" } }, "type": "object", "required": [ "id", "organization_id", "contract_id", "created_at", "updated_at", "contract" ], "title": "AccountDetailRow", "description": "Detailed account snapshot with contract and borrower relationships." }, "AccountRow": { "properties": { "id": { "type": "string", "title": "Id" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "The organization the account belongs to." }, "contract_id": { "type": "string", "title": "Contract Id" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "Source loan-management account identifier." }, "external_contract_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Contract Id", "description": "Client-supplied contract identifier." }, "status_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Code", "description": "Current account status code." }, "current_balance_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Balance Cents", "description": "Current outstanding balance in cents." }, "past_due_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Past Due Amount Cents", "description": "Amount currently past due in cents." }, "payoff_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payoff Amount Cents", "description": "Current payoff amount in cents." }, "payment_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payment Amount Cents", "description": "Scheduled payment amount in cents." }, "payment_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Frequency", "description": "Scheduled payment cadence." }, "last_payment_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Last Payment At", "description": "Date of the most recent payment." }, "next_payment_due_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Next Payment Due At", "description": "Next scheduled payment due date." }, "payments_made": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Payments Made" }, "interest_rate_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interest Rate Bps", "description": "Annual interest rate in basis points." }, "apr_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Apr Bps", "description": "Annual percentage rate in basis points." }, "interest_start_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Interest Start At" }, "days_past_due_30": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 30", "description": "Days in the 1-30 day delinquency bucket." }, "days_past_due_60": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 60", "description": "Days in the 31-60 day delinquency bucket." }, "days_past_due_90": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Past Due 90", "description": "Days in the 61-90 day delinquency bucket." }, "nsf_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nsf Count", "description": "Number of non-sufficient-funds events." }, "opened_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Opened At", "description": "Date the account opened." }, "closed_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Closed At", "description": "Date the account closed, when applicable." }, "borrowers": { "items": { "$ref": "#/components/schemas/AccountBorrower" }, "type": "array", "title": "Borrowers", "description": "Active borrower parties, with the primary borrower first." } }, "type": "object", "required": [ "id", "organization_id", "contract_id" ], "title": "AccountRow", "description": "Thin account-list shape with role-carrying borrowers." }, "AddressRow": { "properties": { "party_address_id": { "type": "string", "title": "Party Address Id", "description": "The party-address relationship ID for this address row." }, "type": { "type": "string", "title": "Type", "description": "Address usage type, such as home or mailing." }, "is_current": { "type": "boolean", "title": "Is Current", "description": "Whether this is a current address." }, "line_1": { "type": "string", "title": "Line 1", "description": "Primary street-address line." }, "line_2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line 2", "description": "Secondary street-address line." }, "city": { "type": "string", "title": "City", "description": "City or locality." }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State", "description": "State, province, or subdivision code, where the country uses one. Null for countries with no subdivision in an address." }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code", "description": "Postal code as provided by the source, in the local format. Null for countries that do not use postal codes." }, "country": { "type": "string", "title": "Country", "description": "Country code or name stored for the address." }, "effective_from": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Effective From", "description": "Date this party-address relationship began." }, "effective_until": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Effective Until", "description": "Date this party-address relationship ended." } }, "type": "object", "required": [ "party_address_id", "type", "is_current", "line_1", "city", "country" ], "title": "AddressRow", "description": "A current client-safe address associated with a person." }, "AutopayCreate": { "properties": { "account_id": { "type": "string", "title": "Account Id", "description": "The account this schedule pays toward." }, "payment_method_id": { "type": "string", "title": "Payment Method Id", "description": "The stored payment method to charge on each run." }, "amount_cents": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Amount Cents", "description": "Amount to charge per run, in integer cents." }, "frequency_unit": { "type": "string", "enum": [ "day", "week", "month", "year" ], "title": "Frequency Unit", "description": "Unit of the recurrence interval." }, "frequency_interval": { "type": "integer", "minimum": 1.0, "title": "Frequency Interval", "description": "Number of units between runs. Defaults to 1.", "default": 1 }, "start_date": { "type": "string", "format": "date", "title": "Start Date", "description": "Date of the first scheduled run." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "Last date a run may occur. Omit for an open-ended schedule." }, "anchor_day": { "anyOf": [ { "type": "integer", "maximum": 31.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Anchor Day", "description": "Day of month (1-31) to pin runs to, for month/year cadences." }, "anchor_month": { "anyOf": [ { "type": "integer", "maximum": 12.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Anchor Month", "description": "Month (1-12) to pin runs to, for yearly cadences." } }, "additionalProperties": false, "type": "object", "required": [ "account_id", "payment_method_id", "amount_cents", "frequency_unit", "start_date" ], "title": "AutopayCreate", "description": "Request body for creating an autopay schedule. The payment\nmethod must belong to a borrower on the target account." }, "AutopayRow": { "properties": { "id": { "type": "string", "title": "Id" }, "account_id": { "type": "string", "title": "Account Id", "description": "The account this schedule pays toward." }, "payment_method_id": { "type": "string", "title": "Payment Method Id", "description": "The stored payment method charged on each run." }, "amount_cents": { "type": "integer", "title": "Amount Cents", "description": "Amount charged per run, in integer cents." }, "frequency_unit": { "type": "string", "title": "Frequency Unit", "description": "Unit of the recurrence interval. One of: day, week, month, year." }, "frequency_interval": { "type": "integer", "title": "Frequency Interval", "description": "Number of units between runs (e.g. 2 + week = every two weeks)." }, "anchor_day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Anchor Day", "description": "Day of month (1-31) runs are pinned to, for month/year cadences. Clamped to the last day of shorter months." }, "anchor_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Anchor Month", "description": "Month (1-12) runs are pinned to, for yearly cadences." }, "start_date": { "type": "string", "format": "date", "title": "Start Date", "description": "Date of the first scheduled run." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "Last date a run may occur. Null for open-ended schedules." }, "next_run_date": { "type": "string", "format": "date", "title": "Next Run Date", "description": "Date the next charge is scheduled to run." }, "status": { "type": "string", "title": "Status", "description": "Schedule state. One of: active, paused, cancelled, expired." }, "cancelled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Cancelled At", "description": "When the schedule was cancelled. Null unless cancelled." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "account_id", "payment_method_id", "amount_cents", "frequency_unit", "frequency_interval", "start_date", "next_run_date", "status", "created_at", "updated_at" ], "title": "AutopayRow", "description": "A recurring payment schedule tying an account to a stored\npayment method." }, "AutopayUpdate": { "properties": { "payment_method_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method Id", "description": "Switch the schedule to a different stored payment method. Must belong to a borrower on the schedule's account." }, "amount_cents": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Amount Cents", "description": "New per-run amount, in integer cents." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "New last date a run may occur." }, "status": { "anyOf": [ { "type": "string", "enum": [ "active", "paused" ] }, { "type": "null" } ], "title": "Status", "description": "Pause or resume the schedule. Cancelling is done via DELETE." } }, "additionalProperties": false, "type": "object", "title": "AutopayUpdate", "description": "Editable autopay fields. Cadence and start date are fixed once\ncreated \u2014 cancel and recreate the schedule to change them." }, "ContactMethodRow": { "properties": { "type": { "type": "string", "title": "Type", "description": "Contact channel, such as phone or email." }, "value": { "type": "string", "title": "Value", "description": "Dialable phone number or email address." }, "extension": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extension", "description": "Phone extension, when applicable." }, "usage_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Type", "description": "Usage classification such as mobile or home." }, "is_primary": { "type": "boolean", "title": "Is Primary", "description": "Whether this is the preferred method for its type." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether this contact method can currently be used." }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Verified At", "description": "When ownership was last verified." }, "line_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Line Type", "description": "Detected phone line type, when available." }, "carrier_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Carrier Name", "description": "Detected phone carrier, when available." }, "is_textable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Textable", "description": "Whether the phone line can receive SMS." }, "deactivated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Deactivated At", "description": "When the carrier reported the line inactive." } }, "type": "object", "required": [ "type", "value", "is_primary", "is_active" ], "title": "ContactMethodRow", "description": "An active client-safe phone or email contact method." }, "ContractSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "cash_price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cash Price Cents" }, "original_term": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Original Term", "description": "Original number of payment periods." }, "original_payment_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Original Payment Amount Cents" }, "original_interest_rate_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Original Interest Rate Bps" }, "original_apr_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Original Apr Bps" }, "originated_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Originated At" }, "first_payment_due_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "First Payment Due At" } }, "type": "object", "required": [ "id" ], "title": "ContractSummary", "description": "Originated-loan facts. Returned nested on AccountDetailRow." }, "ErrorBody": { "properties": { "error_code": { "type": "string", "title": "Error Code" } }, "type": "object", "required": [ "error_code" ], "title": "ErrorBody", "description": "Standard error body. Branch on `error_code`." }, "ErrorResponse": { "properties": { "detail": { "$ref": "#/components/schemas/ErrorBody" } }, "type": "object", "required": [ "detail" ], "title": "ErrorResponse", "description": "Standard error envelope. Branch on `detail.error_code`." }, "ExternalCardBrand": { "type": "string", "enum": [ "visa", "mastercard", "amex", "discover", "diners" ], "title": "ExternalCardBrand", "description": "Card network, required when `payment_method` is `card`." }, "ExternalPaymentCreate": { "properties": { "amount_cents": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Amount Cents", "description": "Payment amount, in integer cents." }, "payment_method": { "$ref": "#/components/schemas/ExternalPaymentMethod" }, "check_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Check Number", "description": "Required for `check`, `money_order` and `cashiers_check`; not allowed for other methods." }, "card_brand": { "anyOf": [ { "$ref": "#/components/schemas/ExternalCardBrand" }, { "type": "null" } ], "description": "Required for `card`; not allowed for other methods." }, "external_reference": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "External Reference", "description": "Your own reference for this payment." }, "memo": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Memo", "description": "Free-text note." } }, "additionalProperties": false, "type": "object", "required": [ "amount_cents", "payment_method" ], "title": "ExternalPaymentCreate", "description": "Request body for recording a payment collected outside Monterey." }, "ExternalPaymentMethod": { "type": "string", "enum": [ "cash", "check", "card", "money_order", "cashiers_check" ], "title": "ExternalPaymentMethod", "description": "How the payment was collected." }, "ExternalPaymentOut": { "properties": { "payment_id": { "type": "string", "title": "Payment Id", "description": "Monterey payment ID." }, "account_id": { "type": "string", "title": "Account Id", "description": "The account the payment was posted to." }, "amount_cents": { "type": "integer", "title": "Amount Cents", "description": "Payment amount, in integer cents." }, "payment_method": { "type": "string", "title": "Payment Method", "description": "How the payment was collected." }, "check_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Check Number", "description": "Check number, when applicable." }, "status": { "type": "string", "title": "Status", "description": "`pending`, `posted`, `pending_confirmation`, `reversal_pending`, `reversed` or `failed`." }, "effective_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Effective Date", "description": "Date the payment applies." }, "external_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Reference", "description": "Your own reference." }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memo", "description": "Free-text note." }, "reference_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reference Number", "description": "Reference number of the posted payment." }, "posted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Posted At", "description": "When it was posted." }, "reversal": { "anyOf": [ { "$ref": "#/components/schemas/ReversalOut" }, { "type": "null" } ], "description": "Reversal details; null unless the payment was reversed." } }, "type": "object", "required": [ "payment_id", "account_id", "amount_cents", "payment_method", "check_number", "status", "effective_date", "external_reference", "memo", "reference_number", "posted_at", "reversal" ], "title": "ExternalPaymentOut", "description": "A payment an organization posted to one of its accounts." }, "ExternalPaymentReversalCreate": { "properties": { "reason": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Reason", "description": "Why the payment is reversed." }, "is_nsf": { "type": "boolean", "title": "Is Nsf", "description": "Reverse as NSF (returned funds).", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "reason" ], "title": "ExternalPaymentReversalCreate", "description": "Request body for reversing a payment your organization posted." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError", "description": "Parameter-validation error (HTTP 422). `detail` lists each violated constraint with its location, message, and type." }, "OrganizationRow": { "properties": { "id": { "type": "string", "title": "Id", "description": "The organization's unique ID." }, "display_name": { "type": "string", "title": "Display Name", "description": "The organization's display name." }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name", "description": "The full legal entity name." }, "dba_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dba Name", "description": "The doing-business-as name." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the organization is active." } }, "type": "object", "required": [ "id", "display_name", "is_active" ], "title": "OrganizationRow", "description": "An organization visible to the authenticated client credential." }, "PageMeta": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque token to pass as ?cursor= to fetch the next page." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True if more rows exist past this page." }, "limit": { "type": "integer", "title": "Limit", "description": "Echo of the resolved page size." } }, "type": "object", "required": [ "has_more", "limit" ], "title": "PageMeta", "description": "Pagination envelope on list responses. `next_cursor` is non-null when more rows exist \u2014 pass it back as `cursor` to continue." }, "Page_AccountRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[AccountRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_AutopayRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AutopayRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[AutopayRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_ExternalPaymentOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ExternalPaymentOut" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[ExternalPaymentOut]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_OrganizationRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/OrganizationRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[OrganizationRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_PaymentMethodRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PaymentMethodRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[PaymentMethodRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_PersonRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PersonRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[PersonRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "Page_TransactionRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TransactionRow" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" } }, "type": "object", "required": [ "items", "page" ], "title": "Page[TransactionRow]", "description": "A page of results: `items` plus a `page` pagination envelope." }, "PaymentMethodRow": { "properties": { "id": { "type": "string", "title": "Id" }, "party_id": { "type": "string", "title": "Party Id", "description": "The person (borrower) this payment method belongs to." }, "instrument_type": { "type": "string", "title": "Instrument Type", "description": "Kind of instrument. One of: card, bank_account, wallet." }, "holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Holder Name", "description": "Name of the card or account holder." }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nickname", "description": "Borrower-chosen label for this payment method." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "False once the payment method has been removed. Inactive methods cannot be attached to autopay or payments." }, "last_four": { "type": "string", "title": "Last Four", "description": "Last four digits of the card or account number." }, "card_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Card Brand", "description": "Card network (e.g. visa, mastercard). Cards only." }, "card_exp_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Card Exp Month", "description": "Card expiration month (1-12). Cards only." }, "card_exp_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Card Exp Year", "description": "Card expiration year (four digits). Cards only." }, "bank_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Name", "description": "Bank name. Bank accounts only." }, "bank_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Account Type", "description": "Bank account type (e.g. checking, savings). Bank accounts only." }, "wallet_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Type", "description": "Wallet provider (e.g. apple_pay, google_pay). Wallets only." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "party_id", "instrument_type", "is_active", "last_four", "created_at", "updated_at" ], "title": "PaymentMethodRow", "description": "A stored payment instrument (card, bank account, or wallet)\nbelonging to a borrower. Carries display-safe metadata only \u2014\nnever full card or account numbers." }, "PaymentMethodUpdate": { "properties": { "nickname": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Nickname", "description": "Borrower-chosen label for this payment method." }, "holder_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Holder Name", "description": "Name of the card or account holder." } }, "additionalProperties": false, "type": "object", "title": "PaymentMethodUpdate", "description": "Editable payment-method fields. Instrument data (type, digits,\nexpiry, bank, wallet) is immutable \u2014 requests naming any other\nfield are rejected with a 422." }, "PersonDetailRow": { "properties": { "id": { "type": "string", "title": "Id", "description": "The person's unique party ID." }, "display_name": { "type": "string", "title": "Display Name", "description": "The person's client-facing display name." }, "first_name": { "type": "string", "title": "First Name", "description": "The person's first name." }, "last_name": { "type": "string", "title": "Last Name", "description": "The person's last name." }, "date_of_birth": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Date Of Birth", "description": "The person's date of birth." }, "ssn_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ssn Last Four", "description": "Last four SSN digits; the full hash is never exposed." }, "primary_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Phone", "description": "Preferred active phone, or newest active phone." }, "primary_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Email", "description": "Preferred active email, or newest active email." }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preferred Language", "description": "Preferred language code." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the person is active." }, "contact_methods": { "items": { "$ref": "#/components/schemas/ContactMethodRow" }, "type": "array", "title": "Contact Methods", "description": "Active client-safe phone and email methods." }, "addresses": { "items": { "$ref": "#/components/schemas/AddressRow" }, "type": "array", "title": "Addresses", "description": "Current client-safe addresses." } }, "type": "object", "required": [ "id", "display_name", "first_name", "last_name", "is_active" ], "title": "PersonDetailRow", "description": "Detailed person record with contact methods and current addresses." }, "PersonRow": { "properties": { "id": { "type": "string", "title": "Id", "description": "The person's unique party ID." }, "display_name": { "type": "string", "title": "Display Name", "description": "The person's client-facing display name." }, "first_name": { "type": "string", "title": "First Name", "description": "The person's first name." }, "last_name": { "type": "string", "title": "Last Name", "description": "The person's last name." }, "date_of_birth": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Date Of Birth", "description": "The person's date of birth." }, "ssn_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ssn Last Four", "description": "Last four SSN digits; the full hash is never exposed." }, "primary_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Phone", "description": "Preferred active phone, or newest active phone." }, "primary_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Email", "description": "Preferred active email, or newest active email." }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preferred Language", "description": "Preferred language code." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the person is active." } }, "type": "object", "required": [ "id", "display_name", "first_name", "last_name", "is_active" ], "title": "PersonRow", "description": "Thin person record returned by paginated list endpoints." }, "RateLimitErrorBody": { "properties": { "error_code": { "type": "string", "const": "rate_limited", "title": "Error Code" }, "bucket": { "type": "string", "enum": [ "api", "token" ], "title": "Bucket" }, "limit_per_minute": { "type": "integer", "title": "Limit Per Minute" }, "burst_capacity": { "type": "integer", "title": "Burst Capacity" }, "retry_after_seconds": { "type": "integer", "title": "Retry After Seconds" }, "reset_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reset At" } }, "type": "object", "required": [ "error_code", "bucket", "limit_per_minute", "burst_capacity", "retry_after_seconds", "reset_at" ], "title": "RateLimitErrorBody", "description": "Self-tuning details returned after a rate-limit denial." }, "RateLimitErrorResponse": { "properties": { "detail": { "$ref": "#/components/schemas/RateLimitErrorBody" } }, "type": "object", "required": [ "detail" ], "title": "RateLimitErrorResponse", "description": "Rate-limit error envelope returned with HTTP 429." }, "ReversalOut": { "properties": { "reversed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Reversed At", "description": "When it was reversed." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Reason given for the reversal." }, "is_nsf": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Nsf", "description": "Whether it was reversed as NSF." }, "reference_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reference Number", "description": "Reference number of the reversal." }, "reversed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reversed By", "description": "Who reversed the payment." } }, "type": "object", "required": [ "reversed_at", "reason", "is_nsf", "reference_number", "reversed_by" ], "title": "ReversalOut", "description": "Reversal details of a payment that has been (or is being) reversed." }, "TokenRequest": { "properties": { "grant_type": { "type": "string", "title": "Grant Type", "description": "Must be `client_credentials`." }, "client_id": { "type": "string", "title": "Client Id", "description": "API key prefix shown in the client portal." }, "client_secret": { "type": "string", "title": "Client Secret", "description": "API key plaintext shown once at creation." } }, "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "title": "TokenRequest", "description": "Client-credentials request using a portal-issued API key." }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type" }, "expires_in": { "type": "integer", "title": "Expires In" } }, "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "title": "TokenResponse", "description": "Short-lived bearer token returned by a successful exchange." }, "TransactionRow": { "properties": { "transaction_id": { "type": "string", "title": "Transaction Id", "description": "Canonical transaction ULID." }, "organization_id": { "type": "string", "title": "Organization Id", "description": "The organization this transaction belongs to." }, "account_id": { "type": "string", "title": "Account Id", "description": "Account ULID." }, "type": { "type": "string", "title": "Type", "description": "Transaction category. One of: payment, adjustment, fee, refund." }, "amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount Cents", "description": "Gross signed transaction amount in integer cents. Positive = money in, negative = money out. May be null on some pre-2017 rows." }, "effective_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Effective At", "description": "Accounting-effective date of the transaction (ISO 8601)." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Transaction status flag. One of: 'NSF', 'void', 'reversed', or null for normal transactions." }, "principal_applied_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Principal Applied Cents", "description": "Portion of amount applied to principal, in integer cents. For complete payments, this and the other allocation fields sum to the absolute gross amount_cents. May be null on some pre-2017 rows." }, "interest_applied_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Interest Applied Cents", "description": "Portion of amount applied to interest, in integer cents. May be null on some pre-2017 rows." }, "late_fee_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Late Fee Cents", "description": "Portion of amount applied to late fees, in integer cents. May be null on some pre-2017 rows." }, "nsf_fee_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nsf Fee Cents", "description": "Portion of amount applied to NSF fees, in integer cents. May be null on some pre-2017 rows." }, "service_fee_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Service Fee Cents", "description": "Portion of amount applied to service fees, in integer cents. May be null on some pre-2017 rows." }, "other_fee_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Other Fee Cents", "description": "Portion of amount applied to other fees, in integer cents. May be null on some pre-2017 rows." }, "excess_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Excess Cents", "description": "Excess payment amount in integer cents. The fee-category fields (principal, interest, late_fee, nsf_fee, service_fee, other_fee, excess) sum to the absolute gross amount_cents for complete payments. May be null on some pre-2017 rows." }, "check_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Check Number", "description": "Check or instrument number associated with this payment, if applicable." }, "cancelled_at": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Cancelled At", "description": "Reversal date if this transaction was cancelled or reversed. Exclude rows where this is non-null from running totals." } }, "type": "object", "required": [ "transaction_id", "organization_id", "account_id", "type" ], "title": "TransactionRow", "description": "A money-movement event on an account (payment, adjustment, fee). Carries `organization_id` for cross-org grouping.", "examples": [ { "account_id": "01J9ZQ8H7Z3K8M4N5P6Q7R8S9T", "amount_cents": 25000, "check_number": "1042", "effective_at": "2026-04-15", "excess_cents": 0, "interest_applied_cents": 6500, "late_fee_cents": 0, "nsf_fee_cents": 0, "organization_id": "01J8AB2C3D4E5F6G7H8J9K0L1M", "other_fee_cents": 0, "principal_applied_cents": 18500, "service_fee_cents": 0, "transaction_id": "01JAQZ7G8H9J0K1L2M3N4P5Q6R", "type": "payment" } ] }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError", "description": "A single parameter-validation failure: `loc` is the path to the offending input, `msg` is human-readable, and `type` is the rule that failed." } }, "securitySchemes": { "BearerToken": { "type": "http", "description": "Short-lived access token minted by POST /v1/oauth/token.", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "Authentication", "description": "Exchange API keys for access tokens." }, { "name": "Organizations", "description": "Organizations visible to the API key." }, { "name": "Persons", "description": "Borrowers visible through in-scope accounts." }, { "name": "Accounts", "description": "Servicing accounts and identifier lookups." }, { "name": "Transactions", "description": "Account money-movement history." }, { "name": "Payment Methods", "description": "Stored payment instruments." }, { "name": "Autopay", "description": "Recurring payment schedules." } ], "security": [ { "BearerToken": [] } ] }