Cardholder Activation

Cardholders are created in an activating state behind an activation block. See Get Cardholder Blocks for more information on blocks.

The activation block prevents the cardholder from issuing cards and transacting. The block is lifted once Immersve has confirmed that all onboarding prerequisites and checks are satisfied.

Activation Prerequisites

Immersve lifts the activation block only after all of the following are satisfied. These are the same checks surfaced by the Get Spending Prerequisites endpoint, described in

KYC Spending Prerequisites

Prerequisite	Description
Expected spend	The cardholder's expected spend amount has been set via the Update Expected Spend Amount endpoint.
KYC passed	The cardholder has successfully completed identity verification. See Detecting KYC Completion.
Contact channels	Both a contact email and a contact phone number have been set via the Update Contact Details endpoint.

Additional checks are performed after prerequisites are met. A cardholder who completed identity verification may still be awaiting clearance, during which the activation block remains in place.

Detecting Cardholder Activation

There are two ways to detect that a cardholder's activation block has been lifted. Using webhooks is the recommended approach.

Webhooks (Recommended)

Subscribe to the cardholder-block-released topic to receive a real-time notification when an activation block is lifted.

Configure a Webhook Listener – Set up and register your webhook listener. See
Configuring Webhook Listeners
Subscribe to the Topic – Subscribe your listener to the cardholder-block-released topic.
Handle the Notification – Listen to incoming webhooks and verify the cardholderAccountId and reason to ensure the webhook corresponds to the cardholder activation block. The webhook payload will be as following:
```
{
  "blockId": "75a7e8ef0d234d0a6bf755e07d39eb03",
  "cardholderAccountId": "9b7552cf9abab0f2efed72df6b3ce4bc",
  "reason": "activation"
}
```
See the Cardholder Block Released topic reference for the full payload schema.
Once the webhook notification is received for the given cardholder, treat the cardholder as active.

Polling (Fallback)

For partners without webhook infrastructure, poll Get Spending Prerequisites while the user is actively waiting.

Unacceptable Usage: Polling the spending prerequisites endpoint at high frequencies or for extended periods is not supported and may result in rate limiting. Poll only while the user is actively waiting, and stop after a short timeout. See Detecting KYC Completion for acceptable polling patterns.

Creating a Card

Attempting to create a card before the activation block has been lifted will fail. The Create Card endpoint returns a 403 response with an errorCode identifying the missing prerequisite.

Once the activation block has been lifted, follow Issue a Virtual Card to issue a card.