Skip to navigation

Add bank payment method

View as Markdown

Adds a new bank account payment method for a payee. Supports pay-to-bank transfers with account and routing number details for United States and Great Britain bank accounts.

The payment method is created as pending and returns 201. Account verification runs asynchronously. Use GET payment methods or payment_method.verified / payment_method.failed webhooks to observe the terminal status. Create-time default is not applied — call set-default after verified.

Path Parameters

ParameterTypeRequiredDescription
payee_idUUIDYesID of the payee to add the payment method to

Request Body — bank account shapes

Send country_code, currency_code, routing_number_type, account_number, and routing_number consistent with one of the supported rows below. Internally inconsistent combinations (for example US country with an IBAN-shaped account, or GB with ABA routing) return 400 validation errors.

Regioncountry_codecurrency_coderouting_number_typeaccount_numberrouting_number
United StatesUSUSDaba (default)Domestic US account number (digits; not IBAN-shaped)9-digit ABA routing number
Great BritainGBGBPbicValid GB IBANBIC / SWIFT (8 or 11 characters)

When country_code and currency_code are omitted
They default to US and USD; routing_number_type defaults to aba.

Great Britain notes

  • IBAN must validate structurally (including check digits) and use the GB country prefix for v1.
  • On create, verification returns pending; use GET list/detail on payment methods or webhooks to observe verified or failed.

Request Body fields

FieldTypeRequiredDescriptionValidation Rules
account_numberStringYesAccount identifierUS: digits-only domestic account (max length per API). GB: IBAN (GB prefix, valid checksum).
routing_numberStringYesRouting identifierUS: 9-digit ABA. GB: BIC/SWIFT per routing_number_type bic.
routing_number_typeStringNoaba or bicMust match country_code row in the matrix above (GB requires bic).
currency_codeStringNoISO 4217 codeMust pair with country_code per supported pairs (USD↔US, GBP↔GB).
country_codeStringNoISO 3166-1 alpha-2US or GB for supported payee bank accounts.

Response Body

FieldTypeDescription
idUUIDUnique identifier for the payment method
payee_idUUIDID of the payee associated with the payment method
account_last_fourStringLast four characters/digits derived from the account number for display
routing_numberStringRouting identifier stored for the payment method
currency_codeStringISO 4217 currency code of the account
country_codeStringISO 3166-1 alpha-2 country code of the bank account
verification_statusStringCurrent verification status (pending, verified, or failed)
is_defaultBooleanWhether this is the default payment method for the payee (always false on create)
supported_railsArrayRails available for this payment method given country, currency, and bank configuration
created_atDateTimeTimestamp when the payment method was created
updated_atDateTimeTimestamp when the payment method was last updated

Success Responses

Status CodeDescription
201Created — payment method persisted as pending; verification continues asynchronously

Error Responses

Status CodeError CodeDescription
400VALIDATION_ERRORThe provided data failed validation
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action
404NOT_FOUNDThe specified payee was not found
409DUPLICATE_RESOURCEA payment method with these details already exists
422INVALID_PAYMENT_DETAILSThe payment details are invalid or incomplete

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

OR
AuthorizationBearer

Short-lived session JWT from the Session Tokens API. Send as Authorization: Bearer <token>. Accepted on payment-method endpoints for a specific payee or payer; mint tokens with an API key.

Path parameters

payee_idstringRequiredformat: "uuid"

Request

This endpoint expects an object.
account_numberstringRequired<=100 characters
routing_numberstringRequired<=11 characters
routing_number_typeenumOptional

aba (US), bic (GB), or ifsc (IN)

Allowed values:
currency_codeenumOptional

USD (US), GBP (GB), or INR (IN)

Allowed values:
country_codeenumOptional
US, GB, or IN
Allowed values:

Response

Bank payment method created as pending; verification continues asynchronously

dataobject

Shared response model for bank payment methods (both payee and payer).

warningstring or nullOptional