Cards & Authentication

Card webhooks cover status changes, digital wallet provisioning, and 3D Secure authentication challenges issued during card transactions. The following events are available:

Event	Description
`card.created`	A card is created, whether issued via the API or internally by Rain.
`card.updated`	A card status changes or a card is added to a digital wallet.
`card.notification`	A card provisioning or wallet token decision is made.
`challenge.requested`	A 3D Secure challenge is issued during card authentication.

`card.created`

Sent whenever a card is created, whether you issue it through the API or Rain creates it internally. This webhook is informational only and does not require a response.

Payload

{
    "id": "bda1b5ca-2bca-4c62-8e17-d80ee6f5aa59",
    "resource": "card",
    "action": "created",
    "version": "1.0.0",
    "body": {
        "id": "277a9918-d463-4bf2-a783-116d02cb9a51",
        "userId": "5086685d-3849-4ec8-bb94-6a2afb73663b",
        "type": "virtual",
        "status": "active",
        "limit": {
            "amount": 8000,
            "frequency": "per24HourPeriod"
        },
        "last4": "5600",
        "expirationMonth": "4",
        "expirationYear": "2032",
        "cardCreationSource": "api_initiated"
    }
}

Field	Type	Description
`id`	`string`	Rain card ID
`userId`	`string`	ID of the cardholder user
`type`	`string`	`virtual` or `physical`
`status`	`string`	Card status: `active`, `locked`, `canceled`, or `notActivated`
`limit`	`object` (optional)	Spending limit configuration
`limit.amount`	`number`	Limit amount in cents
`limit.frequency`	`string`	`per24HourPeriod`, `per7DayPeriod`, `per30DayPeriod`, `perYearPeriod`, `allTime`, or `perAuthorization`
`last4`	`string`	Last 4 digits of the card number
`expirationMonth`	`string`	Card expiration month (no leading zero)
`expirationYear`	`string`	Card expiration year
`cardCreationSource`	`string` (optional)	How the card was created: `api_initiated` (through the API) or `rain_initiated` (internally by Rain). Present when known.
`currency`	`string` (optional)	The program’s primary currency, lowercase ISO-4217. Added in v1.1.0.

The body matches card.updated without statusChangeReason and tokenWallets, plus the optional cardCreationSource. For version history, see the card.created webhook reference.

`card.updated`

Sent when a card status changes or when a user adds their card to a digital wallet. This webhook is informational only and does not require a response.

Payload

{
    "id": "bda1b5ca-2bca-4c62-8e17-d80ee6f5aa59",
    "resource": "card",
    "action": "updated",
    "version": "1.1.0",
    "body": {
        "id": "277a9918-d463-4bf2-a783-116d02cb9a51",
        "userId": "5086685d-3849-4ec8-bb94-6a2afb73663b",
        "type": "virtual",
        "status": "canceled",
        "limit": {
            "amount": 8000,
            "frequency": "per24HourPeriod"
        },
        "last4": "5600",
        "expirationMonth": "4",
        "expirationYear": "2032",
        "statusChangeReason": "api_update_cancel_request"
    }
}

Field	Type	Description
`id`	`string`	Rain card ID
`userId`	`string`	ID of the cardholder user
`type`	`string`	`virtual` or `physical`
`status`	`string`	Card status: `active`, `locked`, `canceled`, or `notActivated`
`limit`	`object` (optional)	Spending limit configuration
`limit.amount`	`number`	Limit amount in cents
`limit.frequency`	`string`	`per24HourPeriod`, `per7DayPeriod`, `per30DayPeriod`, `perYearPeriod`, `allTime`, or `perAuthorization`
`last4`	`string`	Last 4 digits of the card number
`expirationMonth`	`string`	Card expiration month (no leading zero)
`expirationYear`	`string`	Card expiration year
`tokenWallets`	`string[]` (optional)	Digital wallets where the card is tokenized: `Apple` or `Google Pay`
`statusChangeReason`	`string` (optional)	The reason for the card status change
`createdAt`	`string`	ISO-8601 timestamp of when the card was created. Added in v1.2.0.
`updatedAt`	`string`	ISO-8601 timestamp of this update. Added in v1.2.0.
`successorCard`	`object` (optional)	The card that replaced this one, with `id`, `last4`, `expirationMonth`, and `expirationYear`. Present only when `statusChangeReason` is `card_replaced`. Added in v1.3.0.
`currency`	`string` (optional)	The program’s primary currency, lowercase ISO-4217. Added in v1.4.0.
`networkCardId`	`string` (optional)	The card’s network token identifier, for programs with network token reporting enabled. Added in v1.5.0 (replacing `primaryAccountIdentifier` from v1.2.0–v1.4.0).

