Skip to content

Managed Cards

Managed Cards are a type of financial instrument offered by Weavr.

You can create virtual or physical cards that are issued to the consumer or corporate identity.

A card created in prepaid mode has its own balance, whereas a card created in debit mode does not have its own balance but taps into the balance of its parent managed account.

Operations

Create a managed card

Request

Creates a managed card for the consumer or corporate identity. The Managed Card Profile (configured in the Multi Portal) specified determines the behaviour and restrictions that the managed card will have.

Security
auth_token and api-key
Headers
idempotency-refstring

A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

Bodyapplication/jsonrequired
profileIdstring(ProfileId)^[0-9]+$required

The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

tagstring, <= 50 characters(Tag)^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

friendlyNamestring, [ 1 .. 50 ] charactersrequired

The friendly name for the card.

nameOnCardstring, [ 1 .. 27 ] characters^[a-zA-Z0-9ßÀÁÂÃÄÅǍÆÇÈÉÊËÌÍÎÏÒÓÔÕÖØŠÙÚÛÜŸÝĄĆČ...required

The card holder's name for the card.

This may be verified by merchants when the card is used online. For Physical cards, this field will be printed on the card. The maximum characters allowed will depend on the design chosen and will be provided to you by Weavr when setting up your plastic cards.

nameOnCardLine2string, <= 27 characters^[a-zA-Z0-9ßÀÁÂÃÄÅǍÆÇÈÉÊËÌÍÎÏÒÓÔÕÖØŠÙÚÛÜŸÝĄĆČ...

Line 2 of the 'name on card' field. For Physical cards, this field will be printed on the card. The maximum characters allowed will depend on the design chosen and will be provided to you by Weavr when setting up your plastic cards.

billingAddressobject(BillingAddress)required

The billing address set for the card holder. This may be verified by merchants when the card is used online.

digitalWalletsobject(DigitalWallets)

The Card Tokenisation details

authForwardingDefaultTimeoutDecisionstring

Default decision for auth forwarding on timeout

Enum:"APPROVE""DECLINE"
modestringrequired

The card can be created in prepaid mode or debit mode.

  • A prepaid mode card has its own balance and can have funds transferred to or from it.
  • A debit mode card does not have its own balance but will be able to spend funds belonging to its parent managed account, subject to a configurable spend limit.
Enum:"PREPAID_MODE""DEBIT_MODE"
Discriminator
externalDataArray of objects, <= 10 items, unique(ExternalData)

External data fields, as provided and managed by the caller that are to be stored and associated with a Managed Card instance. This information is not processed or used by Weavr but some of the values could be shown in specific reports and used as filters

renewalTypestring(CardRenewalType)

Indicates how the card will be handled once it is close to expiring.

  • RENEW: The card will be automatically renewed, keeping the same card number but with a new expiry date and CVV.
  • NO_RENEW: Once the expiry date is reached, the card is destroyed.
Enum:"RENEW""NO_RENEW"
userIdstring(UserId)^[0-9]+$

The Authorised User to be linked to the card, whose authentication details will be used for actions such as 3DS authentication, or manual provisioning to a digital wallet. This field can be used instead of threeDSecureAuthConfig as it better describes the wider scope of possible uses.

currencystring, = 3 characters(Currency)^[A-Z]*$required

The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

cardholderMobileNumberstring, [ 5 .. 15 ] characters^\+[0-9]+$deprecated

The mobile number including country code of the card holder.

For transactions that require a 3DS challenge, an SMS with a code will be sent on this number, to be entered during an online purchase.

threeDSecureAuthConfigobject(ThreeDSecureAuthConfig)deprecated

3DS details for card creation

curl -i -X POST \
  https://sandbox.weavr.io/multi/managed_cards \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -H 'idempotency-ref: string' \
  -d '{
    "profileId": "string",
    "tag": "string",
    "friendlyName": "string",
    "nameOnCard": "string",
    "nameOnCardLine2": "string",
    "cardholderMobileNumber": "string",
    "billingAddress": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st"
    },
    "digitalWallets": {
      "pushProvisioningEnabled": true,
      "walletsEnabled": true,
      "artworkReference": "string"
    },
    "authForwardingDefaultTimeoutDecision": "APPROVE",
    "threeDSecureAuthConfig": {
      "linkedUserId": "string",
      "primaryChannel": "OTP_SMS",
      "fallbackChannel": "OTP_SMS"
    },
    "mode": "PREPAID_MODE",
    "externalData": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "renewalType": "RENEW",
    "userId": "string",
    "currency": "str"
  }'

Responses

Success

Headers
request-refstringrequired

A request identifier. Providing this reference when contacting our support team will help us investigate your query.

Bodyapplication/json
idstring^[0-9]+$required

The unique identifier of the card.

profileIdstring(ProfileId)^[0-9]+$required

The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

externalHandlestringrequired

A uniquely generated code used to identify a card.

This code is to be used instead of the sensitive card number in order to refer to a card when opening a support ticket.

tagstring, <= 50 characters(Tag)^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

friendlyNamestring, [ 1 .. 50 ] charactersrequired

The friendly name given to the card.

currencystring, = 3 characters(Currency)^[A-Z]*$required

The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

stateobject(ManagedInstrumentState)required
typestringrequired

The type of card:

  • VIRTUAL: Not a printed or embedded card. The card can be used online or added to digital wallets.
  • PHYSICAL: A physical card that can be printed and shipped to your customers or embedded in a Wearable device. It can be used at physical terminals.
Enum:"VIRTUAL""PHYSICAL"
cardBrandstringrequired

The card scheme, or brand of the card.

Enum:"MASTERCARD""VISA"
cardNumberobject(SensitiveCardNumber)

