Skip to navigation

Payment Methods API

View as Markdown

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:

MethodHeaderTypical use
API keyx-api-key: <key>Server-to-server
Session tokenAuthorization: Bearer <token>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):

TypeDescription
bank_accountDirect bank transfer (pay-to-bank). Field requirements vary by country and currency — see Country and Currency.
cardPush-to-card payment method. Available markets and currencies depend on your integration and card program.
Bank%20Payment%20Method Debit%20Card%20Payment%20Method

For Payers (Payins - Money In):

TypeDescription
bank_accountPay-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:

StatusDescription
pendingVerification process has been initiated
verifiedPayment method has been successfully verified and can be used
failedVerification 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

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.