Process to Load a Loyalty Card

In order to load a loyalty card, you need to:

Create a Smart Transaction with:
- the card in the idents array;
- a special article in the basket.
Carry out the payment.

The special article is passed like an ordinary article. It just needs to have the special EAN/GTIN 4260447149502, that we have reserved for this purpose.

The special EAN is eligible for bonus collection. If the card group is also configured for a bonus program, they effectively given a discount on the card charge. Sometimes that's what you want.

You can exclude the card charge from bonification, when you consider the above EAN in the blacklist or whitelist configuration.

Create the Smart Transaction

Firstly we create a Smart Transaction. It contains the card, and a special basket item to load it.

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "contract": {
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "id": "SDV_WPX6NU09Q2NDF0KJD3H584EXJR3XA2"
    },
    "customer": {
        "id": "PCU_H8ZQSFS9G2X07TF5JF89V55H645UA2"
    },
    "intent": "sale",
    "idents": [
        {
            "type": "card",
            "value": "9276004424644352"
        }
    ],
    "basket": {
        "products": [
            {
                "id": 1,
                "articleNumber": 30200,
                "desc": "Dining service Puslnitz, 26 pieces",
                "quantity": 1,
                "priceOne": 5900, // €59
                "tax": 19
            },
            {
                "id": 2,
                "ean": "4260447149502",
                "articleNumber": null,
                "desc": "Kartenaufladung 20 EUR",
                "quantity": 1,
                "priceOne": 2000, // €20
                "tax": 0
            }
        ]
    },
    "basket_info": {
        "sum": 7900, // €79
        "currency": "EUR"
    }
}

This creates a Smart Transaction with a basket total of €79. The special article carries the special EAN 4260447149502 to load the card.

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

Successful response:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_W28QKGS8H2X07TF64EDJ8DZEJN9RA2",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
        "companyname": "Secupay Test-Shop"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "customer": {
        "object": "payment.customers",
        "id": "PCU_H8ZQSFS9G2X07TF5JF89V55H645UA2",
        "contact": {
            "forename": "Demond",
            "surname": "Mustermann",
            "name": "Demond Mustermann",
            // ...
        }
    },
    "device_source": {
        "object": "smart.devices",
        "id": "SDV_WPX6NU09Q2NDF0KJD3H584EXJR3XA2"
    },
    "transactions": [],
    "created": "2021-01-20T09:37:32+01:00",
    "status": "created",
    "transactionRef": null,
    "merchantRef": null,
    "intent": "sale",
    "basket": {
        "products": [{
            "id": 1,
            "parent": null,
            "item_type": "article",
            "desc": "Dining service Puslnitz, 26 pieces",
            "articleNumber": "30200",
            "ean": "",
            "quantity": 1,
            "priceOne": 5900,
            "tax": 19,
            "reference_id": null,
            "group": []
        }, {
            "id": 2,
            "parent": null,
            "item_type": "article",
            "desc": "Kartenaufladung 20 EUR",
            "articleNumber": "",
            "ean": "4260447149502",
            "quantity": 1,
            "priceOne": 2000,
            "tax": 0,
            "reference_id": null,
            "group": []
        }],
        "type": "default",
        "texts": []
    },
    "basket_info": {
        "sum": 7900,
        "gratuity": null,
        "currency": "EUR"
    },
    "idents": [{
        "object": "smart.idents",
        "id": "smi_1",
        "prefix": "9276",
        "name": "secucard Kundenkarte",
        "type": "card",
        "value": "9276004424644352",
        "valid": true,
        "merchantcard": {
            "object": "loyalty.merchantcards",
            "id": "MCD_2UXQJ84A62MENH7UWH6QXDYJSBNAA9",
            "merchant": {
                "object": "general.merchants",
                "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8"
            },
            "created_for_merchant": {
                "object": "general.merchants",
                "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8"
            },
            "card": {
                "object": "loyalty.cards",
                "id": "CRD_22H4H5D47Q44URN2K8KTP876H6M3PM",
                "cardnumber": "9276004424644352",
                "created": "2015-02-20T08:51:46+01:00"
            },
            "cardgroup": {
                "object": "loyalty.cardgroups",
                "id": "CRG_GO7GQ6DHW3TJYGDF64WD16PUIDHQ8Y",
                "display_name": "Bonus",
                "display_name_raw": "Bonus",
                "stock_warn_limit": 0,
                "picture": "https:\/\/connect.secucard.com\/ds_g\/8e79737df1e2513db48908b342c3cc436edf501a"
            },
            "created_for_store": {
                "object": "general.stores",
                "id": "STO_3522R8MS2MSHCN7D37UVJYR4P6C4PX"
            },
            "is_base_card": false,
            "points": 0,
            "cash_balance": 200, // €2.00
            "bonus_balance": 20, // €0.20
            "balance": 220, // €2.20
            "last_usage": "2017-10-11T09:34:42+02:00",
            "last_charge": "2017-10-11T09:34:42+02:00",
            "stock_status": "inactive",
            "lock_status": "unlocked",
            "passcode": 1,
            "expiry_date": null
        }
    }],
    "is_demo": true,
    // ...
}

The card has not yet been charged. This is done in the next step, when the payment is made.

Capture the Payment

You would carry out the payment as described in the integration guide for payment. We assume this is already implemented.

The last step is always a call to /start:

Request

