Apply the Loyalty Card for Payment

In order to use the card balance for payment, you need to call POST /api/v2/Smart/Transactions/{id}/preTransaction. If you only want to charge the card, or track revenue to gain balance, you need not call this endpoint.

We apply the card balance to our Smart Transaction:

Request
POST /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ/preTransaction 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 some details:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"missing_sum": 725,
"bonus_products": [{
"id": 4,
"articleNumber": "111111117",
"ean": "111111117",
"quantity": 1,
"priceOne": -53,
"tax": 7,
"desc": "Bonus Steuer 7"
}, {
"id": 5,
"articleNumber": "1111111119",
"ean": "1111111119",
"quantity": 1,
"priceOne": -18,
"tax": 19,
"desc": "Bonus Steuer 19"
}]
}

The buyer would spend €0.71 with bonus balance. There are €0.53 collected for articles with the reduced VAT rate of 7%, and €0.18 for the full rate of 19%.

In this example the buyer would have to pay €7.25 using another payment method. If there was also cash balance after spending the full bonus balance, the missing_sum would be be decreased even more.

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

These details also appear in the Smart Transaction now:

Request
GET /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ HTTP/1.1
Host: connect-testing.secupay-ag.de
Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

This is the response:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ",
// ...
"transactions": [],
// ...
"status": "processing",
// ...
"basket": {
"products": [{
"id": 1,
"parent": null,
"articleNumber": "30037",
"ean": "",
"desc": "Sandwich Romano",
"quantity": 1,
"priceOne": 349,
"tax": 7,
"group": [],
"serialNumber": null,
"item_type": "article",
"reference_id": null,
"contract_id": null,
"sum": null
}, {
"id": 2,
"parent": null,
"articleNumber": "30200",
"ean": "",
"desc": "Fruit salad, small bowl",
"quantity": 1,
"priceOne": 249,
"tax": 7,
"group": [],
"serialNumber": null,
"item_type": "article",
"reference_id": null,
"contract_id": null,
"sum": null
}, {
"id": 3,
"parent": null,
"articleNumber": "51",
"ean": "4999012345678",
"desc": "Water, mildly sprinkling, 0.25 ltr.",
"quantity": 2,
"priceOne": 99,
"tax": 19,
"group": [],
"serialNumber": null,
"item_type": "article",
"reference_id": null,
"contract_id": null,
"sum": null
}, {
"id": 4,
"parent": null,
"articleNumber": "111111117",
"ean": "111111117",
"desc": "Bonus Steuer 7",
"quantity": 1,
"priceOne": -53,
"tax": 7,
"group": [],
"serialNumber": null,
"item_type": "coupon",
"reference_id": null,
"contract_id": null,
"sum": null
}, {
"id": 5,
"parent": null,
"articleNumber": "1111111119",
"ean": "1111111119",
"desc": "Bonus Steuer 19",
"quantity": 1,
"priceOne": -18,
"tax": 19,
"group": [],
"serialNumber": null,
"item_type": "coupon",
"reference_id": null,
"contract_id": null,
"sum": null
}],
"texts": [],
"type": "default"
},
"basket_info": {
"sum": 725,
"currency": "EUR",
"gratuity": null,
"missing_sum": 725
},
"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_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8"
},
"created_for_merchant": {
"object": "general.merchants",
"id": "MRC_F40KSJYW5AAJHHC93TQ6C7A8X76WO6"
},
"card": {
"object": "loyalty.cards",
"id": "CRD_22H4H5D47Q44URN2K8KTP876H6M3PM",
"cardnumber": "9276004424644352",
"created": "2015-02-20T08:51:46+01:00"
},
"cardgroup": {
"object": "loyalty.cardgroups",
"id": "CRG_4VA6040D2DWRYHJKCWXZEW24654PRH",
"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": 0,
"bonus_balance": 71,
"balance": 71,
"last_usage": "2020-10-28T07:54:29+01:00",
"last_charge": "2020-10-28T07:54:29+01:00",
"stock_status": "active",
"lock_status": "unlocked",
"passcode": 1,
"expiry_date": null
}
}],
// ...
}

As you see, the Smart Transaction is in status processing now (line 10). There is no Loyalty or Payment Transaction (line 8), and the card is not charged yet (lines 137–139).

The missing sum is visible in the basket_info (line 96), and the special bonus items are added to the basket now (lines 58–88).

The system needs to remember the missing sum. If there is no remainder (missing_sum is 0) you have to execute a pure card payment. Otherwise you need to run the process for credit card or SEPA direct debit payment.