> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.useroot.com/api-reference/payment-methods-api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.useroot.com/_mcp/server. # Payment Methods API The **Payment Methods API** allows you to manage payment methods for both payees (for payouts) and payers (for payins). Payment methods are scoped by path to a payee or payer (`payee_id` / `payer_id`). Each payee or payer (`party_type`) identified by `party_id` can have multiple payment methods. Our platform uses vault technology to secure sensitive data with tokenization, encryption, and access control, ensuring compliance with PCI. This allows safe storage and processing of data without exposing raw information, enabling secure and privacy-conscious interactions. ## Authentication Payment-method endpoints accept either: | Method | Header | Typical use | | ------------- | ------------------------------- | ------------------------------------------------ | | API key | `x-api-key: ` | Server-to-server | | Session token | `Authorization: Bearer ` | Frontend / embedded flows for one payee or payer | Mint session tokens with the **Session Tokens API** (`POST /api/session-tokens/party`), then send the returned JWT as a Bearer token. The token is limited to that party's payment methods and expires after a short TTL — see the Session Tokens API overview for scopes and security guidance. ## Payment Methods A **Payment Method** represents the payment configuration associated with a payee or payer. It contains key details necessary for initiating transactions, such as account number, routing number, and card details. ### Payment Method Types The API supports different payment method types based on the use case: **For Payees (Payouts - Money Out):** | Type | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `bank_account` | Direct bank transfer (pay-to-bank). Field requirements vary by country and currency — see **Country and Currency**. | | `card` | Push-to-card payment method. Available markets and currencies depend on your integration and card program. | ![Bank%20Payment%20Method](https://content.pstmn.io/2a0200f6-789a-420b-8abe-0051bc77a412/UGF5bWVudERldGFpbHMtQmFua0FjY291bnQuZ2lm)![Debit%20Card%20Payment%20Method](https://content.pstmn.io/a0f270b2-915b-4603-a001-cf42b179edde/UGF5bWVudERldGFpbHMtRGViaXQuZ2lm) **For Payers (Payins - Money In):** | Type | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `bank_account` | Pay-by-bank for pulling funds from payer accounts. Field requirements vary by country and currency — see **Country and Currency**. | ### Country and currency Payment methods are associated with a market through **`country_code`** and **`currency_code`**. Requirements differ by payment method type and market. **Bank accounts** — field shapes, supported combinations, and verification behavior by currency are documented under **Country and Currency**. **Cards** — push-to-card programs may support additional markets and currencies over time. Use the Payee Payment Methods API card endpoints for request and response details for your integration. ### Verification Status Lifecycle Payment methods go through a verification process with the following statuses: | Status | Description | | ---------- | ------------------------------------------------------------------ | | `pending` | Verification process has been initiated | | `verified` | Payment method has been successfully verified and can be used | | `failed` | Verification process failed due to invalid details or other issues | ### Default Payment Method Each payee or payer can have one payment method designated as the default. Payouts and payins use that default unless you pass an override (`override_default_payment_method_id` on payouts, `payment_method_id` on payins). **Required flow** 1. **Add** a payment method (`POST .../pay-to-bank`, `.../push-to-card`, or `.../pay-by-bank`). Create always returns **201** with **`verification_status: pending`** and **`is_default: false`**. There is no create-time `is_default` request parameter. 2. **Verify** — wait for the `payment_method.verified` webhook (or poll GET payment methods until `verified`). 3. **Set default** — call `POST .../payment-methods/{payment_method_id}/set-default` once the method is `verified`. Until a default is set, creating a payout/payin without an override returns **404** `NOT_FOUND` with `details.reason: "no_default_payment_method"` (plus `party_type`, `party_id`, and legacy `payor_id`). Status code and `error_code` stay **404** / **NOT_FOUND** for backward compatibility. * Only **`verified`** payment methods can be set as default * Attempting to set an unverified payment method as default returns an error * As an alternative to setting a default, pass a verified payment method id on the transfer (`override_default_payment_method_id` / `payment_method_id`) ![Set%20Default%20Payment%20Method](https://content.pstmn.io/b82928fd-1471-415c-8d67-9fb87d69494c/U2V0RGVmYXVsdFBheW1lbnQuZ2lm) A payment method in **`pending`** or **`failed`** cannot be set as the default. ### Deleting a Payment Method A payment method can be deleted when it is no longer needed. Deleting a payment method removes it from day-to-day operations while preserving the record for audit and reporting purposes. Delete restrictions: 1. The payment method **cannot** be the current default. You must first set another verified payment method as default. 2. Only the owning payee or payer (`party_id` / `party_type`), or an authorized admin/API key, can delete their own payment methods. 3. The operation returns **HTTP 204 No Content** on success. Use the appropriate endpoint to perform the deletion: * For payees: `DELETE /api/payees/{payee_id}/payment-methods/{payment_method_id}` * For payers: `DELETE /api/payers/{payer_id}/payment-methods/{payment_method_id}` See the endpoint reference below for detailed request and response information and examples. ## Docs - [Country and Currency](https://docs.useroot.com/api-reference/payment-methods-api/country-and-currency.md) ## API Docs - [Add bank payment method](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/add-payee-bank-payment-method.md): Payee Payment Methods API - [Add card payment method](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/add-payee-card-payment-method.md): Payee Payment Methods API - [List payment methods](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/list-payee-payment-methods.md): Payee Payment Methods API - [Get default payment method](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/get-payee-default-payment-method.md): Payee Payment Methods API - [Get payment method by ID](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/get-payee-payment-method-by-id.md): Payee Payment Methods API - [Delete payment method](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/delete-payee-payment-method.md): Payee Payment Methods API - [Set default payment method](https://docs.useroot.com/api-reference/payment-methods-api/payee-payment-methods-api/set-payee-default-payment-method.md): Payee Payment Methods API - [Add bank payment method for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/add-payer-bank-payment-method.md): Payer Payment Methods API - [List payment methods for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/list-payer-payment-methods.md): Payer Payment Methods API - [Get default payment method for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/get-payer-default-payment-method.md): Payer Payment Methods API - [Get payment method by ID for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/get-payer-payment-method-by-id.md): Payer Payment Methods API - [Delete payment method for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/delete-payer-payment-method.md): Payer Payment Methods API - [Set default payment method for payer](https://docs.useroot.com/api-reference/payment-methods-api/payer-payment-methods-api/set-payer-default-payment-method.md): Payer Payment Methods API ## OpenAPI Specification - [OpenAPI JSON](https://docs.useroot.com/openapi.json): raw OpenAPI 3.1 specification for this API, JSON format - [OpenAPI YAML](https://docs.useroot.com/openapi.yaml): raw OpenAPI 3.1 specification for this API, YAML format