Skip to main content

User currencies

It is possible for users (including card assigneesCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.) to view the balance of a debit-mode card or set spend limits in a secondary currency, different from the card's assigned currency, known as the userCurrency.

What is userCurrency?​

Consider a UK-based company with employees in Sweden. If the company enables SEK as a userCurrency, it can assign this currency when creating cards for Swedish employees. Card assigneesCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. can view their card balance and spend limits in their designated userCurrency, providing greater flexibility and transparency in managing expenses.

note

Specifying a userCurrency does not change the underlying card’s issuing currency with our banking partners. The card's statements are still reported in the original card currency. Additionally, once a card is created, its userCurrency cannot be changed.

info

This feature is not available on prepaid-mode cards.

Enabling the userCurrency feature​

This feature is optional. To enable it, contact your account manager or support team with the following details:

  • The name of the application/s you wish to enable the feature for
  • The card profileProfile A template defining the configuration for one type of object — corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type./s (if not all) you wish to enable it on

You can choose to enable all supported currencies or a subset for each card profileProfile A template defining the configuration for one type of object — corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type.. Supported userCurrency values:

JPY, BGN, CZK, DKK, HUF, PLN, RON, SEK, CHF, ISK, NOK, TRY, AUD, BRL, CAD, CNY, HKD, IDR, ILS, INR, KRW, MXN, MYR, NZD, PHP, SGD, THB, ZAR

We support USD, EUR, and GBP as currencies for cards. If you choose USD as the base currency, for example, you can also set EUR and/or GBP as user currencies.

Creating a card with a userCurrency​

To create a new debit-mode card with a userCurrency, use:

POST/managed_cardsTry it 
{
  "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": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "renewalType": "RENEW",
  "userId": "string"
}

Include the optional userCurrency parameter in the request body, selecting a value from the supported list.

If omitted, spend limits default to the card's currency, which also matches the parentManagedAccountId currency, the card's base currency.

The userCurrency setting does not alter the issuing currency or how statements are reported.

note

Once a card is created, the userCurrency cannot be changed.

Retrieving available-to-spend amount​

To retrieve the available-to-spend amount, use:

GET/managed_cards/{id}Try it 
{
  "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": {
      "replacementReason": "DAMAGED",
      "replacementId": "string"
    },
    "deliveryAddress": {
      "name": "string",
      "surname": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st",
      "contactNumber": "string"
    },
    "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": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "userId": "string",
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  }
}

or

GET/managed_cardsTry it 
{
  "cards": [
    {
      "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": {
          "replacementReason": "DAMAGED",
          "replacementId": "string"
        },
        "deliveryAddress": {
          "name": "string",
          "surname": "string",
          "addressLine1": "string",
          "addressLine2": "string",
          "city": "string",
          "postCode": "string",
          "state": "string",
          "country": "st",
          "contactNumber": "string"
        },
        "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": "string",
      "externalData": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "userId": "string",
      "replacement": {
        "id": "string",
        "reason": "DAMAGED"
      }
    }
  ],
  "count": 0,
  "responseCount": 0
}

If a userCurrency is assigned, the returned amount is shown in that currency. Otherwise, the amount is shown in the card's base currency.

Setting spend limits​

To define a spend limit, use:

POST/managed_cards/{id}/spend_rulesTry it 
{
  "allowedMerchantCategories": [
    "string"
  ],
  "blockedMerchantCategories": [
    "string"
  ],
  "allowedMerchantIds": [
    "string"
  ],
  "blockedMerchantIds": [
    "string"
  ],
  "allowedMerchantCountries": [
    "st"
  ],
  "blockedMerchantCountries": [
    "st"
  ],
  "allowContactless": true,
  "allowAtm": true,
  "allowECommerce": true,
  "allowCashback": true,
  "allowCreditAuthorisations": true,
  "rolloverPolicy": {
    "rolloverNegative": true
  },
  "spendLimit": [
    {
      "startTimestamp": 0,
      "value": {
        "currency": "str",
        "amount": 0
      },
      "interval": "DAILY"
    }
  ],
  "minTransactionAmount": 0,
  "maxTransactionAmount": 0
}

Provide both the currency and amount in the spendLimit object.

If a userCurrency is assigned, spendLimit.value.currency must match it. Otherwise, it must match the parentManagedAccountId currency.

note

minTransactionAmount and maxTransactionAmount are always in the parentManagedAccountId currency, regardless of whether a userCurrency is assigned.

The same logic applies when updating spend rules via:

PATCH/managed_cards/{id}/spend_rulesTry it 
{
  "allowedMerchantCategories": [
    "string"
  ],
  "blockedMerchantCategories": [
    "string"
  ],
  "allowedMerchantIds": [
    "string"
  ],
  "blockedMerchantIds": [
    "string"
  ],
  "allowedMerchantCountries": [
    "st"
  ],
  "blockedMerchantCountries": [
    "st"
  ],
  "allowContactless": true,
  "allowAtm": true,
  "allowECommerce": true,
  "allowCashback": true,
  "allowCreditAuthorisations": true,
  "rolloverPolicy": {
    "rolloverNegative": true
  },
  "spendLimit": [
    {
      "startTimestamp": 0,
      "value": {
        "currency": "str",
        "amount": 0
      },
      "interval": "DAILY"
    }
  ],
  "minTransactionAmount": 0,
  "maxTransactionAmount": 0,
  "updateSpendLimitMethod": "OVERWRITE"
}

Retrieving the card statement​

To retrieve a card statement, use:

GET/managed_cards/{id}/statementTry it 
{
  "entry": [
    {
      "transactionId": {
        "type": "AUTHORISATION",
        "id": "string"
      },
      "entryState": "PENDING",
      "originalAmount": {
        "currency": "str",
        "amount": 0
      },
      "forexRate": {
        "value": 0,
        "scale": -128
      },
      "transactionAmount": {
        "currency": "str",
        "amount": 0
      },
      "availableBalanceAdjustment": {
        "currency": "str",
        "amount": 0
      },
      "actualBalanceAdjustment": {
        "currency": "str",
        "amount": 0
      },
      "balanceAfter": {
        "currency": "str",
        "amount": 0
      },
      "availableBalanceAfter": {
        "currency": "str",
        "amount": 0
      },
      "actualBalanceAfter": {
        "currency": "str",
        "amount": 0
      },
      "transactionFee": {
        "currency": "str",
        "amount": 0
      },
      "cardholderFee": {
        "currency": "str",
        "amount": 0
      },
      "processedTimestamp": 0,
      "sourceAmount": {
        "currency": "str",
        "amount": 0
      },
      "userCurrencyTransactionDetails": {
        "userTransactionAmount": {
          "currency": "str",
          "amount": 0
        },
        "userExchangeRate": "string"
      },
      "additionalFields": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],
  "count": 0,
  "responseCount": 0,
  "startBalance": {
    "currency": "str",
    "amount": 0
  },
  "endBalance": {
    "currency": "str",
    "amount": 0
  },
  "footer": "string"
}

If the card has a userCurrency assigned, the response includes a userTransactionAmount field with:

  • userTransactionAmount.currency: the assigned userCurrency
  • userTransactionAmount.amount: the transaction amount in userCurrency
  • userTransactionAmount.userExchangeRate: the conversion rate used, which is the daily ECB rate.
note

If userCurrency equals the original transaction currency, no conversion is applied.

Webhooks​

Authorization and settlement webhooks for cards with a userCurrency include:

  • userTransactionAmount: transaction amount in the userCurrency
  • currency: the userCurrency
  • amount: transaction amount in the userCurrency