Issue a Scoped Card

Create spend-limited virtual cards for AI agents and purpose-specific use cases, then retrieve their encrypted details in one request.

Security best practices:

• Never store decrypted card details.
• Only request full card details when absolutely necessary.
• Always use the latest encryption libraries to maintain security.

With a scoped card, you create a single-use virtual card limited to the spend you authorize. Set a spending amount when you create it, and Rain caps the card’s lifetime limit at that amount plus a configurable buffer (by default 1.2× the amount, a 20% buffer) to absorb authorization holds. This makes scoped cards a good fit for AI agents and other automated, purpose-specific spending.

Scoped cards are single-use. After the card’s first approved authorization, Rain closes it and its status becomes canceled. Declined authorizations and test authorizations ($0 verifications and validations of $1 or less) leave it open.

Rain closes the card without sending a card.updated webhook. Use the approved transaction.created event as your signal, or check the card’s status with get a card. Rain declines any later authorization as it does for any canceled card.

Unlike standard cards, where you create the card and then retrieve its encrypted details in a separate call, the scoped endpoint lets you do both at once. Pass an encrypted sessionid when creating the card, and the response returns the encrypted PAN and CVC inline.

Prerequisites

• The matching issuance capability for the card’s binType: consumer scoped cards (the default) need consumer card issuance, and "binType": "commercial" needs corporate card issuance. Creating a card without the capability returns a 403.
• A user with a linked cardholder to issue the card to.
• A sessionid: an encrypted session ID that protects the returned card details. See generating a session ID and use the public key for your environment.

Creating a scoped card

1. Generate a session ID

   Create a 32-character hex secret and RSA-OAEP encrypt it with Rain’s public key for your environment. Keep the secret, you’ll need it to decrypt the response. See the full session ID example.

2. Create the card

   Call create a scoped card with the amount in USD cents and the encrypted sessionid header.

   curl --request POST \
     --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
     --header 'Api-Key: <API_KEY>' \
     --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
     --header 'content-type: application/json' \
     --data '{ "amountInUSDCents": 4299 }'
   
3. Decrypt the card details

   The response returns the card metadata plus the encrypted PAN and CVC. Decrypt encryptedPan and encryptedCvc with your session secret using AES-128-GCM, see decrypting card details.

   {
     "id": "b1a2c3d4-...",
     "encryptedPan": { "iv": "base64_iv", "data": "base64_data" },
     "encryptedCvc": { "iv": "base64_iv", "data": "base64_data" },
     "last4": "4242",
     "expirationMonth": 12,
     "expirationYear": 2028,
     "status": "active"
   }
   

Decryption happens client-side, so Rain creates the card even if your decryption step fails. If that happens, use the returned id to retry retrieval via the get a card’s encrypted data endpoint.

Setting transaction amount

When you create a scoped card, you must set its spending limit by passing amountInUSDCents in the request body.

By default, Rain applies a 20% buffer on top of amountInUSDCents to absorb authorization holds. For example, a request of 4299 cents allows authorizations up to 5159 cents before Rain declines them. This buffer accounts for cases where the final amount exceeds the original request, such as pre-authorization holds or tip adjustments.

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299 }'

Card creation returns a 400 error if amountInUSDCents:

• Is omitted. It is a required field.
• Is not an integer, is less than 1, or is more than 10000000 ($100,000).

Adjusting the buffer

To change the buffer, pass an optional bufferPercentage in the request body: an integer from 0 to 20 inclusive. Rain rounds the lifetime limit up when applying the buffer. Omitting the field, or passing 20, applies the default 20% buffer. Passing 0 sets the lifetime limit to the exact requested amount, with no buffer. Passing null does not restore the default: Rain reads null as 0 and applies no buffer.

You set bufferPercentage when you create the card, and you cannot change it afterward. To apply a different buffer, create a new scoped card.

For example, with the default buffer (or 20), a request of 4299 cents allows authorizations up to 5159 cents. With 0, the limit is exactly 4299 cents.

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299, "bufferPercentage": 0 }'

Set bufferPercentage to 0 only for exact-amount flows. When the final settled or authorized amount can exceed the requested amount (for example, cross-border or foreign transaction fees, tips, or pre-authorization holds), a 0% buffer causes Rain to decline the authorization for exceeding the buffered lifetime limit. Rain returns the decline reason card spending limit exceeded, the same reason returned when any card reaches its configured spending limit. See Decline Reasons. Keep some buffer for those cases.

Card creation returns a 400 error if bufferPercentage:

• Is not an integer.
• Is less than 0 or greater than 20.

Choosing the card type

Pass the optional binType field to choose consumer (the default) or commercial:

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299, "binType": "commercial" }'

Card creation returns a 403 if your tenant is not entitled to issue the requested card type (Tenant is not permitted to issue consumer cards or ... commercial cards). Retrying doesn’t help. Contact Rain’s team during onboarding to add an entitlement.

Card creation returns a 400 if binType is any other value (binType must be one of: consumer, commercial).

Setting an expiration

