Create a debit card

Create a card that spends directly from a managed account.

The card is created as a virtual card for the logged-in consumer or corporate identity and is bound to a parent managed account. It has no balance of its own. Spending draws on the parent account's funds, up to a configurable spend limit. Several debit cards can share the same parent account.

Prerequisites

The identity must have completed due diligence before it can create cards; otherwise the request fails with OWNER_IDENTITY_NOT_VERIFIED. The Managed Card Profile referenced by profileId must be active, and the parent managed account must already exist and be active, otherwise the request fails with PARENT_MANAGED_ACCOUNT_NOT_FOUND or PARENT_MANAGED_ACCOUNT_NOT_ACTIVE.

This operation requires a stepped-up access token. Step up before calling it by issuing a challenge through Step-up.

Fields

Profile and mode

profileId selects the Managed Card Profile configured in the Multi Portal, which determines the behavior, limits, and restrictions applied to the card. Set mode to DEBIT_MODE.

Funding

parentManagedAccountId identifies the managed account the card spends from. The card has no separate balance or currency field: payments are billed in the parent account's currency. Use spend rules to cap how much of the parent account's funds this card can use. The response includes availableToSpend for each configured spend-limit interval.

Display currency

userCurrency is optional and presentation-only. Set it to show cardholder amounts in their preferred currency. Card payment data then includes a userAmount alongside billingAmount, which you can display in your app. It has no effect on how a payment is billed or settled. If it isn't set, userAmount matches billingAmount.

Names

nameOnCard is the cardholder name and may be checked by merchants for online purchases. It is printed on the card if the card is later upgraded to physical, as is the optional nameOnCardLine2. Both are capped at 27 characters here, but the limit that actually applies to a printed card depends on the chosen card design and is confirmed by Weavr during physical card setup. friendlyName is a label for your own use and isn't printed or shared with merchants.

Address

billingAddress is the cardholder's billing address and may be verified by merchants for online purchases. It is unrelated to where a physical card is delivered. The delivery address is supplied when the card is upgraded to physical.

Linking a user

Set userId to link the card to an authorized user. The linked user's authentication details are then used for actions performed on the card, such as 3DS authentication and manual provisioning to a digital wallet. Linking is also a prerequisite for bulk physical delivery.

Renewal

renewalType controls what happens as the card approaches expiry. RENEW reissues the card with the same card number and a new expiry date and CVV; NO_RENEW lets it expire and be destroyed.

Digital wallets and external data

digitalWallets controls whether the card can be tokenized and push-provisioned into a digital wallet, and which artwork is used. externalData holds up to 10 name/value pairs of your own. Weavr stores them against the card and can surface them in reports and filters, but never acts on them.

Next steps

The card is usable as a virtual card as soon as it is created. To issue plastic for it, see Request a physical card for individual delivery or for bulk delivery.