General

Cards

Retrieve a list of cards stored in the PCI DSS Level 1 vault

List

List cards used for recurring transactions that have been stored on the platform through a Checkout Page, Checkout Form or Card Vault.

Path

GET /cards?{query parameters}

Query Parameters

Field	Required	Description	Example
expire_in_months	N	Filter for card that will expire in x months	2
card_status	N	Card status ACTIVE, ARCHIVED, DISABLED, EXPIRED	ACTIVE
customer_id	N	ID of a specific customer to filter for, see customers	cus_YxVm9CfEeP-6GnSN0MBCb

Response Body

{
  "status": true,
  "results": [{
    "id": "crd_3yXrdg041rMGY4_VYaWva",
    "created_at": "2024-12-28 22:14:47",
    "updated_at": null,
    "card_status": "ACTIVE",
    "usage_type": "VAULT_AND_SUBSCRIPTION",
    "customer_id": "cus_YxVm9CfEeP-6GnSN0MBCb",
    "card_nickname": "Mike's Card",
    "card_ending": "9834",
    "card_expire": "04/29",
    "card_brand": "VISA",
    "card_token": "60d678e2465b5b6c4fd5e847ef39c70c4b0c22d1b826f39eb80a107b3b8433ad",
    "is_expired": false,
    "is_default": true,
    "priority": 1,
    "expire_in_months": 5,
    "last_transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY"
  }, ...]
}

Response Parameters

Field	Type	Description	Example
status	Boolean	true - response success, false - response error	true
results	Array	Array of card objects	...
results.id	String(32)	Unique ID of this card	crd_3yXrdg041rMGY4_VYaWva
results.created_at	Timestamp(YYYY-MM-DD HH:mm:ss)	When this card was stored	2024-12-28 22:14:47
results.updated_at	Timestamp(YYYY-MM-DD HH:mm:ss)	When this card entry was last changed	null
results.card_status	ENUM	Card status ACTIVE, ARCHIVED, DISABLED, EXPIRED	ACTIVE
results.usage_type	ENUM	How the card may be used `VAULT_AND_SUBSCRIPTION`, `SUBSCRIPTION_ONLY`	VAULT_AND_SUBSCRIPTION
results.customer_id	String(32)	ID of the customer who owns this card see customers	cus_YxVm9CfEeP-6GnSN0MBCb
results.card_nickname	String(64)	A nickname given to the card	Mike's Card
results.card_ending	String(4)	Last 4 digits of the card number	9834
results.card_expire	String(5)	Card expiry date in MM/YY format	04/29
results.card_brand	ENUM	Card brand (`VISA`, `MASTERCARD`, `AMERICAN_EXPRESS`, `DISCOVER`)	`VISA`
results.card_token	String	Card token used for collections	60d678e2465b5b6c4fd5e847ef39c70c4b0c22d1b826f39eb80a107b3b8433ad
results.is_expired	Boolean	Indicates if the card has expired	false
results.is_default	Boolean	Indicates if the card is the default card set for collections	true
results.priority	Integer	Cascade fallback order among non-default cards (lower runs first)	1
results.expire_in_months	Integer	Number of months until the card expires	5
results.last_transaction_id	String(32)	Hashed ID of the most recent transaction for this card, or `null` when none exist	tra_pr6CvR_4pvWwmgQ4y3dtY

Update

API call to update existing card(s) as single or batch records.

Terminal statuses: Once a card is set to DISABLED or ARCHIVED it cannot be re-activated (ACTIVE). Setting either status also retires the card at the card processor (ACI registration is deregistered asynchronously). Soft declines / back-off do not apply here — these statuses are permanent.

Path

POST /cards/update

Request Body

Only include fields you wish to change (besides id used to find the record). Setting a column to null will clear that field's value if allowed

{
  "records": [{
    "id": "crd_3yXrdg041rMGY4_VYaWva",
    "card_status": "DISABLED",
    "card_nickname": "Mike's Updated Card",
    "is_default": true
  }, {
    "id": "crd_SFq2E9LskQimPkf2mRqnV",
    "card_nickname": "Sarah's Card",
    "is_default": false
  }]
}

Request Parameters

