Method Financial Payments API
ACH and clearing payments
ACH and clearing payments
openapi: 3.2.0
info:
title: Method Payments API
version: '2026-03-30'
license:
name: Proprietary
url: https://methodfi.com
description: "The Method API enables you to retrieve financial data, create payments, and manage\nentities and accounts programmatically. This specification covers the public API\nsurface for version `2026-03-30`.\n\n## Authentication\n\nMost API requests require a Bearer token in the `Authorization` header.\nUse your secret key (`sk_...`) for server-side requests and public key (`pk_...`)\nfor client-side Element requests. Public Message-Level Encryption key discovery\nendpoints are documented separately and do not require authentication.\n\n## Versioning\n\nThe API version is selected via the `Method-Version` header. This spec targets\nversion `2026-03-30`. The SDK sets this header automatically.\n\n## Response Envelope\n\nMost JSON responses are wrapped in a standard envelope:\n\n```json\n{\n \"success\": true,\n \"data\": { ... },\n \"message\": null\n}\n```\n\nThe `/.well-known/jwks.json` endpoint is an exception and returns a bare JWK set.\n\n## Pagination\n\nList endpoints return pagination metadata in response headers:\n`Pagination-Page`, `Pagination-Page-Count`, `Pagination-Page-Limit`,\n`Pagination-Total-Count`, `Pagination-Page-Cursor-Prev`, `Pagination-Page-Cursor-Next`.\n\n## Expandable Fields\n\nCertain resource fields can be expanded from IDs to full objects using the\n`expand` query parameter. Maximum nesting depth is 4 levels.\n"
contact:
name: Method Financial
url: https://methodfi.com
email: team@methodfi.com
servers:
- url: https://production.methodfi.com
description: Production
x-fern-server-name: Production
- url: https://sandbox.methodfi.com
description: Sandbox
x-fern-server-name: Sandbox
- url: https://dev.methodfi.com
description: Development
x-fern-server-name: Development
security:
- SecretKey: []
tags:
- name: Payments
description: ACH and clearing payments
paths:
/payments:
get:
operationId: listPayments
summary: List all payments
description: Returns a paginated list of payments. Results can be filtered by status, type, accounts, holders, reversal, and date range.
tags:
- Payments
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'
- name: status
in: query
required: false
description: Filter payments by status.
schema:
type: string
enum:
- pending
- processing
- sent
- posted
- settled
- failed
- reversed
- canceled
- cashed
- name: source
in: query
required: false
description: Filter payments by source account ID.
schema:
type: string
pattern: ^acc_\w+$
- name: destination
in: query
required: false
description: Filter payments by destination account ID.
schema:
type: string
pattern: ^acc_\w+$
- name: type
in: query
required: false
description: Filter payments by payment type.
schema:
type: string
enum:
- standard
- clearing
- name: reversal_id
in: query
required: false
description: Filter payments by reversal ID.
schema:
type: string
pattern: ^rvs_\w+$
- name: acc_id
in: query
required: false
description: Filter payments by either the source or destination account ID.
schema:
type: string
pattern: ^acc_\w+$
- name: destination_holder_id
in: query
required: false
description: Filter payments by destination entity ID.
schema:
type: string
pattern: ^ent_\w+$
- name: source_holder_id
in: query
required: false
description: Filter payments by source entity ID.
schema:
type: string
pattern: ^ent_\w+$
- name: holder_id
in: query
required: false
description: Filter payments by either the source or destination entity ID.
schema:
type: string
pattern: ^ent_\w+$
- $ref: '#/components/parameters/expand_payments'
responses:
'200':
description: A paginated list of payments.
headers:
Pagination-Page:
$ref: '#/components/headers/Pagination-Page'
Pagination-Page-Count:
$ref: '#/components/headers/Pagination-Page-Count'
Pagination-Page-Limit:
$ref: '#/components/headers/Pagination-Page-Limit'
Pagination-Total-Count:
$ref: '#/components/headers/Pagination-Total-Count'
Pagination-Page-Cursor-Prev:
$ref: '#/components/headers/Pagination-Page-Cursor-Prev'
Pagination-Page-Cursor-Next:
$ref: '#/components/headers/Pagination-Page-Cursor-Next'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentListResponse'
'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'
post:
operationId: createPayment
summary: Create a payment
description: Creates a new payment to transfer funds from a source account to a destination account.
tags:
- Payments
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/idempotency_key'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCreateRequest'
examples:
standard:
summary: Create a standard payment
value:
source: acc_b9q2XVAnNFbp3
destination: acc_Y8u3qL9mNa1Bz
amount: 5000
description: Monthly card payment
metadata:
invoice_id: inv_1001
clearing:
summary: Create a clearing payment with a fee
value:
source: acc_b9q2XVAnNFbp3
destination: acc_Y8u3qL9mNa1Bz
amount: 25000
description: Settlement transfer
fee:
type: total
amount: 250
responses:
'200':
description: The newly created payment.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
example:
success: true
data:
id: pmt_rPrDPEwyCVUcm
reversal_id: null
source_trace_id: null
destination_trace_id: null
source: acc_b9q2XVAnNFbp3
destination: acc_Y8u3qL9mNa1Bz
amount: 5000
description: Monthly card payment
status: pending
fund_status: transmitting
estimated_completion_date: '2026-01-19'
source_settlement_date: null
destination_settlement_date: null
source_status: null
destination_status: null
destination_payment_method: null
fee: null
type: standard
error: null
metadata:
invoice_id: inv_1001
created_at: '2026-01-15T18:30:00.000Z'
updated_at: '2026-01-15T18:30:00.000Z'
message: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
/payments/{paymentId}:
get:
operationId: retrievePayment
summary: Retrieve a payment
description: Retrieves a payment by its unique identifier.
tags:
- Payments
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/PaymentIdParam'
- $ref: '#/components/parameters/expand_payments'
responses:
'200':
description: The requested payment.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'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'
delete:
operationId: deletePayment
summary: Delete a payment
description: Cancels a pending payment. Only payments with a `pending` status can be canceled.
tags:
- Payments
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/PaymentIdParam'
- $ref: '#/components/parameters/idempotency_key'
responses:
'200':
description: The canceled payment.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
ListEnvelope:
type: object
description: Standard envelope for successful responses that return a list payload.
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `true` for successful responses.
data:
description: Operation-specific list payload.
message:
type:
- string
- 'null'
example:
success: true
data: []
message: null
Merchant:
type: object
required:
- id
- parent_name
- name
- logo
- type
- provider_ids
- is_temp
- account_number_formats
properties:
id:
type: string
description: Unique identifier for the merchant.
example: mch_aTJMbnCjw34yQ
parent_name:
type: string
description: Name of the parent merchant group.
example: Chase
name:
type: string
description: Display name of the merchant.
example: Chase - Credit Cards
logo:
type: string
description: URL of the merchant logo.
example: https://static.methodfi.com/logos/chase.png
type:
$ref: '#/components/schemas/MerchantType'
description: Type of accounts supported by this merchant.
provider_ids:
$ref: '#/components/schemas/MerchantProviderIds'
is_temp:
type: boolean
description: Whether this is a temporary merchant entry.
account_number_formats:
type: array
items:
type: string
description: Accepted account number formats.
AccountExpandableAttribute:
title: AccountExpandableAttribute
description: 'The latest attribute ID. This field is expandable. When expanded, returns the full AccountAttribute object.
'
oneOf:
- type: string
pattern: ^acc_attr_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountAttribute'
Account:
type: object
description: 'An Account represents a financial account (ACH, liability, clearing, or debit card) associated with an Entity. The `type` field indicates which nested details object (`ach`, `liability`, `clearing`, or `debit_card`) is populated. `type` is null for accounts that are disabled before a type was determined.
'
required:
- id
- holder_id
- type
- status
- consent_status
- products
- restricted_products
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the account.
pattern: ^acc_\w+$
example: acc_b9q2XVAnNFbp3
holder_id:
type: string
description: The entity ID that owns this account.
pattern: ^ent_\w+$
example: ent_au22b1fbFJbp8
type:
type:
- string
- 'null'
description: The type of account. Null for accounts that are disabled before a type was determined.
enum:
- ach
- liability
- clearing
- debit_card
- null
status:
type: string
description: Current status of the account.
enum:
- active
- disabled
- processing
- pending_exchange
- closed
consent_status:
type: string
description: Current consent status for data access on this account.
enum:
- pending
- withdrawn
- approved
ach:
$ref: '#/components/schemas/AccountACH'
liability:
$ref: '#/components/schemas/AccountLiability'
clearing:
$ref: '#/components/schemas/AccountClearing'
debit_card:
$ref: '#/components/schemas/AccountDebitCard'
error:
$ref: '#/components/schemas/AccountResourceError'
metadata:
$ref: '#/components/schemas/Metadata'
products:
type: array
description: Products currently active for this account.
items:
type: string
restricted_products:
type: array
description: Products restricted from this account.
items:
type: string
subscriptions:
type: array
description: Subscriptions currently active for this account. Only present for liability accounts.
items:
type: string
available_subscriptions:
type: array
description: Subscriptions available to be enrolled for this account. Only present for liability accounts.
items:
type: string
restricted_subscriptions:
type: array
description: Subscriptions restricted from this account. Only present for liability accounts.
items:
type: string
latest_verification_session:
title: AccountExpandableLatestVerificationSession
description: 'The latest verification session ID. This field is expandable. When expanded, returns the full AccountVerificationSession object.
'
oneOf:
- type: string
pattern: ^avf_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountVerificationSession'
balance:
$ref: '#/components/schemas/AccountExpandableBalance'
payoff:
$ref: '#/components/schemas/AccountExpandablePayoff'
payment_instrument:
$ref: '#/components/schemas/AccountExpandablePaymentInstrument'
card_brand:
$ref: '#/components/schemas/AccountExpandableCardBrand'
update:
$ref: '#/components/schemas/AccountExpandableUpdate'
attribute:
$ref: '#/components/schemas/AccountExpandableAttribute'
sensitive:
$ref: '#/components/schemas/AccountExpandableSensitive'
created_at:
type: string
format: date-time
description: Timestamp when the account was created.
updated_at:
type: string
format: date-time
description: Timestamp when the account was last updated.
AccountDebitCard:
type:
- object
- 'null'
description: Debit card account details. Present when `type` is `debit_card`.
properties:
network:
type: string
description: The card network.
mask:
type: string
description: Last 4 digits of the card number.
issuer:
type: string
description: The card issuer.
AccountSensitiveResourceError:
type:
- object
- 'null'
description: Error details when retrieving account sensitive data fails.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of sensitive data error.
enum:
- ACCOUNT_SENSITIVE_FAILED
code:
type: integer
description: Numeric error code (17XXX range).
enum:
- 17001
sub_type:
type: string
description: Specific sensitive data error classification.
enum:
- ACCOUNT_SENSITIVE_FAILED_VERIFICATION_REQUIRED
message:
type: string
description: Human-readable error description.
example:
type: ACCOUNT_SENSITIVE_FAILED
code: 17001
sub_type: ACCOUNT_SENSITIVE_FAILED_VERIFICATION_REQUIRED
message: Account sensitive failed due to missing required verification.
AccountExpandablePaymentInstrument:
title: AccountExpandablePaymentInstrument
description: 'The latest payment instrument ID. This field is expandable. When expanded, returns the full AccountPaymentInstrument object.
'
oneOf:
- type: string
pattern: ^pmt_inst_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountPaymentInstrument'
ErrorEnvelope:
type: object
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `false` for error responses.
data:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
message:
type: string
ResourceError:
type:
- object
- 'null'
required:
- type
- code
- message
properties:
type:
type: string
code:
type: integer
sub_type:
type:
- string
- 'null'
message:
type: string
BalanceResourceError:
type:
- object
- 'null'
description: Error details when a balance sync fails.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of balance error.
enum:
- BALANCE_FAILED
code:
type: integer
description: Numeric error code (20XXX range).
enum:
- 20001
sub_type:
type: string
description: Specific balance error classification.
enum:
- BALANCE_TEMPORARILY_UNAVAILABLE
message:
type: string
description: Human-readable error description.
example:
type: BALANCE_FAILED
code: 20001
sub_type: BALANCE_TEMPORARILY_UNAVAILABLE
message: Balance is temporarily unavailable for this account.
AccountExpandableSensitive:
title: AccountExpandableSensitive
description: 'The latest sensitive ID. This field is expandable. When expanded, returns the full AccountSensitive object.
'
oneOf:
- type: string
pattern: ^astv_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountSensitive'
Payment:
type: object
description: A Payment represents a transfer of funds between two accounts.
required:
- id
- source
- destination
- amount
- status
- type
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the payment.
pattern: ^pmt_\w+$
example: pmt_rPrDPEwyCVUcm
reversal_id:
type:
- string
- 'null'
description: Identifier of the associated reversal, if any.
pattern: ^rvs_\w+$
reversal_account:
type:
- string
- 'null'
description: Account ID used for the reversal leg of the payment.
pattern: ^acc_\w+$
payment_instrument:
type:
- string
- 'null'
description: Identifier of the payment instrument used to create this payment, if any.
pattern: ^pmt_inst_\w+$
example: pmt_inst_aTJMbnCjw34yQ
source_trace_id:
type:
- string
- 'null'
description: Trace identifier for the source side of the payment.
destination_trace_id:
type:
- string
- 'null'
description: Trace identifier for the destination side of the payment.
source:
title: PaymentExpandableSource
description: 'The source account ID. This field is expandable. When expanded, returns the full Account object.
'
anyOf:
- type: string
pattern: ^acc_\w+$
- type: 'null'
- $ref: '#/components/schemas/Account'
destination:
title: PaymentExpandableDestination
description: 'The destination account ID. This field is expandable. When expanded, returns the full Account object.
'
anyOf:
- type: string
pattern: ^acc_\w+$
- type: 'null'
- $ref: '#/components/schemas/Account'
amount:
type: integer
description: Payment amount in cents.
minimum: 0
example: 5000
description:
type:
- string
- 'null'
description: Human-readable description for the payment.
status:
type: string
description: Current status of the payment.
enum:
- pending
- processing
- sent
- posted
- settled
- failed
- reversed
- canceled
- cashed
fund_status:
type:
- string
- 'null'
description: The current status of the payment funds.
enum:
- transmitting
- transmitted
- requested
- clearing
- pending
- hold
- sent
- posted
- cashed
- unknown
- pending_consolidation
- pending_clearing
- failed
- null
estimated_completion_date:
type:
- string
- 'null'
format: date
description: Estimated date when the payment will be completed (YYYY-MM-DD).
source_settlement_date:
type:
- string
- 'null'
format: date
description: The expected or actual settlement date for the source side of the payment.
destination_settlement_date:
type:
- string
- 'null'
format: date
description: The expected or actual settlement date for the destination side of the payment.
destination_posted_date:
type:
- string
- 'null'
format: date
description: The date the destination side of the payment was posted.
source_status:
type:
- string
- 'null'
description: The status of the source side of the payment.
destination_status:
type:
- string
- 'null'
description: The status of the destination side of the payment.
destination_payment_method:
type:
- string
- 'null'
description: The payment method used for the destination.
fee:
type:
- object
- 'null'
description: Fee associated with the payment.
required:
- type
- amount
properties:
type:
type: string
description: The fee type.
enum:
- total
amount:
type: integer
description: Fee amount in cents.
minimum: 0
type:
type: string
description: The type of payment.
enum:
- standard
- clearing
error:
$ref: '#/components/schemas/PaymentResourceError'
idempotency_key:
type:
- string
- 'null'
description: The idempotency key provided when the payment was created, if any.
metadata:
$ref: '#/components/schemas/Metadata'
created_at:
type: string
format: date-time
description: Timestamp when the payment was created.
updated_at:
type: string
format: date-time
description: Timestamp when the payment was last updated.
AccountBalance:
type: object
description: A balance record for an account.
required:
- id
- account_id
- status
- amount
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the balance.
pattern: ^bal_\w+$
example: bal_dKe9ehC3hEBYy
account_id:
type: string
description: The account this balance belongs to.
pattern: ^acc_\w+$
status:
type: string
description: Current status of the balance request.
enum:
- completed
- pending
- failed
amount:
type:
- number
- 'null'
description: The balance amount in cents.
error:
$ref: '#/components/schemas/BalanceResourceError'
created_at:
type: string
format: date-time
description: Timestamp when the balance was created.
updated_at:
type: string
format: date-time
description: Timestamp when the balance was last updated.
PaymentResourceError:
type:
- object
- 'null'
description: Error details when a payment fails or is canceled.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of payment error.
enum:
- PAYMENT_FAILED
- PAYMENT_CANCELED
code:
type: integer
description: Numeric error code (10XXX range).
enum:
- 10001
- 10002
- 10003
- 10004
- 10005
- 10006
- 10007
- 10008
- 10009
- 10010
sub_type:
type: string
description: Specific payment error classification.
enum:
- PAYMENT_INSUFFICIENT_FUNDS
- PAYMENT_UNAUTHORIZED
- PAYMENT_INVALID_ACCOUNT
- PAYMENT_UNAUTHORIZED_SOURCE
- PAYMENT_UNAUTHORIZED_DESTINATION
- PAYMENT_INVALID_SOURCE_ACCOUNT
- PAYMENT_INVALID_DESTINATION_ACCOUNT
- PAYMENT_REJECTED_BY_DESTINATION_INSTITUTION
- PAYMENT_REJECTED_INVALID_AMOUNT
message:
type: string
description: Human-readable error description.
example:
type: PAYMENT_FAILED
code: 10001
sub_type: PAYMENT_INSUFFICIENT_FUNDS
message: Payment failed due to insufficient funds from the source account.
AccountExpandablePayoff:
title: AccountExpandablePayoff
description: 'The latest payoff ID. This field is expandable. When expanded, returns the full AccountPayoff object.
'
oneOf:
- type: string
pattern: ^pyf_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountPayoff'
SuccessEnvelope:
type: object
description: Standard envelope for successful responses that return a single payload.
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `true` for successful responses.
data:
description: Operation-specific response payload.
message:
type:
- string
- 'null'
example:
success: true
data: {}
message: null
PaymentListResponse:
allOf:
- $ref: '#/components/schemas/ListEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Payment'
AccountExpandableUpdate:
title: AccountExpandableUpdate
description: 'The latest update ID. This field is expandable. When expanded, returns the full AccountUpdate object.
'
oneOf:
- type: string
pattern: ^upd_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountUpdate'
AccountExpandableBalance:
title: AccountExpandableBalance
description: 'The latest balance ID. This field is expandable. When expanded, returns the full AccountBalance object.
'
oneOf:
- type: string
pattern: ^bal_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountBalance'
AccountAttribute:
type: object
description: An attribute record for an account containing financial data attributes.
required:
- id
- account_id
- status
- attributes
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the account attribute.
pattern: ^acc_attr_\w+$
example: acc_attr_eTJMbnCjw34yQ
account_id:
type: string
description: The account this attribute belongs to.
pattern: ^acc_\w+$
status:
type: string
description: Current status of the attribute request.
enum:
- completed
- pending
- failed
attributes:
type: object
description: Financial data attributes for the account.
additionalProperties: true
error:
$ref: '#/components/schemas/ResourceError'
created_at:
type: string
format: date-time
description: Timestamp when the attribute was created.
updated_at:
type: string
format: date-time
description: Timestamp when the attribute was last updated.
PaymentResponse:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/Payment'
AccountACH:
type:
- object
- 'null'
description: ACH account details. Present when `type` is `ach`.
properties:
routing:
type: string
description: The ACH routing number.
number:
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/method-financial/refs/heads/main/openapi/method-financial-payments-api-openapi.yml