Methods
GET
Retrieve Single Payment Card
/backend/api/v1/paymentCards/ID - fetch payment card with specified ID.
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.
POST
/backend/api/v1/customers/ID/paymentCards/ - add a new payment card to the specified customer, the newly-added card will be returned.
PATCH
/backend/api/v1/paymentCards/ID - update payment card with specified ID. The modified card will be returned.
DELETE
/backend/api/v1/paymentCards/ID - delete payment card with specified ID.
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 |
| 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 |
| 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 |
Provider-Specific Fields
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.