Integration Guide

Recognise a Secucard Card Number

Cards issued by secucard come with a 16-digit card number starting with "9276...". But you might also use other cards under certain conditions.

Check a Card to be Valid

In many cases it makes sense to validate a card before you add it to a Smart Transaction, or even before you create the transaction. The card is validated by its card number and for the merchant:

Request

POST /api/v2/Loyalty/MerchantCards/MRC/validateMerchantcard HTTP/1.1
Host: connect-testing.secuconnect.com
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "cardnumber": "9276004429999952",
    "merchant": "MRC_BCSPDJBAT5QXBHUSBPGHY2Q8X8U8ON"
}

The response tells you the validity of the card. It is short if it is not a valid card:

Response (Invalid Card)

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "isValid": false
}

The card number might ben unknown at all, or it is not related to this merchant.

If the card is valid, there are a few more details:

Response (Valid Card)

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "isValid": true,
    "hasPasscode": false,
    "isLocked": true
}

The details mean:

Field	Explanation
`isValid`	`true` for card numbers valid for this merchant, `false` if not.
`hasPasscode`	Only present for valid cards. Not needed for e-commerce nor POS integration.
`isLocked`	Only present for valid cards. If `true`, you cannot use the card to pay. You should not add this card to your Smart Transaction.

Check the Card Security Code

If your application requires it, you can check the Card Security Code (CSC). This four-digit code is printed at the back side of the card if so ordered.

The endpoint to check the card security code is POST /api/v2/Loyalty/MerchantCards/{id}/checkCsc:

Request

POST /api/v2/Loyalty/MerchantCards/MCD_2RXTNXPRM2YG9922UMBHHAEWEGN6AJ/checkCsc HTTP/1.1
Host: connect-testing.secuconnect.com
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "cardnumber": "9276004429942845",
    "csc": "4471"
}

Successful response:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "result": true
}

The result signalizes whether the CSC was valid (true) or invalid (false). If the CSC is invalid you must not use the card.

Obtain Details of a Merchant Card

You can check the card status and balance without a Smart Transaction. This is useful if a buyer only asks for the card balance.

The obtain the card details using the card number you need to call GET /Loyalty/MerchantCards/?q=card.cardnumber:{id}. You don't need to send a request body.

Request

GET /api/v2/Loyalty/MerchantCards?q=card.cardnumber:9276004428481652 HTTP/1.1
Host: connect-testing.secuconnect.com
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

You will receive a list of cards. Since you seek for a certain card number, there should be one match or none, for instance for a typo.

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "count": 1,
    "data": [
        {
            "object": "loyalty.merchantcards",
            "id": "MCD_W5ZVSRG8U2MN358FD2MRDCMPYM06AU",
            "merchant": {
                "object": "general.merchants",
                "id": "MRC_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8"
            },
            "created_for_merchant": {
                "object": "general.merchants",
                "id": "MRC_F40KSJYW5AAJHHC93TQ6C7A8X76WO6"
            },
            "card": {
                "object": "loyalty.cards",
                "id": "CRD_3CVJTETZ3MHPR034C9BYGEKDH6XRP4",
                "cardnumber": "9276004428481652",
                "created": "2015-02-20T08:54:07+01:00"
            },
            "cardgroup": {
                "object": "loyalty.cardgroups",
                "id": "CRG_2BESGJNETJJRZVVYS8R7JWGVWK4PRZ",
                "display_name": "Geschenkgutschein",
                "display_name_raw": "Geschenkgutschein",
                "stock_warn_limit": 0,
                "picture": "https://connect.secucard.com/ds_g/8e79737df1e2513db48908b342c3cc436edf501a"
            },
            "created_for_store": {
                "object": "general.stores",
                "id": "STO_2ZCZRU9V6U8QA7B49K94667UP6C4PJ"
            },
            "is_base_card": false,
            "points": 0,
            "cash_balance": 300,
            "bonus_balance": 52,
            "balance": 352,
            "last_usage": "2019-09-12T10:52:22+02:00",
            "last_charge": "2018-04-27T15:47:42+02:00",
            "stock_status": "inactive",
            "lock_status": "unlocked",
            "passcode": 1,
            "expiry_date": null
        }
    ]
}

The card details are the same like those you receive in the Smart Transaction.

The card in our example has a cash balance of €3.00, a bonus balance of €0.52, making a total balance of €3.52 (line 39-41).

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

The card is not locked and has no expiry date.