Fields marked with a version are present only when your webhook configuration pins that version or later; see Versioning and the card.updated version history. The statusChangeReason field can take these values:

Value	Description
`api_lock_request`	Card locked via the lock card endpoint
`pin_limit_exceeded`	Card automatically locked due to too many incorrect PIN attempts
`api_unlock_request`	Card unlocked via the unlock card endpoint
`last_4_api_unlock_request`	Card activated via the verify last 4 endpoint
`api_deactivate_endpoint_request`	Card canceled via the deactivate card endpoint
`api_cancel_request`	Card canceled via the update card endpoint (status set to `canceled`)
`api_update_cancel_request`	Card canceled via the update card endpoint
`user_deleted`	Card canceled because the associated user was deleted
`team_member_deleted`	Card canceled because the team member was removed
`card_replaced`	Card canceled because it was replaced with a new card
`api_update_request`	Card status changed via the update card endpoint
`wallet_provisioned`	Card was added to a digital wallet (Apple Pay, Google Pay)
`rain_initiated`	Card status was changed internally by Rain

`card.notification`

The notification webhook is sent when there are important status updates or decisions regarding card provisioning, particularly related to digital wallet token provisioning. This webhook is informational only and does not require a response.

Limited availability:This webhook is currently triggered when:

A card provisioning request is declined or encounters an issue
Token wallet provisioning decisions are made

Payload

{
    "id": "c3d4e5f6-a1b2-4890-9c8d-7e6f5a4b3c2d",
    "resource": "card",
    "action": "notification",
    "version": "1.0.0",
    "body": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "card": {
            "id": "94534236-927b-44f3-9429-27994c7ebc49",
            "userId": "6d73762a-c401-4898-8f00-d85707e310c0"
        },
        "tokenWallet": "Apple",
        "reasonCode": "PROVISIONING_DECLINED",
        "decisionReason": {
            "code": "WALLET_PROVIDER_RISK_THRESHOLD_EXCEEDED",
            "description": "This tokenization request was declined by the wallet provider due to their proprietary risk assessment system."
        }
    }
}

Field	Type	Description
`id`	`string`	Notification ID
`card.id`	`string`	Rain card ID
`card.userId`	`string` (optional)	ID of the cardholder user
`tokenWallet`	`string`	The digital wallet associated with the event: `Apple` or `Google Pay`
`reasonCode`	`string`	The reason for the notification
`decisionReason`	`object` (optional)	Additional details about the decision
`decisionReason.code`	`string`	The decision reason code
`decisionReason.description`	`string` (optional)	Human-readable description of the decision reason

The reasonCode field takes one of these values:

Value	Description
`PROVISIONING_DECLINED`	The digital wallet provisioning request was declined
`TOKEN_SUSPENDED`	An existing wallet token was suspended
`TOKEN_RESUMED`	A suspended wallet token was reactivated
`TOKEN_DELETED`	A wallet token was removed

The TOKEN_* lifecycle notifications are sent only for programs with network token reporting enabled; contact Rain to enable them. decisionReason applies to PROVISIONING_DECLINED events. The decisionReason.code field tells you who made the decision and what the cardholder can do about it. Rain may add new codes without a version bump, so treat the field as an open-ended string and handle unrecognized values gracefully. Decisions made by Rain

Value	Description	Resolution
`TOKENIZATION_LIMIT_EXCEEDED`	The cardholder reached the limit on device token activations, enforced per 24 hours and over a rolling multi-day window	Have the cardholder retry after the window elapses. The `decisionReason.description` states which limit was reached.
`UNSUPPORTED_REGION`	The cardholder’s country of residence is not supported for Apple Pay provisioning	None. Apple Pay is not available in the cardholder’s region.
`CVC_NOT_VALID`	The CVC/CVV entered does not match the card	Have the cardholder re-enter the correct CVC
`EXPIRY_DATE_INVALID`	The expiry date entered does not match the card	Have the cardholder re-enter the correct expiration date
`UNKNOWN`	The wallet provider returned a decision reason Rain has not mapped	Log the event and handle gracefully. Contact Rain support if you see this code frequently.

Decisions forwarded from the wallet provider. Apple and Google decline these based on their own risk assessment. Rain cannot override them.

