PATCH
/
v4
/
MC_VIRTUAL
/
{id}
curl --request PATCH \
  --url https://integration-api-cat2./%7B{environment}%7D.ext.%7B{realm}%7D.cia.enfuce.com/card/v4/MC_VIRTUAL/{id} \
  --header 'Content-Type: application/json' \
  --data '{
  "accountId": "1234567890",
  "customerId": "1234567890",
  "embossing": {
    "additionalField1": "<string>",
    "additionalField2": "<string>",
    "additionalField3": "<string>",
    "additionalField4": "<string>",
    "additionalField5": "<string>",
    "companyName": "Enfuce Financial Services",
    "externalLayoutCode": "BlueCard",
    "firstName": "Monica",
    "lastName": "Liikamaa",
    "manufacturer": "FACTORY_X",
    "physical": true
  },
  "reason": "<string>",
  "segment": "SEGMENT_A",
  "status": "CARD_OK",
  "usageLimits": [
    {
      "code": "24H",
      "values": [
        {
          "code": "ATM",
          "reset": true,
          "singleAmount": 1000,
          "count": 5,
          "sumAmount": 1200
        }
      ]
    }
  ],
  "pinStatus": "D",
  "digitalLayoutCode": "abc123abc",
  "scheduledClosing": {
    "time": "2099-12-31T03:00:00.000Z"
  },
  "additionalValues": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "regionAndEcommBlocking": {
    "ecomm": true,
    "africa": true,
    "asia": true,
    "europe": true,
    "home": true,
    "northAmerica": true,
    "oceania": true,
    "southAmerica": true
  }
}'
{
  "description": "<string>",
  "id": "<string>"
}

Path Parameters

​
id
string
required

The card id for given card

Query Parameters

​
auditUser
string
required

The audit user to log the request

Body

application/json
The new value of selected property. You should only provide a value for the property you want to update, the other ones should be null
​
accountId
string

The account id card is linked to

Example:

"1234567890"

​
customerId
string

The customer id card is linked to

Example:

"1234567890"

​
embossing
object

Default set of allowed characters for fields embossed onto the card:

A-Z, a-z, Áá, Ää, Åå, Ææ, Éé, Íí, Ðð, Óó, Öö, Øø, Úú, Üü, Ýý, Þþ, 0-9, symbols -/.,&+' and space.

For printed cards allowed characters are: (including the above)

ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüý þÿĀāĂ㥹ĆćĈĉĊċČčĎďĐđĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪīĬĭĮįİıIJijĴĵĶķĸĹ ĺĻļĽľĿŀŁłŃńŅņŇňʼnŊŋŌōŎŏŐőŒœŔŕŖŗŘřŚśŜŝŞşŠšŢţŤťŦŧŨũŪūŬŭŮůŰűŲųŴŵ ŶŷŸŹźŻżŽžſǪǫȘșȚțȪȫȮȯȲȳḐḑṢṣẞỌọ

Printed or others characters sets must be agreed in advance.

​
reason
string

Reason for contract status change

Maximum length: 32
​
segment
enum<string>

Field enables to group an entity into a segment. This field will be exported but no logic is applied to this in Enfuce API

Available options:
SEGMENT_A,
SEGMENT_B,
SEGMENT_C,
SEGMENT_D,
SEGMENT_E,
SEGMENT_F
​
status
enum<string>
Available options:
CARD_OK,
CARD_BLOCKED,
SUSPECTED_FRAUD,
CARD_CLOSED_DUE_TO_FRAUD,
CARD_NO_RENEWAL,
CARD_LOST,
CARD_STOLEN,
CARD_CLOSED
​
usageLimits
object[]

Usage limits

Use cases:

  1. No spend or usage limits

If spend and usage should not be limited, then the default configuration is applied. By default, both the singleAmount and sumAmount are set to 0, indicating that no spend limit is set. The count is set to 9999999 indicating that a high (almost unlimited) number of transactions are allowed without any usage limit set.

  usageLimits.values.singleAmount = 0
  usageLimits.values.sumAmount = 0

  usageLimits.values.count = 9999999

