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:
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):
For Payers (Payins - Money In):
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:
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
- Add a payment method (
POST .../pay-to-bank,.../push-to-card, or.../pay-by-bank). Create always returns 201 withverification_status: pendingandis_default: false. There is no create-timeis_defaultrequest parameter. - Verify — wait for the
payment_method.verifiedwebhook (or poll GET payment methods untilverified). - Set default — call
POST .../payment-methods/{payment_method_id}/set-defaultonce the method isverified.
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
verifiedpayment 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)
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:
- The payment method cannot be the current default. You must first set another verified payment method as default.
- Only the owning payee or payer (
party_id/party_type), 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.