When you create a scoped card, you can set an optional expiration by passing expiresAt in the request body. Provide an absolute timestamp in ISO-8601 format with a UTC offset. For example, 2026-09-01T00:00:00Z or 2026-09-01T00:00:00+00:00.

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299, "expiresAt": "2026-09-01T00:00:00Z" }'

Card creation returns a 400 error if expiresAt:

• Omits the UTC offset. It must end in Z or an offset such as +00:00.
• Is not a valid timestamp, or is in the past.
• Is more than 365 days in the future.

After a scoped card’s expiresAt passes, Rain declines new authorizations on that card. Rain judges expiration by when the transaction occurred, not when it receives the message, so Rain still evaluates a delayed or replayed transaction against the moment it took place.

Refunds and other credits back to the card are exempt: Rain never declines money owed back to the cardholder for expiration. If you create a scoped card without an expiresAt, Rain assigns a default expiry date per standard card issuance.

Restricting merchant categories

When you create a scoped card, you can limit where it spends by passing an optional allowedMccs allow-list in the request body. Each entry is a four-digit merchant category code (MCC). For example, 5411 for grocery stores or 5812 for restaurants.

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299, "allowedMccs": ["5411", "5812"] }'

Card creation returns a 400 error if allowedMccs:

• Is present but empty. Omit the field entirely to apply no restriction.
• Contains duplicate codes.
• Contains a code that is not a recognized four-digit MCC.

Once a scoped card has a non-empty allowedMccs list, Rain declines new authorizations at any merchant whose category is not on the list. An empty or omitted list applies no category restriction, so the card authorizes at any merchant.

Refunds and other credits back to the card are exempt: Rain never declines money owed back to the cardholder based on merchant category. If a transaction arrives without a readable merchant category code, Rain approves it rather than declining it.

Restricting merchants

When you create a scoped card, you can also limit it to specific merchants by passing an optional allowedMerchants allow-list in the request body. Each entry is a merchant name, such as Uber or Amazon. You can combine allowedMerchants with allowedMccs; Rain enforces each restriction independently.

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards/scoped \
  --header 'Api-Key: <API_KEY>' \
  --header 'sessionid: <ENCRYPTED_SESSION_ID>' \
  --header 'content-type: application/json' \
  --data '{ "amountInUSDCents": 4299, "allowedMerchants": ["Uber", "Uber Eats"] }'

Card creation returns a 400 error if allowedMerchants:

• Is present but empty. Omit the field entirely to apply no restriction.
• Contains more than 25 names.
• Contains a blank entry, a name longer than 64 characters (after trimming), or duplicate names.

Once a scoped card has a non-empty allowedMerchants list, Rain matches each authorization’s merchant name against the list and declines non-matching merchants with the reason merchant scope mismatch. Matching is a best-effort name match against the merchant name on the authorization, so include the name variants you expect to see on statements (for example, both Uber and Uber Eats).

Refunds, other credits back to the card, and $0 account verifications are exempt: Rain never declines them based on the merchant list. If the merchant name on a transaction is too short or garbled to match reliably, Rain approves it rather than declining it.

How Rain matches merchant names

Rain compares your allow-list with the merchant name the network reports (the first 25 characters of the card-acceptor name). Matching is case-insensitive and word by word, so Uber matches UBER TECHNOLOGIES. When you build the list:

• Aggregator prefixes are stripped. For PAYPAL *SELLER or SQ *SELLER, Rain matches the seller. List the seller, not PayPal or Square.
• Generic words don’t count. Rain ignores words such as Inc, LLC, Store, Online, Payments, and App. A single generic word can’t match anything. A name of two or more generic words, such as Trip.com, matches only when they appear together, in order.
• Longer names match approximately. Names of four or more characters also match close spellings, so Apple matches Applebee's. Shorter names must match a word exactly.
• Latin letters and digits only. Rain ignores other characters, including accented letters. If none of a card’s names can match anything, Rain approves its authorizations instead of declining every purchase.

Viewing a scoped card

A scoped card appears in get a card and list cards as a virtual card. Its limit is the buffered lifetime amount with frequency set to allTime. The responses don’t include bufferPercentage, expiresAt, allowedMccs, or allowedMerchants, so store them with the card id. You can’t change these scopes after creation, but you can still edit the card’s limit and status with update a card.

Spending and creation limits

Default limits (configurable during onboarding):

• Up to 10 active scoped cards per user.
• Up to 10 scoped cards created per user in a rolling 24-hour window.
• Up to $5,000 approved spend across a user’s scoped cards in a rolling 24-hour window.

Card creation returns a 400 error if you exceed the active-card or creation-velocity limit. Rain enforces the daily spend limit at authorization time and declines any transaction that would exceed it with the reason scoped_daily_spend_limit_exceeded. Contact Rain’s team to configure custom thresholds for scoped card spending and creation limits.

What’s next

Manage Cards

Apply spend controls, including scoped cards, alongside spending limits and merchant blocks.

Viewing Encrypted Card Details

Retrieve full card details for standard cards.