Authorise and Capture the Payment
From the perspective of your loyalty integration there are three ways to pay:
only by secucard;
only by credit card, or SEPA direct debit;
partially by secucard, and the missing sum by credit card, or SEPA direct debit.
Your system tells our API when the payer wants to use his secucard. In our answer, you see, whether it can be paid with this card, or how much is the missing, that needs to be paid by one of the other methods.
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:
POST /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ/preTransaction HTTP/1.1Host: connect-testing.secupay-ag.deAuthenticate: Bearer qb56tjj1bcvo9n2nj4u38k84loAccept: application/jsonIf everything is fine, the API responds with 200 OK and some details:
HTTP/1.1 200 OKContent-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:
GET /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ HTTP/1.1Host: connect-testing.secupay-ag.deAuthenticate: Bearer qb56tjj1bcvo9n2nj4u38k84loAccept: application/jsonThis is the response:
HTTP/1.1 200 OKContent-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.
Pay Fully by Secucard
Given you have called preTransaction and received a missing_sum of 0 (zero), and the order can be paid fully by secucard. You need to call the endpoint to execute a pure loyalty transaction:
POST /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ/start/loyalty HTTP/1.1Host: connect-testing.secupay-ag.deAuthenticate: Bearer qb56tjj1bcvo9n2nj4u38k84loAccept: application/jsonThere is no need for a previous authorization call (endpoint POST /api/v2/Smart/Transactions/{id}/prepare) here.
If everything is fine, the API responds with HTTP status 200 OK, and the new object representation:
HTTP/1.1 200 OKContent-Type: application/json...{ "object": "smart.transactions", "id": "STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ", // ... "status": "ok", // ... "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" }, "receipt": [{ "type": "separator", "value": { "caption": "Kundenkarte" } }, { "type": "name-value", "value": { "name": "Kartennummer:", "value": "9276004424644352", "decoration": [] } }, { "type": "name-value", "value": { "name": "TA Code:", "value": "30061885", "decoration": [] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Umsatz erfasst:", "decoration": [] } }, { "type": "textline", "value": { "text": "7,25 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Bonus:", "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Aktuelles Guthaben", "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }], "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": 72, "balance": 72, "last_usage": "2020-10-28T14:16:10+01:00", "last_charge": "2020-10-28T14:16:10+01:00", "stock_status": "active", "lock_status": "unlocked", "passcode": 1, "expiry_date": null } }], "payment_method": "loyalty", // ...}Pay the Remainder by Credit Card or SEPA Direct Debit
Given you have not applied the card with preTransaction, or there was a missing_sum that needs to be paid by credit card or SEPA direct debit. In the Getting Started section we have demonstrated this for SEPA direct debit.
The payment process is exactly the same like for other e-commerce payments. There are two different guides explaining this. If you haven't implemented it yet, you need to consult one of these guides:
The only difference is that you find a receipt node in the Smart Transaction after you have started it.
This is our call to execute the already authorized payment:
POST /api/v2/Smart/Transactions/STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ/start HTTP/1.1Host: connect-testing.secupay-ag.deAuthenticate: Bearer qb56tjj1bcvo9n2nj4u38k84loAccept: application/jsonIf everything is fine, the API responds with HTTP status 200 OK, and the object representation of the Smart Transaction:
HTTP/1.1 200 OKContent-Type: application/json...{ "object": "smart.transactions", "id": "STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ", // ... "transactions": [{ "object": "payment.transactions", "id": "PCI_AT03WBYQDU8RS8RQ6XFGNZ4X0C64N4" }], "created": "2020-10-28T14:16:02+01:00", "updated": "2020-10-28T14:16:06+01:00", "status": "ok", // ... "intent": "sale", "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" }, "receipt": [{ "type": "separator", "value": { "caption": "Kundenkarte" } }, { "type": "name-value", "value": { "name": "Kartennummer:", "value": "9276004424644352", "decoration": [] } }, { "type": "name-value", "value": { "name": "TA Code:", "value": "30061885", "decoration": [] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Zahlung \u00fcber:", "decoration": [] } }, { "type": "textline", "value": { "text": "0,71 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Umsatz erfasst:", "decoration": [] } }, { "type": "textline", "value": { "text": "7,25 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Bonus:", "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Aktuelles Guthaben", "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }], "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": 72, "balance": 72, "last_usage": "2020-10-28T14:16:10+01:00", "last_charge": "2020-10-28T14:16:10+01:00", "stock_status": "active", "lock_status": "unlocked", "passcode": 1, "expiry_date": null } }], "payment_method": "debit", "trans_id": "30061884", // ...}Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent). This applies to all basket details, and the card details. In contrast, the receipt lines are text lines, and the amounts are already formatted.
Status ok, received or collection means you can deliver. Status pending means you have to wait for one of these statusses. Status failed means the payment failed, and you must repeat the payment process.
Print the Receipt
Example Smart Transaction with Receipt
After the payment was executed, the Smart Transaction may contain a receipt:
{ "object": "smart.transactions", "id": "STX_2XYYHKXXV2NRCHVSHCS45WSE63PMA2", // ... "status": "ok", // ... "receipt": [ { "type": "separator", "value": { "caption": "Kundenkarte Aufladung" } }, { "type": "name-value", "value": { "name": "Terminal-ID:", "value": "VT000124", "decoration": [] } }, { "type": "name-value", "value": { "name": "Datum:", "value": "24.09.2020 14:40:58", "decoration": [] } }, { "type": "name-value", "value": { "name": "Kartennummer:", "value": "9276004429942845", "decoration": [] } }, { "type": "name-value", "value": { "name": "TA Code:", "value": "29187305", "decoration": [] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Zahlung über:", "decoration": [] } }, { "type": "textline", "value": { "text": "5,00 EUR", "decoration": [ "important" ] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Folgender Betrag", "decoration": [] } }, { "type": "textline", "value": { "text": "wurde aufgeladen:", "decoration": [] } }, { "type": "textline", "value": { "text": "10,00 EUR", "decoration": [ "important" ] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Aktuelles Guthaben", "decoration": [] } }, { "type": "textline", "value": { "text": "10,00 EUR", "decoration": [ "important" ] } } ], // ...}Here the generated PDF for this receipt:
PDF for similar receipt
There are four types of receipt lines. You can distinguish them by the type field:
separators with optional headline;
plain textlines;
name-value lines;
space lines.
Furthermore there are some decorations to emphasise lines, or to align the text at the line.
Separator Line
The separator line starts a new receipt with a caption:
{ "type": "separator", "value": { "caption": "Kundenkarte Aufladung" }}The separator line is like a headline. It needs to be centered, and is printed bolder and larger than normal text. It should be padded with some space at the top and the bottom.
The attribute caption is optional:
{ "type": "separator", "value": { }}If there is no caption, you can print a horizontal line instead, or just a number of dashes.
Separator lines have no decorations.
Text Line
A text line, here with decoration important:
{ "type": "textline", "value": { "text": "10,00 EUR", "decoration": [ "important" ] }}Text lines can have one or more of these decorations:
important (print it bold);
align-left
align-center
align-right
The default alignment is to the left.
Name-Value Line
A name-value line, with one text adjusted to the left, the other to the right:
{ "type": "name-value", "value": { "name": "Kartennummer:", "value": "9276004429942845", "decoration": [] }}Name and value shall be printed at the same line. The name is adjusted to the left, and the value to the right.
Name-value lines can have the decoration important. Here goes the same like for normal text lines. It needs to be printed bolder.
Space Line
This is a space line:
{ "type": "space"}A space line is used to add some vertical space between a series of normal text or name-value lines. It is used to form text sections.
Space lines have neither attributes nor decorations.