Payment Methods API

The Payment Methods API allows you to manage payment methods for both payees (for payouts) and payers (for payins). Payment methods can be added using their unique payee_id or payer_id. Each party 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.

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.

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. The default payment method is automatically used for transactions unless otherwise specified.

A payment method can only be set as default if its verification status is verified
When adding a new payment method, you can specify whether it should be set as default using the is_default parameter
If is_default is set to true but the payment method is not verified, it will be created but not set as default, and a warning will be returned
The default can be changed using the Set Default Payment Method API, but only verified payment methods can be set as default
Attempting to set an unverified payment method as default will result in an error

A payment method in pending or failed cannot be set as the default. If a payment method is created but not set as default for this reason, the response includes a warning field (207 Multi-Status).

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:

The payment method cannot be the current default. You must first set another verified payment method as default.
Only the party owner (or an authorized admin/API key) can delete their own payment methods.
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.