Nexus GO Cards reporting

This article describes the different available methods for retrieval of card report data. There are a number of different ways to retrieve card report data besides manually downloading a file from the card management portal.

API

Sending an HTTP GET to /api/card/{cardId} gives you complete card information for the specified card.

Notifications

Instead of polling each individual card, Nexus GO Cards offers the possibility to subscribe to events. Examples of available events are when a self-service invitation has been sent or when a card has been activated. 

Example: Event schema for a card activation event

{
    "eventId": "E2202040936-A41D6B65",
    "created": "2022-02-04T09:36:45.650982100",
    "apiVersion": "2.0.0",
    "topic": "CARD_ACTIVATED",
    "data": {
        "cardId": "CA2202040404-5GG3F4C8",
        "articleId": "KSK-K11686X",
        "cardHolderEmail": "jane.doe@nexusgroup.com",
        "cardElements": {
            "FIRST_NAME": "Jane",
            "LAST_NAME": "Doe",
        },
        "photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
        "reportData": {
            "TRANSLATION_MIFARE_HEX_MSB": "00132564",
            "TRANSLATION_MIFARE_HEX_LSB": "64251300",
        },
        "externalReportData": {
            "PIN_CODE": "145632"
        },
        "produced": "2022-02-04T09:36:45.630982300",
        "delivered": "2022-02-04T09:39:45.620982700",
        "activated": "2022-02-10T12:46:45.610982200"
    }
}

The content of the data field in the notification is dependent on the type of event, for example, all card related events have a data value based on the CardInfoResponse schema, see heading "Schemas" in Nexus GO Cards ordering. Similarly, all self-service invite events have a data value based on the InviteInfoResponse schema, see heading "Schemas" in Nexus GO Cards ordering.

The currently supported events are:

There are two different ways to receive notifications, via Webhooks or Message Bus.

Webhooks

You can receive real-time updates from your card activity in Nexus GO Cards using webhooks. Information is sent as JSON via an HTTP post to a URL of your choice. To secure the integrity of your data, your webhook endpoint must support HTTPS. Furthermore, all notification requests are signed with a shared secret key. It is highly recommended that you validate the signature of all notifications sent to your webhook endpoint.

When you add a new webhook you must always generate a shared secret key. This secret key is used to sign the JSON request body of each HTTP request sent to that particular webhook. The signature is then added to the header in the following format: X-Nexus-Signature: HMAC-SHA256=SignatureData.

The part preceding the equals sign specifies the hash function used for calculating the signature. The latter part contains the JSON request body.

The request body is a UTF-8 encoded string and must be interpreted as such during signature validation. 

You configure webhooks under Administration > Integration > Webhooks in Nexus GO Cards management portal. 

Message bus

In cases where the implementation of a webhook URL within the organization is not an option, Nexus GO Cards offers the possibility to subscribe to an organizationally unique Azure Service Bus Queue. For more information on how to consume messages from Azure service bus queues, refer to the official Microsoft documentation, for example, receive messages from queue.

Configuration of the message bus solution is set up as part of the customer on-boarding.

Invoice reports

Partner account required

You must have a partner account in Nexus GO to manage multiple customer accounts.  For more information, see Nexus GO Cards for partners.

You can access invoice reports under Administration > Reports in Nexus GO Cards management portal. From here, you can generate reports, view and analyze statistics, and onward billing to your customers.

The invoice report includes one .csv file per sub-customer containing details about orders placed over a specified time interval. Each file contains the following headers:

- COSTCENTRE
- INVOICENUMBER
- ARTICLENUMBER
- QUANTITY
- ORDERDATE