Field	Required	Type	Description	Example
id	Y	String(32)	ID of the card to update	crd_3yXrdg041rMGY4_VYaWva
card_status	N	ENUM	Card status ACTIVE, ARCHIVED, DISABLED, EXPIRED. `DISABLED` / `ARCHIVED` are terminal — the card cannot later be set back to `ACTIVE`, and its processor registration is deregistered	DISABLED
card_nickname	N	String(64)	A nickname for the card	Mike's Updated Card
is_default	N	Boolean	Set as the default card for collections	true

Response Body

{
  "status": true,
  "results": [{
    "id": "crd_3yXrdg041rMGY4_VYaWva",
    "created_at": "2024-12-28 22:14:47",
    "updated_at": "2024-12-28 22:20:15",
    "card_status": "DISABLED",
    "usage_type": "VAULT_AND_SUBSCRIPTION",
    "customer_id": "cus_YxVm9CfEeP-6GnSN0MBCb",
    "card_nickname": "Mike's Updated Card",
    "card_ending": "9834",
    "card_expire": "04/29",
    "card_brand": "VISA",
    "card_token": "60d678e2465b5b6c4fd5e847ef39c70c4b0c22d1b826f39eb80a107b3b8433ad",
    "is_expired": false,
    "is_default": true,
    "priority": 1,
    "expire_in_months": 5,
    "last_transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY"
  }, {
    "id": "crd_SFq2E9LskQimPkf2mRqnV",
    "created_at": "2024-12-28 21:30:12",
    "updated_at": "2024-12-28 22:20:15",
    "card_status": "ACTIVE",
    "usage_type": "SUBSCRIPTION_ONLY",
    "customer_id": "cus_tDaOH6RaG0YlGah9VKxu7",
    "card_nickname": "Sarah's Card",
    "card_ending": "1234",
    "card_expire": "08/27",
    "card_brand": "VISA",
    "card_token": "70e789f3576c6c7d5ge6f958fg50d81e5c1d33e2c937g50fc91b218c4c9544be",
    "is_expired": false,
    "is_default": false,
    "priority": 2,
    "expire_in_months": 35,
    "last_transaction_id": null
  }]
}

Response Parameters

Field	Required	Type	Description	Example
id	Y	String(32)	Record id to update	crd_3yXrdg041rMGY4_VYaWva
card_status	N	ENUM	Card status ACTIVE, ARCHIVED, DISABLED, EXPIRED	DISABLED
usage_type	n/a	ENUM	How the card may be used `VAULT_AND_SUBSCRIPTION`, `SUBSCRIPTION_ONLY`	VAULT_AND_SUBSCRIPTION
card_nickname	N	String(64)	A nickname for the card	Mike's Updated Card
is_default	N	Boolean	Set as the default card for collections	true
priority	n/a	Integer	Cascade fallback order among non-default cards (lower runs first)	1
last_transaction_id	n/a	String(32)	Hashed ID of the most recent transaction for this card, or `null` when none exist	tra_pr6CvR_4pvWwmgQ4y3dtY
customer_id	n/a	String(32)	ID of the customer who owns this card see customers	cus_YxVm9CfEeP-6GnSN0MBCb
card_ending	n/a	String(4)	Last 4 digits of the card number	9834
card_expire	n/a	String(5)	Card expiry date in MM/YY format	04/29
card_brand	n/a	ENUM	Card brand (`VISA`, `MASTERCARD`, `AMERICAN_EXPRESS`, `DISCOVER`)	`VISA`
card_token	n/a	String	Card token used for collections	8EooXHkTd7hf7xD2nM1nS72cifJeijXk
is_expired	n/a	Boolean	Indicates if the card has expired	false
expire_in_months	n/a	Integer	Number of months until the card expires	5
created_at	n/a	Timestamp(YYYY-MM-DD HH:mm:ss)	Date and time card was stored	2024-12-28 22:14:47
updated_at	n/a	Timestamp(YYYY-MM-DD HH:mm:ss)	Date and time record was last updated	2024-12-28 22:20:15

Bank Accounts

Manage customer bank account details including account numbers, branch codes, account types, and bank verification. Required for EFT Debit Orders, DebiCheck, and Registered Mandate processing.

Mandates

Create and manage mandates for collections including DebiCheck and Registered Mandates. Handle mandate creation, authentication, status updates, and cancellation with full SARB compliance.