The full card number of the card.

This field is omitted when the card state is NOT_ENABLED.

cvvobject(SensitiveCvv)

The CVV of the card.

This field is omitted when the card state is NOT_ENABLED.

cardNumberFirstSixstring^[0-9]{6}$required

The first six digits of the card number.

cardNumberLastFourstring^[0-9]{4}$required

The last four digits of the card number.

nameOnCardstring, <= 27 characters^[a-zA-Z0-9ßÀÁÂÃÄÅǍÆÇÈÉÊËÌÍÎÏÒÓÔÕÖØŠÙÚÛÜŸÝĄĆČ...required

The card holder’s name for the card. This may be verified by merchants when the card is used online. For Physical cards, this field will be printed on the card. The maximum characters allowed will depend on the design chosen and will be provided to you by Weavr when setting up your plastic cards.

nameOnCardLine2string, <= 27 characters^[a-zA-Z0-9ßÀÁÂÃÄÅǍÆÇÈÉÊËÌÍÎÏÒÓÔÕÖØŠÙÚÛÜŸÝĄĆČ...

Line 2 of the 'name on card' field. For Physical cards, this field will be printed on the card. The maximum characters allowed will depend on the design chosen and will be provided to you by Weavr when setting up your plastic cards.

startMmyystring, = 4 characters^[0-9]*$required

The start date of this card, in MMYY format.

expiryMmyystring, = 4 charactersrequired

The end date of this card, in MMYY format.

cardLevelClassificationstringrequired

The card classification determines whether the card is from Consumer or Corporate BINs.

Enum:"CONSUMER""CORPORATE"
expiryPeriodMonthsinteger, (int32), [ 1 .. 120 ]required

The validity timeframe of the card, in months.

renewalTypestring(CardRenewalType)required

Indicates how the card will be handled once it is close to expiring.

  • RENEW: The card will be automatically renewed, keeping the same card number but with a new expiry date and CVV.
  • NO_RENEW: Once the expiry date is reached, the card is destroyed.
Enum:"RENEW""NO_RENEW"
renewalTimestampinteger, (int64)

The timestamp when the card will be renewed, expressed in Epoch timestamp using millisecond precision.

creationTimestampinteger, (int64)required

The timestamp when the card was created, expressed in Epoch timestamp using millisecond precision.

billingAddressobject(BillingAddress)required

The billing address set for the cardholder. This can be checked by the merchant during online purchases.

physicalCardDetailsobject(PhysicalCardDetails)
digitalWalletsobject(DigitalWallets)required
authForwardingDefaultTimeoutDecisionstring

Default decision for auth forwarding on timeout

Enum:"APPROVE""DECLINE"
modestringrequired

The mode with which this card was created:

  • A prepaid mode card has its own balance and can have funds transferred to or from it.
  • A debit mode card does not have its own balance but will be able to spend funds belonging to its parent managed account, subject to a configurable spend limit.
Enum:"PREPAID_MODE""DEBIT_MODE"
Discriminator
externalDataArray of objects, <= 10 items, unique(ExternalData)

External data fields, as provided and managed by the caller that are to be stored and associated with a Managed Card instance. This information is not processed or used by Weavr but some of the values could be shown in specific reports and used as filters

userIdstring(UserId)^[0-9]+$

The Authorised User to be linked to the card, whose authentication details will be used for actions such as 3DS authentication, or manual provisioning to a digital wallet. This field can be used instead of threeDSecureAuthConfig as it better describes the wider scope of possible uses.

singleSpendboolean

Indicates if the card is configured for single-spend mode. When true, the card will be automatically blocked after the first successful transaction.

replacementobject(ManagedCardReplacement)

Indicates if the card is replaced by another card.

balancesobject(ManagedInstrumentBalance)

Instruments with funds have 2 balances, the availableBalance indicating the funds that are available for transactions such as purchases, and the actualBalance indicating the funds that are actually on the instrument.

cardholderMobileNumberstring, [ 5 .. 15 ] characters^\+[0-9]+$deprecated

The mobile number including country code of the card holder, needed for 3DS challenge.

threeDSecureAuthConfigobject(ThreeDSecureAuthConfig)deprecated
Response
{
  "id": "string",
  "profileId": "string",
  "externalHandle": "string",
  "tag": "string",
  "friendlyName": "string",
  "currency": "str",
  "state": {
    "state": "ACTIVE",
    "blockedReason": "USER",
    "destroyedReason": "SYSTEM"
  },
  "type": "VIRTUAL",
  "cardBrand": "MASTERCARD",
  "cardNumber": {
    "value": "string"
  },
  "cvv": {
    "value": "str"
  },
  "cardNumberFirstSix": "string",
  "cardNumberLastFour": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "startMmyy": "stri",
  "expiryMmyy": "stri",
  "cardLevelClassification": "CONSUMER",
  "expiryPeriodMonths": 1,
  "renewalType": "RENEW",
  "renewalTimestamp": 0,
  "creationTimestamp": 0,
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "physicalCardDetails": {
    "bulkDelivery": true,
    "productReference": "string",
    "carrierType": "string",
    "pendingActivation": true,
    "pinBlocked": true,
    "manufacturingState": "REQUESTED",
    "replacement": { … },
    "deliveryAddress": { … },
    "deliveryMethod": "STANDARD_DELIVERY",
    "deliveryTrackingCode": "string",
    "deliveryTrackingMethod": "string",
    "deliveryTrackingUrl": "string",
    "nameOnCardLine2": "string"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "PREPAID_MODE",
  "externalData": [
    { … }
  ],
  "userId": "string",
  "singleSpend": true,
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  },
  "balances": {
    "availableBalance": 0,
    "actualBalance": 0
  }
}