We are adding a new endpoint that allows replacing cards.

Replace cards

We are introducing a new endpoint POST /cards/{cardId}/replace that enables you to replace existing cards with new ones.

• When replacing cards all existing configurations will be set up automatically based on the values of the existing card (e.g. limit, transactionLimit ...)
• The big advantage of replacing cards (in comparison to terminate and re-issue a new card) is that most subscriptions (that have been set up using the payment data of the replaced card) will continue to work without updating the payment data. To put it differently: Most merchants (especially big ones) will still be able to deduct money using outdated payment details (PAN, CVV and expiry date). This effectively reduced the danger of failed payments until the payment details have been updated by the cardholder.
• The endpoint only works for cards with types VIRTUAL, PHYSICAL or TRAVEL
• Allowed values for property terminateCardReason are depending on card type
  • For cards with type PHYSICAL all values are valid. If LOST, STOLEN is provided, the replaced card gets automatically terminated; if DAMAGED or OTHER is provided the replaced card gets terminated only once the newly created card is activated.
  • For cards with type VIRTUAL or TRAVEL only the values STOLEN (for compromised card details) or OTHER are allowed. In both cases, the replaced card gets immediately terminated.

Minor improvements

• We have updated our API lifecycle guidelines.
• We added the type property to the response and as a query parameter of the GET /cards endpoint.

We added a couple of improvements to several parts of our API especially on your possibilities to maintain callback subscriptions.

Callback management

We improved the management of subscriptions/callbacks

• Consumers are now able to edit existing subscriptions simply by calling the respective POST endpoints with the updated payload.
• We are introducing a new endpoint to fetch your current callback configuration: GET api/subscriptions. It returns a list of all active subscriptions.
• Once the cardUpdated callback is sent for card updates (e.g. because the event CARD_DETAILS_CHANGED has happened) and no changes are made to the card limits the limitChangeproperty will be omitted from the payload from now on.

Minor improvements

• Previously it was possible to issue a card for a member in INACTIVE state. This is not possible anymore. Instead, the API will respond with HTTP status codes 404 and errorCode NOT_FOUND.
• We added cardholderId to transactionUpdated object that is sent for callbacks that can be subscribed via POST /transactions/subscription.

This week we are introducing travel purchasing cards to our API

New card type: TRAVEL

🚧

Important: This card type is disabled per default and each customer needs to sign additonal contractual agreements for them to be enabled

Travel purchasing cards are virtual cards designed to be used in travel-related business processes.

From a business perspective travel purchasing cards,

• only work for a specified set of merchants
• are exempt from 3DS

From a technical perspective travel purchasing cards are the same as cards with type VIRTUAL.

Changes to the API

We introduced a new ENUM value TRAVEL for property type used in multiple endpoints for card and card requests entities.

List of updated endpoints for cards entity:

• POST /cards/{cardholderId}
• GET /cards/{cardId}
• POST cards/details
• POST /cards/subscription

We are introducing a new way to activate physical cards. Instead of dedicated activation codes that need to be added to the card carrier you can activate cards via API based on the last four digits of the card's PAN.

Using refNum to activate physical cards

Previously it has only been possible to activate physical cards with a dedicated activation code that was provided by the card manufacturer when shipping the cards. This special (one-time) activation code needs to be added to the card carrier (e.g. sticker) and is sometimes overlooked by end users.

To address this issue we are enhancing our POST /cards/{cardId}/activate endpoint with a way to activate cards based on the last four digits of the PAN (which in our API we call refNum )

• Added a request body property called activationMethod with allowed ENUM values activationCode & refNum
• Allowed to provide activationCode values with 4 digits (previously 6 digits)

This applies to cards with the following TYPEs:

PHYSICAL
BLACK

We added some minor improvements in the domains of cardholder and card limit endpoints

Cardholder status

Previously the cardholder status was not exposed. We improved it by:

1. adding the status property to query params & response body of GET /api/cardholders
2. adding the status property to the response body of GET /api/cardholders/{cardholderId}
3. adding a new callback CARDHOLDER_INVITED to POST /cardholders/subscription which is triggered when a member is invited.
4. extending the Callback object cardholderUpdate with status property

Possible ENUMs are:

INVITED
ACTIVE
DEACTIVATED

Card limit changes

We do now provide more granular information about card limit changes. So whenever one of the listed properties of a card is updated we trigger the CARD_LIMIT_CHANGED callback (if setup via POST /cards/subscription).

transactionLimit
monthlyLimit (this one is deprecated)
limit
limitRenewFrequency

We provide a new property called limitChange which includes the previous and the new values so you can easily build e.g. notifications on top of it. Please find an example below:

{
  "eventType": "CARD_LIMIT_CHANGED",
  "cardId": "...",
  "organizationId": "...",
  "cardholderId": "...",
  "type": "VIRTUAL",
  "status": "ACTIVE",
  "label": "Test",
  "limitChange": {
    "beforeChange": {
      "transactionLimit": {
        "value": 4200,
        "currency": "EUR"
      },
      "limit": {
        "value": 4200,
        "currency": "EUR"
      },
      "limitRenewFrequency": "QUARTERLY"
    },
    "afterChange": {
      "transactionLimit": {
        "value": 8400,
        "currency": "EUR"
      },
      "limit": {
        "value": 8400,
        "currency": "EUR"
      },
      "limitRenewFrequency": "QUARTERLY"
    }
  }