2. Spend limit per transaction

If the maximum spend should be limited for the defined transaction type, set the singleAmount to the desired maximum. If only the singleAmount is set, then both the singleAmount and the count will default to 0 indicating that there is no cumulative spend limit and the number of allowed transactions are not limited.

Example: Maximum allowed spend per transaction is 1000

  usageLimits.values.singleAmount = 1000
  usageLimits.values.sumAmount = 0

  usageLimits.values.count = 0

3. Cumulative spend limit

If the amount spent under a time period should be limited, set the sumAmount to the desired maximum. If only the sumAmount is set, then both the singleAmount and the count will default to 0 indicating that there is no limit on the number of allowed transactions or on single amounts.

Example: Maximum allowed spend under a certain period of time is 1200

  usageLimits.values.singleAmount = 0
  usageLimits.values.sumAmount = 1200

  usageLimits.values.count = 0

4. Usage limit

If the number of allowed transaction under a time period should be limited, set the count to the desired maximum. If only the count is set, then both the singleAmount and the sumAmount will default to 0 indicating that there is no limit on the allowed amounts.

Example: Maximum number of allowed transactions under a certain period of time is 5

  usageLimits.values.singleAmount = 0
  usageLimits.values.sumAmount = 0

  usageLimits.values.count = 5

5. Combinations of usage and spend limits

If multiple limits should apply, set each applicable limit to the desired value. Any unset limiter will default back to 0.

Example: Limit the allowed number of transactions to 5 and the allowed amount to 1000 under a certain period of time

  usageLimits.values.singleAmount = 0
  usageLimits.values.sumAmount = 1000

  usageLimits.values.count = 5

6. Restrict Usage

To disable a specific use case for the card—such as ATM transactions—set all corresponding values for that usage type to 0.

Example: Disable ATM usage by setting all limits to 0

  usageLimits.values.singleAmount = 0
  usageLimits.values.sumAmount = 0

  usageLimits.values.count = 0
​
pinStatus
enum<string>

This flag will indicate current status for PIN generation. If not specified system will automatically assign D as default and make sure a PIN is calculated during next embossing process. If set to W, then card will be excluded from embossing process until a PIN has been set and status has been updated to S. It is also possible to revert to D, in order for system to generate PIN. Note that system will update to status S automatically when a PIN is set successfully.

New card

In order for a new card to not get a system generated PIN then pinStatus flag must be set to W when created, this will then halt the embossing process for given card until a PIN has been set.

Reissue card

When reissuing a card it is possible to set pinStatus to W in order to hold embossing process for given card until a PIN has been set. Update pinStatus is done on same card id that is reissued.

Replace card

When replacing a card it is possible to set pinStatus to W in order to hold embossing process for given card until a PIN has been set. Update pinStatus is done on new card id that is returned when replacing.

  • D - default and a random PIN will be generated
  • W - waiting for PIN to be manually set
  • S - PIN has been set successfully
Available options:
D,
W,
S
​
digitalLayoutCode
string

Id used for digital wallet artwork and other related assets. Use of this need to be agreed with Enfuce separately

Maximum length: 32
Example:

"abc123abc"

​
scheduledClosing
object

Scheduled closing of the card. Use of this object should be aligned with Enfuce prior to use.

​
additionalValues
object[]

The additionalValues array is used to store information in the form of key-value pairs. Enfuce does not perform any validation on these key-value pairs beyond ensuring they adhere to the character limit constraints. The primary purpose of these key-value pairs is to store data without further processing. In newer versions of the card personalization files, these key-value pairs are included in the file. However, this inclusion is version-dependent. We recommend consulting the specific version details of your card personalization files to confirm whether these values will be added to the card personalization file in your case.

​
regionAndEcommBlocking
object

Card ecomm and geo-region blocking

Response

200
application/json
Successful update of the card
​
description
string

Short description of the result of the action

​
id
string

Will contain the ID of the resource that has been created or updated