POST /api/v2/Smart/Transactions/STX_W28QKGS8H2X07TF64EDJ8DZEJN9RA2/start HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with 200 OK, and the status of the Smart Transaction is updated once more:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_W28QKGS8H2X07TF64EDJ8DZEJN9RA2",
    // ...
    "updated": "2021-01-20T09:37:50+01:00",
    "status": "ok",
    // ...
    "receipt": [{
        "type": "separator",
        "value": {
            "caption": "Kundenkarte"
        }
    }, {
        "type": "name-value",
        "value": {
            "name": "Kartennummer: ",
            "value": "9276004424644352",
            "decoration": []
        }
    }, {
        "type": "name-value",
        "value": {
            "name": "TA Code: ",
            "value": "32076570",
            "decoration": []
        }
    }, {
        "type": "space"
    }, {
        "type": "textline",
        "value": {
            "text": "Umsatz erfasst:",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "79,00 EUR",
            "decoration": ["important"]
        }
    }, {
        "type": "space"
    }, {
        "type": "textline",
        "value": {
            "text": "Bonus:",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "7,90 EUR",
            "decoration": ["important"]
        }
    }, {
        "type": "space"
    }, {
        "type": "textline",
        "value": {
            "text": "Aktuelles Guthaben",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "10,10 EUR",
            "decoration": ["important"]
        }
    }, {
        "type": "separator",
        "value": {
            "caption": "Kundenkarte Aufladung"
        }
    }, {
        "type": "name-value",
        "value": {
            "name": "Kartennummer:",
            "value": "9276004424644352",
            "decoration": []
        }
    }, {
        "type": "name-value",
        "value": {
            "name": "TA Code:",
            "value": "32076572",
            "decoration": []
        }
    }, {
        "type": "space"
    }, {
        "type": "textline",
        "value": {
            "text": "Folgender Betrag",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "wurde aufgeladen:",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "20,00 EUR",
            "decoration": ["important"]
        }
    }, {
        "type": "space"
    }, {
        "type": "textline",
        "value": {
            "text": "Aktuelles Guthaben:",
            "decoration": []
        }
    }, {
        "type": "textline",
        "value": {
            "text": "30,10 EUR",
            "decoration": ["important"]
        }
    }],
    // ...
    "idents": [{
        "object": "smart.idents",
        // ...
        "merchantcard": {
            "object": "loyalty.merchantcards",
            "id": "MCD_2UXQJ84A62MENH7UWH6QXDYJSBNAA9",
            // ...
            "cash_balance": 2200,
            "bonus_balance": 810,
            "balance": 3010,
            "last_usage": "2021-01-20T09:37:59+01:00",
            "last_charge": "2021-01-20T09:37:59+01:00",
            // ...
        }
    }],
    // ...
}

Response status 200 OK, the field "status": "ok" and the receipt show, the payment has been made, and the loyalty card has been loaded.

Send a Customer Notification

Our system can send a notification email to the customer. The email is composed of your individual template and data found in the Smart Transaction. This function is available at an additional cost.

In order to send such an email you need to pass a communications object to the Smart Transaction:

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "contract": {
        "id": "GCR_9OIH9JOL8KIV5PFJBEOS2NN8TCM1DF"
    },
    "device_source": {
        "id": "SDV_WPX6NU09Q2NDF0KJD3H584EXJR3XA2"
    },
    "customer": {
        "contact": {
            "salutation": "Mr.",
            "title": "Dr.",
            "forename": "Max",
            "surname": "Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "25 b",
                "postal_code": "99999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "max123@example.org"
        }
    },
    "intent": "sale",
    "idents": [
        {
            "type": "card",
            "value": "9276004424644352"
        }
    ],
    "basket": {
        "products": [
            {
                "id": 1,
                "ean": "4260447149502",
                "articleNumber": null,
                "desc": "Kartenaufladung 20 EUR",
                "quantity": 1,
                "priceOne": 2000, // €20
                "tax": 0
            }
        ]
    },
    "basket_info": {
        "sum": 2000, // €20
        "currency": "EUR"
    },
    "communications": {
        "action_type": "charge",
        "template_id": "ETP_6RYLPEWO8O2UPZV83C095P7IQ4GAL1" 
    }
}

This would also work if you let our system create the Smart Transaction on-the-fly as described in another section. Then the idents field would look different.

Parameter details:

Field	Type	Meaning
`communications`	`object`	Optional control for the email communication.
`communications/action_type`	`string`	Must be `charge`.
`communications/template_id`	`string`	Must be the template ID you have received from our project contact.

The email is sent when the Smart Transaction is started. Then the payment is captured, and the card is actually charged (loaded). If you use auto_capture the payment is captured immediately after successful authorisation. It is sent to the email address of the customer in the Smart Transaction (customer/contact/email).

Cross-reference table between Smart Transaction and email template:

Field in Smart Transaction	Placeholder in Email	Example
`customer/contact/salutation`	{{salutation}}	Herr
`customer/contact/title`	{{title}}	Dr.
`customer/contact/forename`	{{forename}}	Max
`customer/contact/surname`	{{surname}}	Mustermann
`idents/#/cardnumber`¹	{{cardnumber}}	9276004424644352
`basket/products/#/priceOne`	{{amount}}	20,00
`basket/products/#/desc`	{{article_description}}	Kartenaufladung 20 EUR

¹) If you create the card on-the-fly, our system will automatically set this field when the card is created. You can omit it.