diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..3a083b8 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "methodfi-docs": { + "type": "http", + "url": "https://docs.methodfi.com/mcp" + } + } +} \ No newline at end of file diff --git a/README.md b/README.md index d7cb837..d5cd472 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Method API OpenAPI Specification -Machine-readable [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) specification for the [Method API](https://docs.methodfi.com). Targets API version `2025-12-01`. +Machine-readable [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) specification for the [Method API](https://docs.methodfi.com). Targets API version `2026-03-30`. ## Directory Structure diff --git a/latest/openapi.bundled.json b/latest/openapi.bundled.json index ecd2e6f..d0a9ba8 100644 --- a/latest/openapi.bundled.json +++ b/latest/openapi.bundled.json @@ -169,10 +169,18 @@ "name": "Payment Reversals", "description": "Reversals for payments" }, + { + "name": "Preauth", + "description": "PreauthSignals transaction success assessments" + }, { "name": "Reports", "description": "Downloadable reports" }, + { + "name": "Report Schedules", + "description": "Recurring report generation schedules" + }, { "name": "Secrets", "description": "Secure secret storage" @@ -988,7 +996,7 @@ "post": { "operationId": "createAccountAttribute", "summary": "Create an account attribute", - "description": "Creates a new attribute request for the specified account.", + "description": "Creates a new attribute request to compute the account's attributes. The attributes returned depend on the account's liability type. This operation is asynchronous: the response returns immediately with `status` set and `attributes` null, and the final result is available by polling the retrieve endpoint or subscribing to webhooks.", "tags": [ "Account Attributes" ], @@ -1008,6 +1016,21 @@ "$ref": "#/components/parameters/AccountIdParam" } ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountAttributeCreateRequest" + }, + "example": { + "bundles": [ + "statement" + ] + } + } + } + }, "responses": { "200": { "description": "The newly created account attribute.", @@ -7267,130 +7290,13 @@ } } }, - "/reports": { - "post": { - "operationId": "createReport", - "summary": "Create a report", - "description": "Creates a new report of the specified type. The report will be generated asynchronously and can be downloaded once its status is `completed`.", - "tags": [ - "Reports" - ], - "security": [ - { - "SecretKey": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/method_version" - }, - { - "$ref": "#/components/parameters/idempotency_key" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ReportCreateRequest" - } - } - } - }, - "responses": { - "200": { - "description": "The newly created report.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ReportResponse" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "422": { - "$ref": "#/components/responses/UnprocessableEntity" - }, - "429": { - "$ref": "#/components/responses/RateLimited" - }, - "500": { - "$ref": "#/components/responses/InternalError" - } - } - } - }, - "/reports/{reportId}": { - "get": { - "operationId": "retrieveReport", - "summary": "Retrieve a report", - "description": "Returns a single report by its identifier. Use this to check the status of a report before downloading.", - "tags": [ - "Reports" - ], - "security": [ - { - "SecretKey": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/method_version" - }, - { - "name": "reportId", - "in": "path", - "required": true, - "description": "Unique identifier for the report.", - "schema": { - "type": "string", - "pattern": "^rpt_\\w+$" - } - } - ], - "responses": { - "200": { - "description": "The requested report.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ReportResponse" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "429": { - "$ref": "#/components/responses/RateLimited" - }, - "500": { - "$ref": "#/components/responses/InternalError" - } - } - } - }, - "/reports/{reportId}/download": { + "/preauth": { "get": { - "operationId": "downloadReport", - "summary": "Download a report", - "description": "Returns the completed report as a CSV file attachment.", + "operationId": "listPreauths", + "summary": "List PreauthSignals assessments", + "description": "Returns a paginated list of PreauthSignals assessments for the team.", "tags": [ - "Reports" + "Preauth" ], "security": [ { @@ -7402,84 +7308,24 @@ "$ref": "#/components/parameters/method_version" }, { - "name": "reportId", - "in": "path", - "required": true, - "description": "Unique identifier for the report.", - "schema": { - "type": "string", - "pattern": "^rpt_\\w+$" - } - } - ], - "responses": { - "200": { - "description": "CSV report content.", - "headers": { - "Content-Disposition": { - "description": "Attachment filename for the downloaded report.", - "schema": { - "type": "string" - } - } - }, - "content": { - "text/csv": { - "schema": { - "type": "string", - "format": "binary" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" - }, - "404": { - "$ref": "#/components/responses/NotFound" - }, - "429": { - "$ref": "#/components/responses/RateLimited" + "$ref": "#/components/parameters/PageParam" }, - "500": { - "$ref": "#/components/responses/InternalError" - } - } - } - }, - "/secrets": { - "get": { - "operationId": "listSecrets", - "summary": "List all secrets", - "description": "Returns a paginated list of secrets. Secret values are never returned.", - "tags": [ - "Secrets" - ], - "security": [ - { - "SecretKey": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/method_version" + "$ref": "#/components/parameters/PageLimitParam" }, { - "$ref": "#/components/parameters/PageParam" + "$ref": "#/components/parameters/PageCursorParam" }, { - "$ref": "#/components/parameters/PageLimitParam" + "$ref": "#/components/parameters/FromDateParam" }, { - "$ref": "#/components/parameters/PageCursorParam" + "$ref": "#/components/parameters/ToDateParam" } ], "responses": { "200": { - "description": "A list of secrets.", + "description": "A list of PreauthSignals assessments.", "headers": { "Pagination-Page": { "description": "Current page number.", @@ -7527,7 +7373,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SecretListResponse" + "$ref": "#/components/schemas/PreauthListResponse" } } } @@ -7550,11 +7396,11 @@ } }, "post": { - "operationId": "createSecret", - "summary": "Create a secret", - "description": "Stores a new secret value securely.", + "operationId": "createPreauth", + "summary": "Create PreauthSignals assessment", + "description": "Computes a PreauthSignals assessment for a given card or account. Provide either an `account_id` for an authenticated Method Account, or a `card` object with raw card identifiers. Exactly one of the two is required; supplying both returns a `400` error. Optionally include `purchase` context to improve the prediction.", "tags": [ - "Secrets" + "Preauth" ], "security": [ { @@ -7574,18 +7420,45 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SecretCreateRequest" + "$ref": "#/components/schemas/PreauthCreateRequest" + }, + "examples": { + "by_card": { + "summary": "Assess raw card identifiers with purchase context", + "value": { + "card": { + "bin6": "411111", + "last4": "1234", + "first_name": "Jane", + "last_name": "Doe", + "phone": "+15555555555", + "zip": "10001" + }, + "purchase": { + "amount": 9999, + "mcc": "4511", + "ip_address": "203.0.113.42", + "txn_time": "2026-05-28T14:00:00Z" + } + } + }, + "by_account": { + "summary": "Assess an authenticated Method Account", + "value": { + "account_id": "acc_4m9amk4KFiaQX" + } + } } } } }, "responses": { "200": { - "description": "The created secret.", + "description": "The PreauthSignals assessment.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SecretResponse" + "$ref": "#/components/schemas/PreauthResponse" } } } @@ -7611,13 +7484,13 @@ } } }, - "/secrets/{id}": { + "/preauth/{preauthId}": { "get": { - "operationId": "retrieveSecret", - "summary": "Retrieve a secret", - "description": "Returns a single secret by its identifier. The secret value is never returned.", + "operationId": "retrievePreauth", + "summary": "Retrieve a PreauthSignals assessment", + "description": "Returns a single PreauthSignals assessment by its identifier.", "tags": [ - "Secrets" + "Preauth" ], "security": [ { @@ -7629,23 +7502,23 @@ "$ref": "#/components/parameters/method_version" }, { - "name": "id", + "name": "preauthId", "in": "path", "required": true, - "description": "Unique identifier for the secret.", + "description": "Unique identifier for the PreauthSignals assessment.", "schema": { "type": "string", - "pattern": "^sec_\\w+$" + "pattern": "^preauth_\\w+$" } } ], "responses": { "200": { - "description": "The requested secret.", + "description": "The requested PreauthSignals assessment.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SecretResponse" + "$ref": "#/components/schemas/PreauthResponse" } } } @@ -7669,13 +7542,15 @@ "$ref": "#/components/responses/InternalError" } } - }, - "delete": { - "operationId": "deleteSecret", - "summary": "Delete a secret", - "description": "Deletes a secret.", + } + }, + "/reports": { + "post": { + "operationId": "createReport", + "summary": "Create a report", + "description": "Creates a new report of the specified type. The report will be generated asynchronously and can be downloaded once its status is `completed`.", "tags": [ - "Secrets" + "Reports" ], "security": [ { @@ -7688,9 +7563,751 @@ }, { "$ref": "#/components/parameters/idempotency_key" - }, - { - "name": "id", + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "The newly created report.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntity" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/reports/{reportId}": { + "get": { + "operationId": "retrieveReport", + "summary": "Retrieve a report", + "description": "Returns a single report by its identifier. Use this to check the status of a report before downloading.", + "tags": [ + "Reports" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "name": "reportId", + "in": "path", + "required": true, + "description": "Unique identifier for the report.", + "schema": { + "type": "string", + "pattern": "^rpt_\\w+$" + } + } + ], + "responses": { + "200": { + "description": "The requested report.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/reports/{reportId}/download": { + "get": { + "operationId": "downloadReport", + "summary": "Download a report", + "description": "Returns the completed report as a CSV file attachment.", + "tags": [ + "Reports" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "name": "reportId", + "in": "path", + "required": true, + "description": "Unique identifier for the report.", + "schema": { + "type": "string", + "pattern": "^rpt_\\w+$" + } + } + ], + "responses": { + "200": { + "description": "CSV report content.", + "headers": { + "Content-Disposition": { + "description": "Attachment filename for the downloaded report.", + "schema": { + "type": "string" + } + } + }, + "content": { + "text/csv": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/report_schedules": { + "get": { + "operationId": "listReportSchedules", + "summary": "List report schedules", + "description": "Returns the report schedules configured for the team.", + "tags": [ + "Report Schedules" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + } + ], + "responses": { + "200": { + "description": "A list of report schedules.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleListResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "post": { + "operationId": "createReportSchedule", + "summary": "Create a report schedule", + "description": "Creates a new active report schedule for a single supported Report `type`. Once created, the schedule runs on Method's standard cadence for that type. A team may have only one active schedule per `type`; creating a duplicate returns an error.", + "tags": [ + "Report Schedules" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/idempotency_key" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleCreateRequest" + }, + "example": { + "type": "payments.created.previous_day", + "email_recipients": [ + "reports@example.com" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The newly created report schedule.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntity" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/report_schedules/{reportScheduleId}": { + "get": { + "operationId": "retrieveReportSchedule", + "summary": "Retrieve a report schedule", + "description": "Returns the report schedule associated with the identifier.", + "tags": [ + "Report Schedules" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "name": "reportScheduleId", + "in": "path", + "required": true, + "description": "Unique identifier for the report schedule.", + "schema": { + "type": "string", + "pattern": "^rpt_sch_\\w+$" + } + } + ], + "responses": { + "200": { + "description": "The requested report schedule.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "put": { + "operationId": "updateReportSchedule", + "summary": "Update a report schedule", + "description": "Updates the `email_recipients` of an existing report schedule. The schedule `type` and cadence cannot be changed.", + "tags": [ + "Report Schedules" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/idempotency_key" + }, + { + "name": "reportScheduleId", + "in": "path", + "required": true, + "description": "Unique identifier for the report schedule.", + "schema": { + "type": "string", + "pattern": "^rpt_sch_\\w+$" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleUpdateRequest" + }, + "example": { + "email_recipients": [ + "ops@example.com", + "reports@example.com" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The updated report schedule.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReportScheduleResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntity" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "delete": { + "operationId": "deleteReportSchedule", + "summary": "Delete a report schedule", + "description": "Deletes a report schedule, stopping all future runs. Returns an empty response.", + "tags": [ + "Report Schedules" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/idempotency_key" + }, + { + "name": "reportScheduleId", + "in": "path", + "required": true, + "description": "Unique identifier for the report schedule.", + "schema": { + "type": "string", + "pattern": "^rpt_sch_\\w+$" + } + } + ], + "responses": { + "200": { + "description": "Report schedule deleted successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "success", + "data", + "message" + ], + "properties": { + "success": { + "type": "boolean", + "example": true + }, + "data": { + "type": "null", + "example": null + }, + "message": { + "type": [ + "null", + "string" + ], + "example": null + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntity" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/secrets": { + "get": { + "operationId": "listSecrets", + "summary": "List all secrets", + "description": "Returns a paginated list of secrets. Secret values are never returned.", + "tags": [ + "Secrets" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/PageParam" + }, + { + "$ref": "#/components/parameters/PageLimitParam" + }, + { + "$ref": "#/components/parameters/PageCursorParam" + } + ], + "responses": { + "200": { + "description": "A list of secrets.", + "headers": { + "Pagination-Page": { + "description": "Current page number.", + "schema": { + "type": "integer" + } + }, + "Pagination-Page-Count": { + "description": "Total number of pages.", + "schema": { + "type": "integer" + } + }, + "Pagination-Page-Limit": { + "description": "Number of items per page.", + "schema": { + "type": "integer" + } + }, + "Pagination-Total-Count": { + "description": "Total number of items across all pages.", + "schema": { + "type": "integer" + } + }, + "Pagination-Page-Cursor-Prev": { + "description": "Cursor for the previous page, if available.", + "schema": { + "type": [ + "string", + "null" + ] + } + }, + "Pagination-Page-Cursor-Next": { + "description": "Cursor for the next page, if available.", + "schema": { + "type": [ + "string", + "null" + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretListResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "post": { + "operationId": "createSecret", + "summary": "Create a secret", + "description": "Stores a new secret value securely.", + "tags": [ + "Secrets" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/idempotency_key" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "The created secret.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "422": { + "$ref": "#/components/responses/UnprocessableEntity" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/secrets/{id}": { + "get": { + "operationId": "retrieveSecret", + "summary": "Retrieve a secret", + "description": "Returns a single secret by its identifier. The secret value is never returned.", + "tags": [ + "Secrets" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "name": "id", + "in": "path", + "required": true, + "description": "Unique identifier for the secret.", + "schema": { + "type": "string", + "pattern": "^sec_\\w+$" + } + } + ], + "responses": { + "200": { + "description": "The requested secret.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "delete": { + "operationId": "deleteSecret", + "summary": "Delete a secret", + "description": "Deletes a secret.", + "tags": [ + "Secrets" + ], + "security": [ + { + "SecretKey": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + }, + { + "$ref": "#/components/parameters/idempotency_key" + }, + { + "name": "id", "in": "path", "required": true, "description": "Unique identifier for the secret.", @@ -9276,6 +9893,64 @@ } } }, + "/opal/events": { + "get": { + "operationId": "listOpalEvents", + "summary": "List Opal session events", + "description": "Returns the events recorded during the Opal session associated with the authenticated token. Event types follow the `..` pattern.", + "tags": [ + "Opal" + ], + "security": [ + { + "OpalToken": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/method_version" + } + ], + "responses": { + "200": { + "description": "The events recorded for the current Opal session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpalEventListResponse" + }, + "example": { + "success": true, + "data": [ + { + "type": "card_connect.flow.started", + "mode": "card_connect", + "object": "flow", + "action": "started", + "timestamp": "2026-03-14T19:02:11.482Z", + "data": null + } + ], + "message": null + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, "/elements/token": { "post": { "operationId": "elementsCreateToken", @@ -13728,6 +14403,29 @@ } ] }, + "AccountAttributeCreateRequest": { + "type": "object", + "description": "Optional request body for creating an account attribute request. Both fields are optional; a request with no body computes the full set of attributes for the account type. Provide `requested_attributes`, `bundles`, or both to scope the response's `attributes` object to just the requested attributes.", + "properties": { + "requested_attributes": { + "type": "array", + "description": "A list of specific attribute names to compute. When omitted, the full set of attributes for the account type is returned.", + "items": { + "type": "string" + } + }, + "bundles": { + "type": "array", + "description": "A list of attribute bundles to compute. Currently supported: `statement`, which returns `next_payment_due_date` and `next_payment_minimum_amount`.", + "items": { + "type": "string" + }, + "example": [ + "statement" + ] + } + } + }, "AccountAttributeResponse": { "allOf": [ { @@ -17765,7 +18463,8 @@ "duration_ms", "status", "status_history", - "created_at" + "created_at", + "updated_at" ], "properties": { "id": { @@ -17804,6 +18503,11 @@ "type": "string", "format": "date-time", "description": "Timestamp when the forwarding request was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the forwarding request was last updated." } } }, @@ -18482,55 +19186,227 @@ "debit" ] }, - "trace_id": { + "trace_id": { + "type": [ + "string", + "null" + ], + "description": "Trace identifier for the reversal." + }, + "target_account": { + "type": [ + "string", + "null" + ], + "description": "The target account for the reversal." + }, + "amount": { + "type": "integer", + "description": "Reversal amount in cents.", + "minimum": 0 + }, + "description": { + "type": [ + "string", + "null" + ], + "description": "Human-readable description for the reversal." + }, + "fee": { + "type": [ + "object", + "null" + ], + "description": "Fee information for the reversal." + }, + "error": { + "$ref": "#/components/schemas/PaymentReversalResourceError" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the reversal was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the reversal was last updated." + } + } + }, + "PaymentReversalListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/ListEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentReversal" + } + } + } + } + ] + }, + "PaymentReversalResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PaymentReversal" + } + } + } + ] + }, + "PaymentReversalUpdateRequest": { + "type": "object", + "description": "Request body for updating a payment reversal.", + "properties": { + "status": { + "type": "string", + "description": "Updated status for the reversal." + } + } + }, + "Preauth": { + "type": "object", + "description": "A PreauthSignals assessment returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. `verified_ownership` and `card_standing` are derived from the identifiers supplied in the request and are available to all teams. `success_likelihood` and `optimal_retry_date` depend on additional underlying data; when a team is not provisioned for that data both fields return `null`, which is a normal response state rather than an error.", + "required": [ + "id", + "account_id", + "status", + "verified_ownership", + "card_standing", + "success_likelihood", + "optimal_retry_date", + "metadata", + "created_at", + "updated_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the PreauthSignals assessment.", + "pattern": "^preauth_\\w+$", + "example": "preauth_qV7kRaFm4JNxw" + }, + "account_id": { + "type": [ + "string", + "null" + ], + "description": "The ID of the associated Method Account. Returned whether the account was passed in the request or generated from raw card input.", + "example": "acc_4m9amk4KFiaQX" + }, + "status": { + "type": "string", + "description": "Current processing status of the assessment.", + "enum": [ + "pending", + "in_progress", + "completed", + "failed" + ], + "example": "completed" + }, + "verified_ownership": { "type": [ "string", "null" ], - "description": "Trace identifier for the reversal." + "description": "The result of matching the provided card details to a known cardholder identity. Derived from the request identifiers alone.", + "enum": [ + "match", + "no_match", + "fuzzy_match", + "identity_not_found", + "unknown", + null + ], + "example": "match" }, - "target_account": { + "card_standing": { "type": [ "string", "null" ], - "description": "The target account for the reversal." + "description": "Current status of the card account at the issuer.", + "enum": [ + "open", + "closed", + null + ], + "example": "open" }, - "amount": { - "type": "integer", - "description": "Reversal amount in cents.", - "minimum": 0 + "success_likelihood": { + "type": [ + "number", + "null" + ], + "description": "The predicted probability that a charge will succeed under the provided conditions, expressed as a decimal from 0.00 to 1.00. Returns `null` when the team is not provisioned for the required underlying data.", + "minimum": 0, + "maximum": 1, + "example": 0.87 }, - "description": { + "optimal_retry_date": { "type": [ "string", "null" ], - "description": "Human-readable description for the reversal." + "format": "date", + "description": "The recommended date on which to attempt or retry the charge. Returns `null` when the team is not provisioned for the required underlying data.", + "example": "2026-06-02" }, - "fee": { + "error": { "type": [ "object", "null" ], - "description": "Fee information for the reversal." + "description": "An object representing an error that occurred while processing this request.", + "allOf": [ + { + "$ref": "#/components/schemas/ResourceError" + } + ] }, - "error": { - "$ref": "#/components/schemas/PaymentReversalResourceError" + "metadata": { + "$ref": "#/components/schemas/Metadata" }, "created_at": { "type": "string", "format": "date-time", - "description": "Timestamp when the reversal was created." + "description": "Timestamp when the assessment was created." }, "updated_at": { "type": "string", "format": "date-time", - "description": "Timestamp when the reversal was last updated." + "description": "Timestamp when the assessment was last updated." } - } - }, - "PaymentReversalListResponse": { + }, + "example": { + "id": "preauth_qV7kRaFm4JNxw", + "account_id": "acc_4m9amk4KFiaQX", + "status": "completed", + "verified_ownership": "match", + "card_standing": "open", + "success_likelihood": 0.87, + "optimal_retry_date": "2026-06-02", + "error": null, + "metadata": null, + "created_at": "2026-05-28T14:00:00.000Z", + "updated_at": "2026-05-28T14:00:00.180Z" + } + }, + "PreauthListResponse": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" @@ -18541,14 +19417,105 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/PaymentReversal" + "$ref": "#/components/schemas/Preauth" } } } } ] }, - "PaymentReversalResponse": { + "PreauthCard": { + "type": "object", + "description": "Raw card identifiers for an unauthenticated card. `bin6`, `last4`, `first_name`, `last_name`, and `phone` are the inputs used to resolve `verified_ownership`; supplying more of them improves match accuracy.", + "required": [ + "bin6", + "last4" + ], + "properties": { + "bin6": { + "type": "string", + "description": "First six digits of the card number (the bank identification number).", + "pattern": "^\\d{6}$", + "example": "411111" + }, + "last4": { + "type": "string", + "description": "Last four digits of the card number.", + "pattern": "^\\d{4}$", + "example": "1234" + }, + "first_name": { + "type": "string", + "description": "Cardholder first name.", + "example": "Jane" + }, + "last_name": { + "type": "string", + "description": "Cardholder last name.", + "example": "Doe" + }, + "phone": { + "type": "string", + "description": "Cardholder phone number in E.164 format.", + "example": "+15555555555" + }, + "zip": { + "type": "string", + "description": "Cardholder billing postal code.", + "example": "10001" + } + } + }, + "PreauthPurchase": { + "type": "object", + "description": "Optional context describing the transaction being assessed. Supplying purchase context improves the accuracy of `success_likelihood`.", + "properties": { + "amount": { + "type": "integer", + "description": "The amount of the transaction in cents (for example, $99.99 = 9999).", + "minimum": 1, + "example": 9999 + }, + "mcc": { + "type": "string", + "description": "Merchant category code for the transaction.", + "example": "4511" + }, + "ip_address": { + "type": "string", + "description": "IP address of the device initiating the transaction.", + "example": "203.0.113.42" + }, + "txn_time": { + "type": "string", + "format": "date-time", + "description": "Timestamp at which the transaction is attempted.", + "example": "2026-05-28T14:00:00Z" + } + } + }, + "PreauthCreateRequest": { + "type": "object", + "description": "Request to compute a PreauthSignals assessment. Exactly one of `account_id` or `card` must be provided; supplying both returns a `400` error.", + "properties": { + "account_id": { + "type": "string", + "description": "The ID of an authenticated Method Account to assess.", + "pattern": "^acc_\\w+$", + "example": "acc_4m9amk4KFiaQX" + }, + "card": { + "$ref": "#/components/schemas/PreauthCard" + }, + "purchase": { + "$ref": "#/components/schemas/PreauthPurchase" + }, + "metadata": { + "$ref": "#/components/schemas/Metadata" + } + } + }, + "PreauthResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" @@ -18557,21 +19524,46 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PaymentReversal" + "$ref": "#/components/schemas/Preauth" } } } ] }, - "PaymentReversalUpdateRequest": { - "type": "object", - "description": "Request body for updating a payment reversal.", - "properties": { - "status": { - "type": "string", - "description": "Updated status for the reversal." - } - } + "ReportType": { + "type": "string", + "description": "The type of report, determining the data it contains and the window it covers.", + "enum": [ + "payments.created.current", + "payments.created.previous", + "payments.created.previous_day", + "payments.updated.current", + "payments.updated.previous", + "payments.failed.previous_day", + "payments.outstanding_itemized.daily", + "payments.outstanding_itemized.total", + "payments.outstanding_itemized.pull_daily", + "payments.outstanding_itemized.pull_total", + "payments.outstanding_itemized.push_daily", + "payments.outstanding_itemized.push_total", + "payments.outstanding_summary.daily", + "payments.outstanding_summary.total", + "payments.outstanding_summary.pull_daily", + "payments.outstanding_summary.pull_total", + "payments.outstanding_summary.push_daily", + "payments.outstanding_summary.push_total", + "ach.pull.upcoming", + "ach.pull.previous", + "ach.pull.nightly", + "ach.reversals.nightly", + "ach.debit.daily", + "reversals.pull_funded.previous_day", + "reversals.push_funded.previous_day", + "entities.created.previous_day", + "reserve_fbo_balance.created.previous_day", + "team_fbo_balance.created.previous_day" + ], + "example": "payments.created.current" }, "ReportCreateRequest": { "type": "object", @@ -18581,23 +19573,7 @@ ], "properties": { "type": { - "type": "string", - "description": "The type of report to generate.", - "enum": [ - "payments.created.current", - "payments.created.previous", - "payments.created.previous_day", - "payments.updated.current", - "payments.updated.previous", - "payments.failed.previous_day", - "ach.pull.upcoming", - "ach.pull.previous", - "ach.pull.nightly", - "ach.reversals.nightly", - "ach.debit.daily", - "entities.created.previous_day", - "reserve_fbo_balance.created.previous_day" - ] + "$ref": "#/components/schemas/ReportType" } } }, @@ -18621,23 +19597,7 @@ "example": "rpt_cj2mkA3hFyHT5" }, "type": { - "type": "string", - "description": "The type of report.", - "enum": [ - "payments.created.current", - "payments.created.previous", - "payments.created.previous_day", - "payments.updated.current", - "payments.updated.previous", - "payments.failed.previous_day", - "ach.pull.upcoming", - "ach.pull.previous", - "ach.pull.nightly", - "ach.reversals.nightly", - "ach.debit.daily", - "entities.created.previous_day", - "reserve_fbo_balance.created.previous_day" - ] + "$ref": "#/components/schemas/ReportType" }, "url": { "type": [ @@ -18684,6 +19644,153 @@ } ] }, + "ReportScheduleType": { + "type": "string", + "description": "The Report type generated by the schedule. Method owns the run cadence for each supported type; the cadence is not configurable. All supported types currently run on business days at 8:00am America/Chicago. Non-business-day runs are skipped and resume on the next scheduled business day.", + "enum": [ + "ach.pull.nightly", + "ach.reversals.nightly", + "entities.created.previous_day", + "payments.created.previous_day", + "payments.failed.previous_day", + "reversals.pull_funded.previous_day", + "reversals.push_funded.previous_day" + ], + "example": "payments.created.previous_day" + }, + "ReportSchedule": { + "type": "object", + "description": "A Report Schedule automates recurring generation of a single Report `type`. Each scheduled run creates a Report exactly as `POST /reports` does, so it follows normal Report persistence and triggers the standard `report.create` webhook. When `email_recipients` are configured, Method also emails the CSV for the generated Report. A team may have only one active schedule per `type`.", + "required": [ + "id", + "type", + "email_recipients", + "status", + "created_at", + "updated_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the report schedule.", + "pattern": "^rpt_sch_\\w+$", + "example": "rpt_sch_Gqjh8pzeUfzH6" + }, + "type": { + "$ref": "#/components/schemas/ReportScheduleType" + }, + "email_recipients": { + "type": "array", + "description": "Email addresses that receive the generated Report CSV after each run. An empty array means no email is sent; the Report is still created.", + "items": { + "type": "string", + "format": "email" + }, + "example": [ + "reports@example.com" + ] + }, + "status": { + "type": "string", + "description": "Current status of the report schedule. `active` schedules run on their cadence.", + "example": "active" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the report schedule was created." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the report schedule was last updated." + } + }, + "example": { + "id": "rpt_sch_Gqjh8pzeUfzH6", + "type": "payments.created.previous_day", + "email_recipients": [ + "reports@example.com" + ], + "status": "active", + "created_at": "2026-06-01T13:21:10.386Z", + "updated_at": "2026-06-01T13:21:10.386Z" + } + }, + "ReportScheduleListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/ListEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportSchedule" + } + } + } + } + ] + }, + "ReportScheduleCreateRequest": { + "type": "object", + "description": "Request body for creating a report schedule. Creating a second schedule for a `type` that already has an active schedule returns an error.", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "#/components/schemas/ReportScheduleType" + }, + "email_recipients": { + "type": "array", + "description": "Email addresses that receive the generated Report CSV after each run.", + "items": { + "type": "string", + "format": "email" + }, + "example": [ + "reports@example.com" + ] + } + } + }, + "ReportScheduleResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ReportSchedule" + } + } + } + ] + }, + "ReportScheduleUpdateRequest": { + "type": "object", + "description": "Request body for updating a report schedule. The schedule `type` and cadence cannot be changed; create a new schedule instead.", + "properties": { + "email_recipients": { + "type": "array", + "description": "Replacement list of email addresses that receive the generated Report CSV.", + "items": { + "type": "string", + "format": "email" + }, + "example": [ + "ops@example.com", + "reports@example.com" + ] + } + } + }, "SecretStatus": { "type": "string", "enum": [ @@ -19928,6 +21035,70 @@ } ] }, + "OpalEvent": { + "type": "object", + "description": "An event recorded during an Opal session, following the `..` type pattern.", + "required": [ + "type", + "mode", + "object", + "action", + "timestamp", + "data" + ], + "properties": { + "type": { + "type": "string", + "description": "Full event type in the format `..`.", + "example": "card_connect.flow.started" + }, + "mode": { + "type": "string", + "description": "The session mode that produced this event.", + "example": "card_connect" + }, + "object": { + "type": "string", + "description": "The object within the mode that the event relates to.", + "example": "flow" + }, + "action": { + "type": "string", + "description": "The action that occurred on the object.", + "example": "started" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of when the event occurred." + }, + "data": { + "type": [ + "object", + "null" + ], + "description": "Optional event-specific data payload." + } + } + }, + "OpalEventListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/ListEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OpalEvent" + } + } + } + } + ] + }, "ObjectResponse": { "allOf": [ { diff --git a/latest/openapi.bundled.yaml b/latest/openapi.bundled.yaml index cbb2504..df0e519 100644 --- a/latest/openapi.bundled.yaml +++ b/latest/openapi.bundled.yaml @@ -129,8 +129,12 @@ tags: description: ACH and clearing payments - name: Payment Reversals description: Reversals for payments + - name: Preauth + description: PreauthSignals transaction success assessments - name: Reports description: Downloadable reports + - name: Report Schedules + description: Recurring report generation schedules - name: Secrets description: Secure secret storage - name: Teams @@ -659,7 +663,7 @@ paths: post: operationId: createAccountAttribute summary: Create an account attribute - description: Creates a new attribute request for the specified account. + description: 'Creates a new attribute request to compute the account''s attributes. The attributes returned depend on the account''s liability type. This operation is asynchronous: the response returns immediately with `status` set and `attributes` null, and the final result is available by polling the retrieve endpoint or subscribing to webhooks.' tags: - Account Attributes security: @@ -668,6 +672,15 @@ paths: - $ref: '#/components/parameters/method_version' - $ref: '#/components/parameters/idempotency_key' - $ref: '#/components/parameters/AccountIdParam' + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/AccountAttributeCreateRequest' + example: + bundles: + - statement responses: '200': description: The newly created account attribute. @@ -4409,6 +4422,161 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' + /preauth: + get: + operationId: listPreauths + summary: List PreauthSignals assessments + description: Returns a paginated list of PreauthSignals assessments for the team. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/PageLimitParam' + - $ref: '#/components/parameters/PageCursorParam' + - $ref: '#/components/parameters/FromDateParam' + - $ref: '#/components/parameters/ToDateParam' + responses: + '200': + description: A list of PreauthSignals assessments. + headers: + Pagination-Page: + description: Current page number. + schema: + type: integer + Pagination-Page-Count: + description: Total number of pages. + schema: + type: integer + Pagination-Page-Limit: + description: Number of items per page. + schema: + type: integer + Pagination-Total-Count: + description: Total number of items across all pages. + schema: + type: integer + Pagination-Page-Cursor-Prev: + description: Cursor for the previous page, if available. + schema: + type: + - string + - 'null' + Pagination-Page-Cursor-Next: + description: Cursor for the next page, if available. + schema: + type: + - string + - 'null' + content: + application/json: + schema: + $ref: '#/components/schemas/PreauthListResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + post: + operationId: createPreauth + summary: Create PreauthSignals assessment + description: Computes a PreauthSignals assessment for a given card or account. Provide either an `account_id` for an authenticated Method Account, or a `card` object with raw card identifiers. Exactly one of the two is required; supplying both returns a `400` error. Optionally include `purchase` context to improve the prediction. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/idempotency_key' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PreauthCreateRequest' + examples: + by_card: + summary: Assess raw card identifiers with purchase context + value: + card: + bin6: '411111' + last4: '1234' + first_name: Jane + last_name: Doe + phone: '+15555555555' + zip: '10001' + purchase: + amount: 9999 + mcc: '4511' + ip_address: 203.0.113.42 + txn_time: '2026-05-28T14:00:00Z' + by_account: + summary: Assess an authenticated Method Account + value: + account_id: acc_4m9amk4KFiaQX + responses: + '200': + description: The PreauthSignals assessment. + content: + application/json: + schema: + $ref: '#/components/schemas/PreauthResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + /preauth/{preauthId}: + get: + operationId: retrievePreauth + summary: Retrieve a PreauthSignals assessment + description: Returns a single PreauthSignals assessment by its identifier. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - name: preauthId + in: path + required: true + description: Unique identifier for the PreauthSignals assessment. + schema: + type: string + pattern: ^preauth_\w+$ + responses: + '200': + description: The requested PreauthSignals assessment. + content: + application/json: + schema: + $ref: '#/components/schemas/PreauthResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' /reports: post: operationId: createReport @@ -4520,6 +4688,215 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' + /report_schedules: + get: + operationId: listReportSchedules + summary: List report schedules + description: Returns the report schedules configured for the team. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + responses: + '200': + description: A list of report schedules. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleListResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + post: + operationId: createReportSchedule + summary: Create a report schedule + description: Creates a new active report schedule for a single supported Report `type`. Once created, the schedule runs on Method's standard cadence for that type. A team may have only one active schedule per `type`; creating a duplicate returns an error. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/idempotency_key' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleCreateRequest' + example: + type: payments.created.previous_day + email_recipients: + - reports@example.com + responses: + '200': + description: The newly created report schedule. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + /report_schedules/{reportScheduleId}: + get: + operationId: retrieveReportSchedule + summary: Retrieve a report schedule + description: Returns the report schedule associated with the identifier. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + responses: + '200': + description: The requested report schedule. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + put: + operationId: updateReportSchedule + summary: Update a report schedule + description: Updates the `email_recipients` of an existing report schedule. The schedule `type` and cadence cannot be changed. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/idempotency_key' + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleUpdateRequest' + example: + email_recipients: + - ops@example.com + - reports@example.com + responses: + '200': + description: The updated report schedule. + content: + application/json: + schema: + $ref: '#/components/schemas/ReportScheduleResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' + delete: + operationId: deleteReportSchedule + summary: Delete a report schedule + description: Deletes a report schedule, stopping all future runs. Returns an empty response. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: '#/components/parameters/method_version' + - $ref: '#/components/parameters/idempotency_key' + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + responses: + '200': + description: Report schedule deleted successfully. + content: + application/json: + schema: + type: object + required: + - success + - data + - message + properties: + success: + type: boolean + example: true + data: + type: 'null' + example: null + message: + type: + - 'null' + - string + example: null + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' /secrets: get: operationId: listSecrets @@ -5676,6 +6053,42 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' + /opal/events: + get: + operationId: listOpalEvents + summary: List Opal session events + description: Returns the events recorded during the Opal session associated with the authenticated token. Event types follow the `..` pattern. + tags: + - Opal + security: + - OpalToken: [] + parameters: + - $ref: '#/components/parameters/method_version' + responses: + '200': + description: The events recorded for the current Opal session. + content: + application/json: + schema: + $ref: '#/components/schemas/OpalEventListResponse' + example: + success: true + data: + - type: card_connect.flow.started + mode: card_connect + object: flow + action: started + timestamp: '2026-03-14T19:02:11.482Z' + data: null + message: null + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/InternalError' /elements/token: post: operationId: elementsCreateToken @@ -8895,6 +9308,22 @@ components: type: array items: $ref: '#/components/schemas/AccountAttribute' + AccountAttributeCreateRequest: + type: object + description: Optional request body for creating an account attribute request. Both fields are optional; a request with no body computes the full set of attributes for the account type. Provide `requested_attributes`, `bundles`, or both to scope the response's `attributes` object to just the requested attributes. + properties: + requested_attributes: + type: array + description: A list of specific attribute names to compute. When omitted, the full set of attributes for the account type is returned. + items: + type: string + bundles: + type: array + description: 'A list of attribute bundles to compute. Currently supported: `statement`, which returns `next_payment_due_date` and `next_payment_minimum_amount`.' + items: + type: string + example: + - statement AccountAttributeResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' @@ -11670,6 +12099,7 @@ components: - status - status_history - created_at + - updated_at properties: id: type: string @@ -11698,6 +12128,10 @@ components: type: string format: date-time description: Timestamp when the forwarding request was created. + updated_at: + type: string + format: date-time + description: Timestamp when the forwarding request was last updated. ForwardingRequestResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' @@ -12236,6 +12670,227 @@ components: status: type: string description: Updated status for the reversal. + Preauth: + type: object + description: A PreauthSignals assessment returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. `verified_ownership` and `card_standing` are derived from the identifiers supplied in the request and are available to all teams. `success_likelihood` and `optimal_retry_date` depend on additional underlying data; when a team is not provisioned for that data both fields return `null`, which is a normal response state rather than an error. + required: + - id + - account_id + - status + - verified_ownership + - card_standing + - success_likelihood + - optimal_retry_date + - metadata + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the PreauthSignals assessment. + pattern: ^preauth_\w+$ + example: preauth_qV7kRaFm4JNxw + account_id: + type: + - string + - 'null' + description: The ID of the associated Method Account. Returned whether the account was passed in the request or generated from raw card input. + example: acc_4m9amk4KFiaQX + status: + type: string + description: Current processing status of the assessment. + enum: + - pending + - in_progress + - completed + - failed + example: completed + verified_ownership: + type: + - string + - 'null' + description: The result of matching the provided card details to a known cardholder identity. Derived from the request identifiers alone. + enum: + - match + - no_match + - fuzzy_match + - identity_not_found + - unknown + - null + example: match + card_standing: + type: + - string + - 'null' + description: Current status of the card account at the issuer. + enum: + - open + - closed + - null + example: open + success_likelihood: + type: + - number + - 'null' + description: The predicted probability that a charge will succeed under the provided conditions, expressed as a decimal from 0.00 to 1.00. Returns `null` when the team is not provisioned for the required underlying data. + minimum: 0 + maximum: 1 + example: 0.87 + optimal_retry_date: + type: + - string + - 'null' + format: date + description: The recommended date on which to attempt or retry the charge. Returns `null` when the team is not provisioned for the required underlying data. + example: '2026-06-02' + error: + type: + - object + - 'null' + description: An object representing an error that occurred while processing this request. + allOf: + - $ref: '#/components/schemas/ResourceError' + metadata: + $ref: '#/components/schemas/Metadata' + created_at: + type: string + format: date-time + description: Timestamp when the assessment was created. + updated_at: + type: string + format: date-time + description: Timestamp when the assessment was last updated. + example: + id: preauth_qV7kRaFm4JNxw + account_id: acc_4m9amk4KFiaQX + status: completed + verified_ownership: match + card_standing: open + success_likelihood: 0.87 + optimal_retry_date: '2026-06-02' + error: null + metadata: null + created_at: '2026-05-28T14:00:00.000Z' + updated_at: '2026-05-28T14:00:00.180Z' + PreauthListResponse: + allOf: + - $ref: '#/components/schemas/ListEnvelope' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Preauth' + PreauthCard: + type: object + description: Raw card identifiers for an unauthenticated card. `bin6`, `last4`, `first_name`, `last_name`, and `phone` are the inputs used to resolve `verified_ownership`; supplying more of them improves match accuracy. + required: + - bin6 + - last4 + properties: + bin6: + type: string + description: First six digits of the card number (the bank identification number). + pattern: ^\d{6}$ + example: '411111' + last4: + type: string + description: Last four digits of the card number. + pattern: ^\d{4}$ + example: '1234' + first_name: + type: string + description: Cardholder first name. + example: Jane + last_name: + type: string + description: Cardholder last name. + example: Doe + phone: + type: string + description: Cardholder phone number in E.164 format. + example: '+15555555555' + zip: + type: string + description: Cardholder billing postal code. + example: '10001' + PreauthPurchase: + type: object + description: Optional context describing the transaction being assessed. Supplying purchase context improves the accuracy of `success_likelihood`. + properties: + amount: + type: integer + description: The amount of the transaction in cents (for example, $99.99 = 9999). + minimum: 1 + example: 9999 + mcc: + type: string + description: Merchant category code for the transaction. + example: '4511' + ip_address: + type: string + description: IP address of the device initiating the transaction. + example: 203.0.113.42 + txn_time: + type: string + format: date-time + description: Timestamp at which the transaction is attempted. + example: '2026-05-28T14:00:00Z' + PreauthCreateRequest: + type: object + description: Request to compute a PreauthSignals assessment. Exactly one of `account_id` or `card` must be provided; supplying both returns a `400` error. + properties: + account_id: + type: string + description: The ID of an authenticated Method Account to assess. + pattern: ^acc_\w+$ + example: acc_4m9amk4KFiaQX + card: + $ref: '#/components/schemas/PreauthCard' + purchase: + $ref: '#/components/schemas/PreauthPurchase' + metadata: + $ref: '#/components/schemas/Metadata' + PreauthResponse: + allOf: + - $ref: '#/components/schemas/SuccessEnvelope' + - type: object + properties: + data: + $ref: '#/components/schemas/Preauth' + ReportType: + type: string + description: The type of report, determining the data it contains and the window it covers. + enum: + - payments.created.current + - payments.created.previous + - payments.created.previous_day + - payments.updated.current + - payments.updated.previous + - payments.failed.previous_day + - payments.outstanding_itemized.daily + - payments.outstanding_itemized.total + - payments.outstanding_itemized.pull_daily + - payments.outstanding_itemized.pull_total + - payments.outstanding_itemized.push_daily + - payments.outstanding_itemized.push_total + - payments.outstanding_summary.daily + - payments.outstanding_summary.total + - payments.outstanding_summary.pull_daily + - payments.outstanding_summary.pull_total + - payments.outstanding_summary.push_daily + - payments.outstanding_summary.push_total + - ach.pull.upcoming + - ach.pull.previous + - ach.pull.nightly + - ach.reversals.nightly + - ach.debit.daily + - reversals.pull_funded.previous_day + - reversals.push_funded.previous_day + - entities.created.previous_day + - reserve_fbo_balance.created.previous_day + - team_fbo_balance.created.previous_day + example: payments.created.current ReportCreateRequest: type: object description: Request body for creating a report. @@ -12243,22 +12898,7 @@ components: - type properties: type: - type: string - description: The type of report to generate. - enum: - - payments.created.current - - payments.created.previous - - payments.created.previous_day - - payments.updated.current - - payments.updated.previous - - payments.failed.previous_day - - ach.pull.upcoming - - ach.pull.previous - - ach.pull.nightly - - ach.reversals.nightly - - ach.debit.daily - - entities.created.previous_day - - reserve_fbo_balance.created.previous_day + $ref: '#/components/schemas/ReportType' Report: type: object description: A Report is a downloadable file containing aggregated data about payments, entities, or other resources. @@ -12277,22 +12917,7 @@ components: pattern: ^rpt_\w+$ example: rpt_cj2mkA3hFyHT5 type: - type: string - description: The type of report. - enum: - - payments.created.current - - payments.created.previous - - payments.created.previous_day - - payments.updated.current - - payments.updated.previous - - payments.failed.previous_day - - ach.pull.upcoming - - ach.pull.previous - - ach.pull.nightly - - ach.reversals.nightly - - ach.debit.daily - - entities.created.previous_day - - reserve_fbo_balance.created.previous_day + $ref: '#/components/schemas/ReportType' url: type: - string @@ -12321,6 +12946,109 @@ components: properties: data: $ref: '#/components/schemas/Report' + ReportScheduleType: + type: string + description: The Report type generated by the schedule. Method owns the run cadence for each supported type; the cadence is not configurable. All supported types currently run on business days at 8:00am America/Chicago. Non-business-day runs are skipped and resume on the next scheduled business day. + enum: + - ach.pull.nightly + - ach.reversals.nightly + - entities.created.previous_day + - payments.created.previous_day + - payments.failed.previous_day + - reversals.pull_funded.previous_day + - reversals.push_funded.previous_day + example: payments.created.previous_day + ReportSchedule: + type: object + description: A Report Schedule automates recurring generation of a single Report `type`. Each scheduled run creates a Report exactly as `POST /reports` does, so it follows normal Report persistence and triggers the standard `report.create` webhook. When `email_recipients` are configured, Method also emails the CSV for the generated Report. A team may have only one active schedule per `type`. + required: + - id + - type + - email_recipients + - status + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the report schedule. + pattern: ^rpt_sch_\w+$ + example: rpt_sch_Gqjh8pzeUfzH6 + type: + $ref: '#/components/schemas/ReportScheduleType' + email_recipients: + type: array + description: Email addresses that receive the generated Report CSV after each run. An empty array means no email is sent; the Report is still created. + items: + type: string + format: email + example: + - reports@example.com + status: + type: string + description: Current status of the report schedule. `active` schedules run on their cadence. + example: active + created_at: + type: string + format: date-time + description: Timestamp when the report schedule was created. + updated_at: + type: string + format: date-time + description: Timestamp when the report schedule was last updated. + example: + id: rpt_sch_Gqjh8pzeUfzH6 + type: payments.created.previous_day + email_recipients: + - reports@example.com + status: active + created_at: '2026-06-01T13:21:10.386Z' + updated_at: '2026-06-01T13:21:10.386Z' + ReportScheduleListResponse: + allOf: + - $ref: '#/components/schemas/ListEnvelope' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ReportSchedule' + ReportScheduleCreateRequest: + type: object + description: Request body for creating a report schedule. Creating a second schedule for a `type` that already has an active schedule returns an error. + required: + - type + properties: + type: + $ref: '#/components/schemas/ReportScheduleType' + email_recipients: + type: array + description: Email addresses that receive the generated Report CSV after each run. + items: + type: string + format: email + example: + - reports@example.com + ReportScheduleResponse: + allOf: + - $ref: '#/components/schemas/SuccessEnvelope' + - type: object + properties: + data: + $ref: '#/components/schemas/ReportSchedule' + ReportScheduleUpdateRequest: + type: object + description: Request body for updating a report schedule. The schedule `type` and cadence cannot be changed; create a new schedule instead. + properties: + email_recipients: + type: array + description: Replacement list of email addresses that receive the generated Report CSV. + items: + type: string + format: email + example: + - ops@example.com + - reports@example.com SecretStatus: type: string enum: @@ -13184,6 +13912,51 @@ components: - object - 'null' example: null + OpalEvent: + type: object + description: An event recorded during an Opal session, following the `..` type pattern. + required: + - type + - mode + - object + - action + - timestamp + - data + properties: + type: + type: string + description: Full event type in the format `..`. + example: card_connect.flow.started + mode: + type: string + description: The session mode that produced this event. + example: card_connect + object: + type: string + description: The object within the mode that the event relates to. + example: flow + action: + type: string + description: The action that occurred on the object. + example: started + timestamp: + type: string + format: date-time + description: ISO 8601 timestamp of when the event occurred. + data: + type: + - object + - 'null' + description: Optional event-specific data payload. + OpalEventListResponse: + allOf: + - $ref: '#/components/schemas/ListEnvelope' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/OpalEvent' ObjectResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' diff --git a/manifests/mounted-routes.json b/manifests/mounted-routes.json index a7660b4..44404e5 100644 --- a/manifests/mounted-routes.json +++ b/manifests/mounted-routes.json @@ -363,6 +363,10 @@ "method": "GET", "path": "/merchants/{mchId}" }, + { + "method": "GET", + "path": "/opal/events" + }, { "method": "DELETE", "path": "/opal/token" @@ -407,6 +411,38 @@ "method": "GET", "path": "/ping" }, + { + "method": "GET", + "path": "/preauth" + }, + { + "method": "POST", + "path": "/preauth" + }, + { + "method": "GET", + "path": "/preauth/{preauthId}" + }, + { + "method": "GET", + "path": "/report_schedules" + }, + { + "method": "POST", + "path": "/report_schedules" + }, + { + "method": "DELETE", + "path": "/report_schedules/{reportScheduleId}" + }, + { + "method": "GET", + "path": "/report_schedules/{reportScheduleId}" + }, + { + "method": "PUT", + "path": "/report_schedules/{reportScheduleId}" + }, { "method": "POST", "path": "/reports" diff --git a/manifests/operation-ids.json b/manifests/operation-ids.json index 88eb90a..dfdcd99 100644 --- a/manifests/operation-ids.json +++ b/manifests/operation-ids.json @@ -21,7 +21,9 @@ "createForwardingRequest", "createOpalToken", "createPayment", + "createPreauth", "createReport", + "createReportSchedule", "createSecret", "createTeam", "createTeamEncryptionKey", @@ -31,6 +33,7 @@ "deleteAccountSubscription", "deleteEntitySubscription", "deletePayment", + "deleteReportSchedule", "deleteSecret", "deleteTeamPublicKey", "deleteWebhook", @@ -66,9 +69,12 @@ "listManagedAccountTransactions", "listManagedAccounts", "listMerchants", + "listOpalEvents", "listPaymentReversals", "listPayments", + "listPreauths", "listPublicJwks", + "listReportSchedules", "listSecrets", "listTeamPublicKeys", "listWebhooks", @@ -105,8 +111,10 @@ "retrieveOpalToken", "retrievePayment", "retrievePaymentReversal", + "retrievePreauth", "retrievePublicJwk", "retrieveReport", + "retrieveReportSchedule", "retrieveSecret", "retrieveTeam", "retrieveTeamPublicKey", @@ -128,5 +136,6 @@ "updateEntityConsent", "updateEntityVerificationSession", "updatePaymentReversal", + "updateReportSchedule", "updateWebhook" ] diff --git a/openapi/components/schemas/account.yaml b/openapi/components/schemas/account.yaml index fb39138..a5b07b4 100644 --- a/openapi/components/schemas/account.yaml +++ b/openapi/components/schemas/account.yaml @@ -599,6 +599,30 @@ AccountAttribute: type: string format: date-time description: Timestamp when the attribute was last updated. +AccountAttributeCreateRequest: + type: object + description: >- + Optional request body for creating an account attribute request. Both fields are + optional; a request with no body computes the full set of attributes for the account + type. Provide `requested_attributes`, `bundles`, or both to scope the response's + `attributes` object to just the requested attributes. + properties: + requested_attributes: + type: array + description: >- + A list of specific attribute names to compute. When omitted, the full set of + attributes for the account type is returned. + items: + type: string + bundles: + type: array + description: >- + A list of attribute bundles to compute. Currently supported: `statement`, which + returns `next_payment_due_date` and `next_payment_minimum_amount`. + items: + type: string + example: + - statement AccountAttributeResponse: allOf: - $ref: common.yaml#/SuccessEnvelope diff --git a/openapi/components/schemas/forwarding_request.yaml b/openapi/components/schemas/forwarding_request.yaml index 4b7e909..c9ef353 100644 --- a/openapi/components/schemas/forwarding_request.yaml +++ b/openapi/components/schemas/forwarding_request.yaml @@ -9,6 +9,7 @@ ForwardingRequest: - status - status_history - created_at + - updated_at properties: id: type: string @@ -37,6 +38,10 @@ ForwardingRequest: type: string format: date-time description: Timestamp when the forwarding request was created. + updated_at: + type: string + format: date-time + description: Timestamp when the forwarding request was last updated. ForwardingRequestStatus: type: string enum: diff --git a/openapi/components/schemas/preauth.yaml b/openapi/components/schemas/preauth.yaml new file mode 100644 index 0000000..20648ae --- /dev/null +++ b/openapi/components/schemas/preauth.yaml @@ -0,0 +1,216 @@ +Preauth: + type: object + description: >- + A PreauthSignals assessment returns the predicted likelihood that a transaction will + succeed, alongside verified ownership of the card and recommended retry timing. + `verified_ownership` and `card_standing` are derived from the identifiers supplied in + the request and are available to all teams. `success_likelihood` and + `optimal_retry_date` depend on additional underlying data; when a team is not + provisioned for that data both fields return `null`, which is a normal response state + rather than an error. + required: + - id + - account_id + - status + - verified_ownership + - card_standing + - success_likelihood + - optimal_retry_date + - metadata + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the PreauthSignals assessment. + pattern: ^preauth_\w+$ + example: preauth_qV7kRaFm4JNxw + account_id: + type: + - string + - 'null' + description: >- + The ID of the associated Method Account. Returned whether the account was passed + in the request or generated from raw card input. + example: acc_4m9amk4KFiaQX + status: + type: string + description: Current processing status of the assessment. + enum: + - pending + - in_progress + - completed + - failed + example: completed + verified_ownership: + type: + - string + - 'null' + description: >- + The result of matching the provided card details to a known cardholder identity. + Derived from the request identifiers alone. + enum: + - match + - no_match + - fuzzy_match + - identity_not_found + - unknown + - null + example: match + card_standing: + type: + - string + - 'null' + description: Current status of the card account at the issuer. + enum: + - open + - closed + - null + example: open + success_likelihood: + type: + - number + - 'null' + description: >- + The predicted probability that a charge will succeed under the provided + conditions, expressed as a decimal from 0.00 to 1.00. Returns `null` when the + team is not provisioned for the required underlying data. + minimum: 0 + maximum: 1 + example: 0.87 + optimal_retry_date: + type: + - string + - 'null' + format: date + description: >- + The recommended date on which to attempt or retry the charge. Returns `null` when + the team is not provisioned for the required underlying data. + example: '2026-06-02' + error: + type: + - object + - 'null' + description: An object representing an error that occurred while processing this request. + allOf: + - $ref: common.yaml#/ResourceError + metadata: + $ref: common.yaml#/Metadata + created_at: + type: string + format: date-time + description: Timestamp when the assessment was created. + updated_at: + type: string + format: date-time + description: Timestamp when the assessment was last updated. + example: + id: preauth_qV7kRaFm4JNxw + account_id: acc_4m9amk4KFiaQX + status: completed + verified_ownership: match + card_standing: open + success_likelihood: 0.87 + optimal_retry_date: '2026-06-02' + error: null + metadata: null + created_at: '2026-05-28T14:00:00.000Z' + updated_at: '2026-05-28T14:00:00.180Z' + +PreauthCard: + type: object + description: >- + Raw card identifiers for an unauthenticated card. `bin6`, `last4`, `first_name`, + `last_name`, and `phone` are the inputs used to resolve `verified_ownership`; + supplying more of them improves match accuracy. + required: + - bin6 + - last4 + properties: + bin6: + type: string + description: First six digits of the card number (the bank identification number). + pattern: ^\d{6}$ + example: '411111' + last4: + type: string + description: Last four digits of the card number. + pattern: ^\d{4}$ + example: '1234' + first_name: + type: string + description: Cardholder first name. + example: Jane + last_name: + type: string + description: Cardholder last name. + example: Doe + phone: + type: string + description: Cardholder phone number in E.164 format. + example: '+15555555555' + zip: + type: string + description: Cardholder billing postal code. + example: '10001' + +PreauthPurchase: + type: object + description: >- + Optional context describing the transaction being assessed. Supplying purchase + context improves the accuracy of `success_likelihood`. + properties: + amount: + type: integer + description: The amount of the transaction in cents (for example, $99.99 = 9999). + minimum: 1 + example: 9999 + mcc: + type: string + description: Merchant category code for the transaction. + example: '4511' + ip_address: + type: string + description: IP address of the device initiating the transaction. + example: 203.0.113.42 + txn_time: + type: string + format: date-time + description: Timestamp at which the transaction is attempted. + example: '2026-05-28T14:00:00Z' + +PreauthCreateRequest: + type: object + description: >- + Request to compute a PreauthSignals assessment. Exactly one of `account_id` or `card` + must be provided; supplying both returns a `400` error. + properties: + account_id: + type: string + description: The ID of an authenticated Method Account to assess. + pattern: ^acc_\w+$ + example: acc_4m9amk4KFiaQX + card: + $ref: '#/PreauthCard' + purchase: + $ref: '#/PreauthPurchase' + metadata: + $ref: common.yaml#/Metadata + +PreauthResponse: + allOf: + - $ref: common.yaml#/SuccessEnvelope + - type: object + properties: + data: + $ref: '#/Preauth' + +PreauthListResponse: + allOf: + - $ref: common.yaml#/ListEnvelope + - type: object + properties: + data: + type: array + items: + $ref: '#/Preauth' diff --git a/openapi/components/schemas/report.yaml b/openapi/components/schemas/report.yaml index dc7e63f..8fe54ac 100644 --- a/openapi/components/schemas/report.yaml +++ b/openapi/components/schemas/report.yaml @@ -1,3 +1,46 @@ +ReportType: + type: string + description: The type of report, determining the data it contains and the window it covers. + enum: + # Payments created + - payments.created.current + - payments.created.previous + - payments.created.previous_day + # Payments updated + - payments.updated.current + - payments.updated.previous + # Payments failed + - payments.failed.previous_day + # Payments outstanding, itemized + - payments.outstanding_itemized.daily + - payments.outstanding_itemized.total + - payments.outstanding_itemized.pull_daily + - payments.outstanding_itemized.pull_total + - payments.outstanding_itemized.push_daily + - payments.outstanding_itemized.push_total + # Payments outstanding, summary + - payments.outstanding_summary.daily + - payments.outstanding_summary.total + - payments.outstanding_summary.pull_daily + - payments.outstanding_summary.pull_total + - payments.outstanding_summary.push_daily + - payments.outstanding_summary.push_total + # ACH + - ach.pull.upcoming + - ach.pull.previous + - ach.pull.nightly + - ach.reversals.nightly + - ach.debit.daily + # Reversals + - reversals.pull_funded.previous_day + - reversals.push_funded.previous_day + # Entities + - entities.created.previous_day + # Balances + - reserve_fbo_balance.created.previous_day + - team_fbo_balance.created.previous_day + example: payments.created.current + Report: type: object description: A Report is a downloadable file containing aggregated data about payments, entities, or other resources. @@ -16,22 +59,7 @@ Report: pattern: ^rpt_\w+$ example: rpt_cj2mkA3hFyHT5 type: - type: string - description: The type of report. - enum: - - payments.created.current - - payments.created.previous - - payments.created.previous_day - - payments.updated.current - - payments.updated.previous - - payments.failed.previous_day - - ach.pull.upcoming - - ach.pull.previous - - ach.pull.nightly - - ach.reversals.nightly - - ach.debit.daily - - entities.created.previous_day - - reserve_fbo_balance.created.previous_day + $ref: '#/ReportType' url: type: - string @@ -60,22 +88,7 @@ ReportCreateRequest: - type properties: type: - type: string - description: The type of report to generate. - enum: - - payments.created.current - - payments.created.previous - - payments.created.previous_day - - payments.updated.current - - payments.updated.previous - - payments.failed.previous_day - - ach.pull.upcoming - - ach.pull.previous - - ach.pull.nightly - - ach.reversals.nightly - - ach.debit.daily - - entities.created.previous_day - - reserve_fbo_balance.created.previous_day + $ref: '#/ReportType' ReportResponse: allOf: - $ref: common.yaml#/SuccessEnvelope diff --git a/openapi/components/schemas/report_schedule.yaml b/openapi/components/schemas/report_schedule.yaml new file mode 100644 index 0000000..4ee085d --- /dev/null +++ b/openapi/components/schemas/report_schedule.yaml @@ -0,0 +1,123 @@ +ReportScheduleType: + type: string + description: >- + The Report type generated by the schedule. Method owns the run cadence for each + supported type; the cadence is not configurable. All supported types currently run on + business days at 8:00am America/Chicago. Non-business-day runs are skipped and resume + on the next scheduled business day. + enum: + - ach.pull.nightly + - ach.reversals.nightly + - entities.created.previous_day + - payments.created.previous_day + - payments.failed.previous_day + - reversals.pull_funded.previous_day + - reversals.push_funded.previous_day + example: payments.created.previous_day + +ReportSchedule: + type: object + description: >- + A Report Schedule automates recurring generation of a single Report `type`. Each + scheduled run creates a Report exactly as `POST /reports` does, so it follows normal + Report persistence and triggers the standard `report.create` webhook. When + `email_recipients` are configured, Method also emails the CSV for the generated + Report. A team may have only one active schedule per `type`. + required: + - id + - type + - email_recipients + - status + - created_at + - updated_at + properties: + id: + type: string + description: Unique identifier for the report schedule. + pattern: ^rpt_sch_\w+$ + example: rpt_sch_Gqjh8pzeUfzH6 + type: + $ref: '#/ReportScheduleType' + email_recipients: + type: array + description: >- + Email addresses that receive the generated Report CSV after each run. An empty + array means no email is sent; the Report is still created. + items: + type: string + format: email + example: + - reports@example.com + status: + type: string + description: Current status of the report schedule. `active` schedules run on their cadence. + example: active + created_at: + type: string + format: date-time + description: Timestamp when the report schedule was created. + updated_at: + type: string + format: date-time + description: Timestamp when the report schedule was last updated. + example: + id: rpt_sch_Gqjh8pzeUfzH6 + type: payments.created.previous_day + email_recipients: + - reports@example.com + status: active + created_at: '2026-06-01T13:21:10.386Z' + updated_at: '2026-06-01T13:21:10.386Z' + +ReportScheduleCreateRequest: + type: object + description: >- + Request body for creating a report schedule. Creating a second schedule for a `type` + that already has an active schedule returns an error. + required: + - type + properties: + type: + $ref: '#/ReportScheduleType' + email_recipients: + type: array + description: Email addresses that receive the generated Report CSV after each run. + items: + type: string + format: email + example: + - reports@example.com + +ReportScheduleUpdateRequest: + type: object + description: >- + Request body for updating a report schedule. The schedule `type` and cadence cannot be + changed; create a new schedule instead. + properties: + email_recipients: + type: array + description: Replacement list of email addresses that receive the generated Report CSV. + items: + type: string + format: email + example: + - ops@example.com + - reports@example.com + +ReportScheduleResponse: + allOf: + - $ref: common.yaml#/SuccessEnvelope + - type: object + properties: + data: + $ref: '#/ReportSchedule' + +ReportScheduleListResponse: + allOf: + - $ref: common.yaml#/ListEnvelope + - type: object + properties: + data: + type: array + items: + $ref: '#/ReportSchedule' diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 48761c6..70753c1 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -90,8 +90,12 @@ tags: description: ACH and clearing payments - name: Payment Reversals description: Reversals for payments +- name: Preauth + description: PreauthSignals transaction success assessments - name: Reports description: Downloadable reports +- name: Report Schedules + description: Recurring report generation schedules - name: Secrets description: Secure secret storage - name: Teams @@ -243,12 +247,20 @@ paths: $ref: paths/payment_reversals.yaml#/collection /payments/{paymentId}/reversals/{reversalId}: $ref: paths/payment_reversals.yaml#/individual + /preauth: + $ref: paths/preauth.yaml#/collection + /preauth/{preauthId}: + $ref: paths/preauth.yaml#/individual /reports: $ref: paths/reports.yaml#/create /reports/{reportId}: $ref: paths/reports.yaml#/individual /reports/{reportId}/download: $ref: paths/reports.yaml#/download + /report_schedules: + $ref: paths/report_schedules.yaml#/collection + /report_schedules/{reportScheduleId}: + $ref: paths/report_schedules.yaml#/individual /secrets: $ref: paths/secrets.yaml#/collection /secrets/{id}: @@ -285,6 +297,8 @@ paths: $ref: paths/simulate/payments.yaml#/payment_instrument /opal/token: $ref: paths/opal.yaml#/token + /opal/events: + $ref: paths/opal.yaml#/events /elements/token: $ref: paths/elements/sk.yaml#/create_token /elements/token/{pk_elem_id}/results: diff --git a/openapi/paths/account_attributes.yaml b/openapi/paths/account_attributes.yaml index d278e25..e0903ec 100644 --- a/openapi/paths/account_attributes.yaml +++ b/openapi/paths/account_attributes.yaml @@ -46,7 +46,11 @@ collection: post: operationId: createAccountAttribute summary: Create an account attribute - description: Creates a new attribute request for the specified account. + description: >- + Creates a new attribute request to compute the account's attributes. The attributes + returned depend on the account's liability type. This operation is asynchronous: the + response returns immediately with `status` set and `attributes` null, and the final + result is available by polling the retrieve endpoint or subscribing to webhooks. tags: - Account Attributes security: @@ -55,6 +59,15 @@ collection: - $ref: ../components/parameters/method_version.yaml - $ref: ../components/parameters/idempotency_key.yaml - $ref: ../components/parameters/path_ids.yaml#/AccountIdParam + requestBody: + required: false + content: + application/json: + schema: + $ref: ../components/schemas/account.yaml#/AccountAttributeCreateRequest + example: + bundles: + - statement responses: '200': description: The newly created account attribute. diff --git a/openapi/paths/opal.yaml b/openapi/paths/opal.yaml index 10ce874..74ae375 100644 --- a/openapi/paths/opal.yaml +++ b/openapi/paths/opal.yaml @@ -102,3 +102,41 @@ token: $ref: ../components/responses/error.yaml#/RateLimited '500': $ref: ../components/responses/error.yaml#/InternalError +events: + get: + operationId: listOpalEvents + summary: List Opal session events + description: >- + Returns the events recorded during the Opal session associated with the + authenticated token. Event types follow the `..` pattern. + tags: + - Opal + security: + - OpalToken: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + responses: + '200': + description: The events recorded for the current Opal session. + content: + application/json: + schema: + $ref: ../components/schemas/opal.yaml#/OpalEventListResponse + example: + success: true + data: + - type: card_connect.flow.started + mode: card_connect + object: flow + action: started + timestamp: '2026-03-14T19:02:11.482Z' + data: null + message: null + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError diff --git a/openapi/paths/preauth.yaml b/openapi/paths/preauth.yaml new file mode 100644 index 0000000..9c28325 --- /dev/null +++ b/openapi/paths/preauth.yaml @@ -0,0 +1,132 @@ +collection: + get: + operationId: listPreauths + summary: List PreauthSignals assessments + description: Returns a paginated list of PreauthSignals assessments for the team. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/pagination.yaml#/PageParam + - $ref: ../components/parameters/pagination.yaml#/PageLimitParam + - $ref: ../components/parameters/pagination.yaml#/PageCursorParam + - $ref: ../components/parameters/pagination.yaml#/FromDateParam + - $ref: ../components/parameters/pagination.yaml#/ToDateParam + responses: + '200': + description: A list of PreauthSignals assessments. + headers: + $ref: ../components/responses/pagination_headers.yaml#/PaginationHeaders + content: + application/json: + schema: + $ref: ../components/schemas/preauth.yaml#/PreauthListResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError + post: + operationId: createPreauth + summary: Create PreauthSignals assessment + description: >- + Computes a PreauthSignals assessment for a given card or account. Provide either an + `account_id` for an authenticated Method Account, or a `card` object with raw card + identifiers. Exactly one of the two is required; supplying both returns a `400` + error. Optionally include `purchase` context to improve the prediction. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/idempotency_key.yaml + requestBody: + required: true + content: + application/json: + schema: + $ref: ../components/schemas/preauth.yaml#/PreauthCreateRequest + examples: + by_card: + summary: Assess raw card identifiers with purchase context + value: + card: + bin6: '411111' + last4: '1234' + first_name: Jane + last_name: Doe + phone: '+15555555555' + zip: '10001' + purchase: + amount: 9999 + mcc: '4511' + ip_address: 203.0.113.42 + txn_time: '2026-05-28T14:00:00Z' + by_account: + summary: Assess an authenticated Method Account + value: + account_id: acc_4m9amk4KFiaQX + responses: + '200': + description: The PreauthSignals assessment. + content: + application/json: + schema: + $ref: ../components/schemas/preauth.yaml#/PreauthResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '422': + $ref: ../components/responses/error.yaml#/UnprocessableEntity + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError +individual: + get: + operationId: retrievePreauth + summary: Retrieve a PreauthSignals assessment + description: Returns a single PreauthSignals assessment by its identifier. + tags: + - Preauth + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - name: preauthId + in: path + required: true + description: Unique identifier for the PreauthSignals assessment. + schema: + type: string + pattern: ^preauth_\w+$ + responses: + '200': + description: The requested PreauthSignals assessment. + content: + application/json: + schema: + $ref: ../components/schemas/preauth.yaml#/PreauthResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError diff --git a/openapi/paths/report_schedules.yaml b/openapi/paths/report_schedules.yaml new file mode 100644 index 0000000..2a19317 --- /dev/null +++ b/openapi/paths/report_schedules.yaml @@ -0,0 +1,209 @@ +collection: + get: + operationId: listReportSchedules + summary: List report schedules + description: Returns the report schedules configured for the team. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + responses: + '200': + description: A list of report schedules. + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleListResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError + post: + operationId: createReportSchedule + summary: Create a report schedule + description: >- + Creates a new active report schedule for a single supported Report `type`. Once + created, the schedule runs on Method's standard cadence for that type. A team may + have only one active schedule per `type`; creating a duplicate returns an error. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/idempotency_key.yaml + requestBody: + required: true + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleCreateRequest + example: + type: payments.created.previous_day + email_recipients: + - reports@example.com + responses: + '200': + description: The newly created report schedule. + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '422': + $ref: ../components/responses/error.yaml#/UnprocessableEntity + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError +individual: + get: + operationId: retrieveReportSchedule + summary: Retrieve a report schedule + description: Returns the report schedule associated with the identifier. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + responses: + '200': + description: The requested report schedule. + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError + put: + operationId: updateReportSchedule + summary: Update a report schedule + description: >- + Updates the `email_recipients` of an existing report schedule. The schedule `type` + and cadence cannot be changed. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/idempotency_key.yaml + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + requestBody: + required: true + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleUpdateRequest + example: + email_recipients: + - ops@example.com + - reports@example.com + responses: + '200': + description: The updated report schedule. + content: + application/json: + schema: + $ref: ../components/schemas/report_schedule.yaml#/ReportScheduleResponse + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '422': + $ref: ../components/responses/error.yaml#/UnprocessableEntity + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError + delete: + operationId: deleteReportSchedule + summary: Delete a report schedule + description: Deletes a report schedule, stopping all future runs. Returns an empty response. + tags: + - Report Schedules + security: + - SecretKey: [] + parameters: + - $ref: ../components/parameters/method_version.yaml + - $ref: ../components/parameters/idempotency_key.yaml + - name: reportScheduleId + in: path + required: true + description: Unique identifier for the report schedule. + schema: + type: string + pattern: ^rpt_sch_\w+$ + responses: + '200': + description: Report schedule deleted successfully. + content: + application/json: + schema: + type: object + required: [success, data, message] + properties: + success: + type: boolean + example: true + data: + type: 'null' + example: null + message: + type: ['null', string] + example: null + '400': + $ref: ../components/responses/error.yaml#/BadRequest + '401': + $ref: ../components/responses/error.yaml#/Unauthorized + '403': + $ref: ../components/responses/error.yaml#/Forbidden + '404': + $ref: ../components/responses/error.yaml#/NotFound + '422': + $ref: ../components/responses/error.yaml#/UnprocessableEntity + '429': + $ref: ../components/responses/error.yaml#/RateLimited + '500': + $ref: ../components/responses/error.yaml#/InternalError