SFTP Payment Methods

The /payment-methods folder allows you to create or update payment methods in bulk via SFTP. This is useful for migrating existing payment data or onboarding large customer bases.

File Format

Upload CSV files to the /payment-methods folder. The CSV should use dot notation to match the Payment Method Creation API structure.

Required Fields

Field	Description	Required	Example
`customer_ref`	Customer reference ID	Yes	`CUST001`
`type`	Payment method type	Yes	`CreditCard`, `ACH`, `Token`
`ownerName`	Payment method owner name	Yes	`John Doe`
`address.street`	Street address	No	`123 Main St`
`address.city`	City	No	`Springfield`
`address.state`	State/province	No	`IL`
`address.zip`	ZIP/postal code	No	`62701`
`address.country`	Country code	No	`US`

Type-Specific Fields

CreditCard

Field	Description	Required
`traits.cardNumber`	Full card number	Yes
`traits.expirationMonth`	Expiration month (1-12)	Yes
`traits.expirationYear`	Expiration year (YYYY)	Yes
`traits.cvv`	CVV code	No

ACH

Field	Description	Required
`subType`	Account type	Yes
`traits.routingNumber`	Bank routing number	Yes
`traits.accountNumber`	Bank account number	Yes

Token

Field	Description	Required
`token`	Token identifier	Yes
`originatingId`	Original payment method ID	No
`traits.tokenType`	Type of underlying payment method	No
`traits.provider`	Token provider	No

Example CSV

customer_ref,type,ownerName,address.street,address.city,address.state,address.zip,address.country,traits.cardNumber,traits.expirationMonth,traits.expirationYear,traits.cvv
CUST001,CreditCard,John Doe,123 Main St,Springfield,IL,62701,US,4111111111111111,12,2028,123
CUST002,ACH,Jane Smith,456 Elm St,Metropolis,NY,10001,US,021000021,123456789,,
CUST003,Token,Alice Johnson,789 Oak Ave,Gotham,NJ,07001,US,tok_abc123,,,,

Processing

For each valid record:

Customer lookup: Verify customer exists
Payment method creation: Create payment method via API
Token creation: Generate tokens if auto-tokenization enabled
Permission setup: Establish proper permissions
Status update: Mark record as processed

Error Codes

Code	Description	Resolution
`CUSTOMER_NOT_FOUND`	Customer reference not found	Verify customer exists
`INVALID_CARD_NUMBER`	Invalid credit card number	Check card number format
`EXPIRED_CARD`	Card has expired	Update expiration date
`INVALID_ROUTING_NUMBER`	Invalid ACH routing number	Verify routing number
`DUPLICATE_PAYMENT_METHOD`	Payment method already exists	Check for duplicates
`INVALID_TOKEN`	Invalid token format	Verify token format