Skip to navigation

Add card payment method

View as Markdown

Adds a new card payment method for a payee. Supports push-to-card payments with card number and expiry details.

The payment method is created as pending and returns 201. Card verification continues 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

FieldTypeRequiredDescriptionValidation Rules
card_numberStringYesCard numberMust contain only digits (0-9). Must pass Luhn check
card_expiry_dateStringYesCard expiry date in YYMM formatMust be 4 digits. Must be a future date

Query Parameters

ParameterTypeRequiredDescription
is_defaultBooleanNoIgnored on create. Kept for compatibility. Set default via POST .../set-default after verified.

Response Body

FieldTypeDescription
idUUIDUnique identifier for the payment method
payee_idUUIDID of the payee associated with the payment method
card_last_fourStringLast four digits of the card number (for cards)
card_expiry_dateStringExpiry date of the card in YYMM format (for cards)
currency_codeStringISO 4217 currency code. Always USD — card payments are US-only.
country_codeStringISO 3166-1 alpha-2 country code. Always US — card payments are US-only.
verification_statusStringCurrent verification status (pending, verified, or failed)
is_defaultBooleanWhether this is the default payment method for the payee (always false on create for this path)
supported_railsArrayList of supported payment rails for this payment method
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
400CARD_VERIFICATION_FAILEDCard type not supported (e.g. credit instead of debit). User should provide a debit card.
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
503CARD_VERIFICATION_SERVICE_ERRORCard verification service (tokenization, lookup) temporarily unavailable. Retry with exponential backoff.

Authentication

x-api-keystring

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

Path parameters

payee_idstringRequiredformat: "uuid"

Query parameters

is_defaultbooleanOptionalDefaults to true

Ignored on create. Default is set only via POST …/set-default after verification_status is verified.

Request

This endpoint expects an object.
card_numberstringRequired<=16 characters
card_expiry_datestringRequired=4 characters
country_codeenumOptional

Country associated with this card payment method (ISO 3166-1 alpha-2)

Allowed values:

Response

Card payment method created as pending; verification continues asynchronously

dataobject
warningstring or nullOptional