Value	Description	Resolution
`WALLET_PROVIDER_RISK_THRESHOLD_EXCEEDED`	The wallet provider declined due to its risk assessment	Have the cardholder wait 24–48 hours before retrying
`DEVICE_SCORE_TOO_LOW`	The wallet provider’s device score is below its minimum threshold	Have the cardholder try a different device or update their OS
`EXCESSIVE_PROVISIONING_ATTEMPTS_ACROSS_ACCOUNTS`	The wallet provider detected excessive provisioning attempts across wallet accounts	Have the cardholder wait 24–48 hours before retrying
`EXCESSIVE_CARDS_AND_PROVISIONING_ATTEMPTS`	The wallet provider detected many different cards added in a short period	Have the cardholder wait 24–48 hours before retrying

Declines surface to the cardholder as a generic “Could Not Add Card” error in the wallet regardless of cause, so match this webhook against support reports to identify the actual reason. See Push Provisioning troubleshooting. For version history, see the card.notification webhook reference.

`challenge.requested`

This webhook is sent when a 3D Secure challenge is initiated for a card transaction. It carries the challenge timing and the transaction context, so you can put the challenge in front of the cardholder. The same event covers both opt-in 3DS paths, and deliveryMethod tells you which flow a challenge belongs to:

`deliveryMethod`	Flow	What you do
`SMS`, `EMAIL`, `WHATSAPP`, `OTHER`	3DS Forwarding	Deliver `challenge.oneTimePassword` to the cardholder through that channel.
`PUSH`	Push Notifications (OOB)	Prompt the cardholder to approve or deny in your app, then report the decision to the `/3ds` endpoint. There is no one-time password.

Opt-in capability: By default, Rain handles 3D Secure step-up directly and sends no webhook. You receive challenge.requested only if your program is enabled for 3DS Forwarding or Push Notifications. This is independent of whether your program is Rain-Managed or Partner-Managed. See 3D Secure (3DS) for the full Forwarding and OOB flows.

The diagram below traces a Forwarding challenge, where you deliver a one-time password. For the OOB equivalent, see the Push Notifications (OOB) flow.

Webhook Rain sends youYour handler (ack 2xx)Action / API callMerchant / network

This event is synchronous with a 60-second timeout: deliver the one-time password to the cardholder and return a 2xx response within that window. If you do not respond in time, the authentication fails and the transaction can be declined. The expiryTime and timeToLive fields define how long the password itself stays valid (300 seconds in the example), which is separate from this response deadline.

Payload

{
    "id": "d4f8a2b1-3c5e-4a7f-9b1d-6e8f0a2c4d5e",
    "resource": "challenge",
    "action": "requested",
    "version": "2.0.0",
    "body": {
        "id": "8a35e8a4-9a3f-41bb-b262-7a2249b2179d",
        "challenge": {
            "startTime": "2026-03-06T10:00:00.000Z",
            "expiryTime": "2026-03-06T10:05:00.000Z",
            "timeToLive": 300,
            "oneTimePassword": "123456"
        },
        "transaction": {
            "amount": 5000,
            "currency": "USD",
            "merchantName": "AMAZON",
            "merchantCountry": "US"
        },
        "card": {
            "id": "94534236-927b-44f3-9429-27994c7ebc49"
        },
        "deliveryMethod": "SMS"
    }
}

Field	Type	Description
`id`	`string`	The notification’s own ID. Use it to keep your handler idempotent.
`challenge.startTime`	`string`	ISO 8601 timestamp of when the challenge started
`challenge.expiryTime`	`string`	ISO 8601 timestamp of when the challenge expires
`challenge.timeToLive`	`number`	Time remaining in seconds
`challenge.oneTimePassword`	`string` (optional)	One-time password for the challenge. Absent on OOB challenges, which have no password.
`challenge.id`	`string` (optional)	Challenge ID. Present only on OOB challenges. Echo it back as `challengeId` when you report the decision to `/3ds`.
`transaction.amount`	`number`	Transaction amount in the currency’s minor unit (for example, `5000` is $50.00)
`transaction.currency`	`string`	Currency code (for example, `USD`)
`transaction.merchantName`	`string`	Merchant name
`transaction.merchantCountry`	`string`	Merchant country
`transaction.id`	`string` (optional)	Transaction ID. Present only on OOB challenges. Echo it back as `apataTransactionId` when you report the decision to `/3ds`.
`card.id`	`string`	Rain card ID
`deliveryMethod`	`string`	Challenge delivery method: `SMS`, `EMAIL`, `WHATSAPP`, `PUSH`, or `OTHER`

The envelope version field can be absent for some tenants, so treat it as optional when you parse. For the full schema and version history, see the challenge.requested webhook reference.

Overview

Compliance

Cards

Payments

Webhooks

Webhook Events

Cards & Authentication

`card.created`

`card.updated`

`card.notification`

`challenge.requested`

​card.created

​card.updated

​card.notification

​challenge.requested

`card.created`

`card.updated`

`card.notification`

`challenge.requested`