Basic Card Link

Provides Card Link lookups using the card token and card manipulation such as enrolment via cardframe, list, delete, etc. via Storebox Card API.

Terminal Card Link

Extending Basic Card Link functionality via terminals running Viking and OnePA. This allows in-store card enrolment and card lookups through Baxi commands.

API based card enrolment

Via a dedicated PCI compliant API cards can be enrolled programmatically. Please note that adding cards programmatically carries extensive security requirements and may even require PCI-DSS certification on integrator side.

All data exchange is in JSON and is UTF-8 encoded. To ensure forward compatibility, client implementations must be resilient to new elements being added to the API responses in the future.

The API has the following rate limiting to ensure performant operation:

If higher rates are required, Storebox must be contacted in advance to avoid automatic blacklisting.

The table below describes the two environments that are available.

To start using Card Link you must first get an API key from Storebox.

Card manipulation using Card API

Handling of card life-cycle management like, add, delete and list is done through Card API. After a card has been added it is available for card link lookups thus it is strongly recommended to implement card manipulation, or at least adding, before card lookup.

Interaction with Card API is server to server. For card enrolment, the generated CardFrame URL is supplied to the client.

Cards enrolled via Card API CardFrame are based on user interaction and are immediately active.

Cards enrolled as part of Terminal Card Link (in-store via terminal) must be activated in order to become available for lookups.

Card lookup

Card lookup is typically done by the ECR before a transaction, so that e.g. the amount can be adjusted according to a discount level or likewise. The lookup may, of course, be done at any favorable point in the payment process.

Using Basic Card Link the ECR fetches the card token from the terminal and calls Card Link lookup.

The result will either be a 404 Not Found if the card is unknown, otherwise the user id and a card id is returned.

1. Card Lookup
2. Card Enrolment
3. Card Activation
4. Online card enrolment and management
5. Short path to receipt delivery

• Card lookup is handled via a high availability, high performance card lookup endpoint.

• Card manipulation is handled via Storebox Card API

  • Add card: Insertion of a new card is done via Storebox Card API card frame. An html form that can be styled and internationalized as needed.
  • List cards: List cards associated with a specific userId.
  • Delete card: Delete a specific card identified by a specific externalCardId.

The addition of the 'Terminal Card Link' package enables the use of Viking and OnePA terminals as clients for card lookup and card enrolment.

The methods described herein are not available via Storebox Card Link API, but solely via Baxi. The inclusion in this documentation serves to provide basic examples of the responses that may be expected in the "payload" object of the response when using Baxi functions to facilitate Storebox Card Link operations.

Baxi uses its own error codes, error messages and has its own possible failures in Baxi context.

Check if a card is known and which userId is registered on a known card using the terminal operation getAsset.

Lookup happens towards Storebox Card Link API from the terminal instead of via integration to Storebox CardLink API.

Baxi structure is defined by Nets. Currently the response from Storebox is contained as payload under da.dam2ra.getasset.asset.attributes. Card Link API responses are contained within the cardlinkapi object under the root object payload from Storebox' systems.

Besides structural differences, the response via getAsset is the same as Card Lookup in Basic Card Link.

Example of succesful card lookup response via Baxi

{
    "payload": {
        "cardlinkapi": {
            "users": [
                {
                    "userId": "511618771",
                    "externalCardId": "ha0u3xb395c4lps1hbfajrdbotq3f4h7"
                },
                {
                    "userId": "797745330",
                    "externalCardId": "x83is6m0uf3c55icykcihhraizfsnaj3"
                }
            ]
        }
    }
}

Available via the Baxi insertAsset operation and delivers the card to Storebox in a 'pending verification' state. Card awaits activation call.

Example of succesful card enrolment response via Baxi

{  
    "payload": {
        "id": "800unxobgxyrguqqv11ankz0vsuy2p5w",
        "posapi": {
            "userId": [
                {
                    "type": "pan",
                    "value": "f37388e0-0a1f-11eb-b596-5c4242535400"
                }
            ]
        },
        "cardlinkapi": {
            "activationCode": "969fc04a-d102-4c2e-b04f-808d0b9ea5d6"
        }
    }
}

Status codes and messages are Baxi specific. Documentation must be provided by Nets. For complete documentation of getAsset and insertAsset in a Baxi context, please refer to NETS documentation.

For a quick'n'dirty flow introduction you may consult our getting started guide to Viking, but please note that it is NOT usable as direct copy/paste reference as Baxi action codes etc. may have changed and thus Nets Baxi documentation must be consulted.