Card Tokens

API Documentation

When a card is added to a digital wallet (Apple Pay, Google Pay, Samsung Pay) or stored as a card-on-file with a merchant, a card token is created that represents the card's presence in that wallet or merchant system. Card tokens are network-level tokens provisioned through the card networks' tokenization services.

Tokens are created by the network provisioning flow, not through the API — there is no create endpoint. Column provides full visibility into the token lifecycle, allows your platform to control provisioning decisions through real-time webhooks, and lets you pause, reactivate, or deactivate tokens through the API.

Digital Wallet Enablement

Before cardholders can add a card to Apple Pay, Google Pay or Samsung Pay, Column works with you to enable your card program for wallets with the card network and with each wallet provider. Once it is enabled, a cardholder can add the card by entering its details in the wallet app, known as manual provisioning. This does not need any app integration.

You provide Column the card art for each card template, your cardholder terms and conditions, and the customer support contact details to show on the card in the wallet. The card network and each wallet provider review the card art before it goes live.

Your platform then handles each wallet provisioning request through real-time decisioning:

• Approve, decline or step up each request with provisioning decisioning.
• Deliver one-time passcodes when a request needs cardholder verification.

The card network and the wallet provider also assess each request. Either can decline it or require cardholder verification, even when your platform approves.

To let cardholders add a card by tapping "Add to Wallet" in your mobile app, set up in-app provisioning after wallet enablement.

Token Types

Wallet Types

Provisioning Decisioning

Column can send a real-time webhook to your platform when a card token provisioning request is received, allowing you to approve, decline, or require additional cardholder verification before a token is activated.

When a provisioning request passes Column's own checks (for example, the card exists and is active), Column sends a webhook to the endpoint registered for the decision.issuing.card_token event type and waits up to 3 seconds for a response. The request body contains the card token under the card_token field, and carries the same Column-Signature header used by other webhooks to validate that the request originated from Column.

Your platform responds with one of the following decision values:

If no endpoint is registered for the event type, or no response or an invalid response is received within the deadline, Column declines the provisioning request.

The outcome of a provisioning decision is recorded on the card token in the provisioning_decisioning_details field, including the decision, who made it (column or platform_owner), and a rejection reason when declined. The field can be empty for requests that Column declines before a provisioning decision is made.

See Real-time Decisioning for more details on the overall decisioning flow, including webhook endpoint setup.

Cardholder Verification

When a token provisioning request requires additional cardholder verification (through a step_up decision response or network requirements), Column supports a passcode-based verification flow. The token moves to the stepping_up status while the cardholder's verification method is selected.

Your platform is responsible for delivering the one-time passcode to the cardholder. When the card network sends Column the passcode, the token moves to pending_authentication (firing issuing.card_token.pending_authentication), and Column sends an issuing.card_token.send_passcode webhook containing the card token fields along with the fields below (see the send passcode webhook payload). The card token in this payload usually has the status pending_authentication, but not always, for example when the network resends a passcode request. Deliver the passcode whenever you receive this webhook, whatever the token's status.

The token remains in pending_authentication until the network reports the result of the verification, and moves to active once the cardholder is verified.

Device Binding

Device binding associates an existing token with a new device. It follows the same verification flow as initial provisioning: real-time decisions use the decision.issuing.card_token.device_binding event type, and passcode delivery uses the issuing.card_token.device_binding.* events listed below.

Managing Tokens

Active tokens can be temporarily paused, and paused tokens reactivated, using the pause and activate endpoints. While a token is paused, authorizations with the token are declined.

A token that is not already deactivated can be deactivated using the deactivate endpoint. Deactivated tokens cannot be reactivated through the API. If the network later sends a new provisioning request for a previously deactivated token, Column resets it to pending_activation and the normal provisioning flow runs again.

Tokens also follow the lifecycle of their card:

• Deactivating a card with deactivate_card_tokens set to true deactivates its tokens. Without it, deactivating a card that has tokens which are not deactivated fails with a 400 error.
• Closing a card account with deactivate_cards_and_card_tokens set to true deactivates its cards and their tokens.
• Renewing a card keeps its tokens alive (the card number is unchanged) and re-links them to the new card, firing an issuing.card_token.card_changed event.
• Replacing a card deactivates its tokens.

Statuses

Events

Card token event payloads contain the card token object.

Token Lifecycle Events

Token Authentication Events

Device Binding Events