Payment Cards
Methods
Section titled “Methods”Retrieve Single Payment Card
Section titled “Retrieve Single Payment Card”/backend/api/v1/paymentCards/ID - fetch payment card with specified ID.
List Payment Cards
Section titled “List Payment Cards”/backend/api/v1/paymentCards/ - list all payment cards.
/backend/api/v1/customers/ID/paymentCards/ - list payment cards belonging to customer with specified ID.
/backend/api/v1/customers/ID/paymentCards/ - add a new payment card to the specified customer, the newly-added card will be returned.
/backend/api/v1/paymentCards/ID - update payment card with specified ID. The modified card will be returned.
DELETE
Section titled “DELETE”/backend/api/v1/paymentCards/ID - delete payment card with specified ID.
Fields
Section titled “Fields”| Field | Name | Type | Description |
|---|---|---|---|
| ourReference | Our Reference | Text | Internal reference number for the payment card |
| customerReference | Customer's Reference | Text | Customer-provided reference for the payment card |
| paymentCardPriority | Card Collection Order | Preset Value | Priority order for payment collection when customer has multiple payment cards |
| emailAddress | Email Address | Preset Value | Email address associated with this payment card |
| cardholderName | Cardholder Name | Text | Name of the cardholder for the payment card |
| paymentCardType | Card Type | Preset Value | Type of payment card (e.g., Visa, Mastercard) |
| PANLastDigits | Last Four Digits | Text | Last four digits of the payment card number for identification |
| fromDate | From Date | Text | Start date for the payment card validity period |
| expiryDate | Expiry Date | Text | Expiry date of the payment card |
| paymentCardStorageType | Card Storage Method | Preset Value | Method used to store and process the payment card information |
| useForPaymentTypes | Use For Payment Types | Preset Value(s) | Array of payment type names this card supports Send "All Payment Types" (or null) for All Payment Types; an empty list means none. |
| paymentCardCollectionTypes | Use For Collection | Preset Value(s) | Array of collection type names this card can be used for |
| providerToken | Provider Token | Text | Token assigned by the payment card provider |
| providerCustomerReference | Provider Customer Reference | Text | Customer reference used by the payment card provider |
| providerReference | Provider Reference | Text | Reference number assigned by the payment card provider |
| providerKey | Provider Key | Text | Provider key for payment card processing |
| providerAccountReference | Provider Account | Text | Stripe account (acct_...) holding this card, recorded when the card was stored |
| status | Card Status | Preset Value | Current status of the payment card |
| paymentCardSetupDate | Set-Up Date | Date | Date when the payment card was set up with the provider |
| paymentCardTakenDate | Last Taken Date | Date | Date when a payment was last successfully taken from this card |
| id | Payment Card ID | Text | The unique identifier for this payment card |
Use For Payment Types
Section titled “Use For Payment Types”useForPaymentTypes controls which payment types the card can collect for. The API distinguishes an unrestricted card from one used for no payment type:
| Meaning | Returned as | Send |
|---|---|---|
| Any payment type (unrestricted) | "All Payment Types" | "All Payment Types" or null |
| No payment type | null | [] or "" |
| Specific payment types | Comma-separated payment type names | An array of names, or a comma-separated string |
{ "useForPaymentTypes": "All Payment Types"}Sending "All Payment Types" together with specific payment types returns HTTP 400 with error code 400201. Leaving useForPaymentTypes out of a PATCH leaves it unchanged.
Provider-Specific Fields
Section titled “Provider-Specific Fields”Stripe
Section titled “Stripe”When creating a payment card with paymentCardStorageType set to Stripe, supply the following provider fields:
| Field | Required | Description |
|---|---|---|
providerCustomerReference | Yes | The Stripe customer ID (beginning cus_) |
providerReference | Recommended | The Stripe payment method ID (beginning pm_). If omitted, the platform will automatically use the customer’s most recent card in Stripe for any collection. |
The other provider fields are updated automatically when the platform syncs with Stripe (via webhooks or scheduled updates). You do not need to supply them:
| Field | Updated by | Description |
|---|---|---|
providerKey | Stripe sync | Card fingerprint, used for identification |
Important: If you are adding cards through your own Stripe integration, make sure the Stripe request is configured to allow future payments on the card (e.g. setup_future_usage or an off-session SetupIntent). Without this, the platform will not be able to collect against it.