Mixed Baskets Transactions for Marketplaces
This guide is only needed for marketplaces. It is relevant if you use mixed basket transactions; this is one transaction for multiple merchants of your Internet marketplace.
This guide is to understand the relationship between the Smart Transaction and the several Payment Transactions in the case of mixed basket transactions / marketplaces.
Transactions and Relations
These are the transactions:
Smart Transaction control the checkout process
Payment Transactions control the payment process
Loyalty Transactions may control gift vouchers or customer loyalty cards
About these you should know:
Your application creates the Smart Transaction for the checkout.
You may offer your customers our Smart Checkout or your custom checkout.
At each authorisation attempt, the Smart Transaction manages to create the needed Payment Transactions. Further authorisation attempts unlink and replace the former Payment Transactions by new ones.
There is one leading Payment Transaction for the Smart Transaction (or the order respectively). We call this the original transaction.
There may be more Payment Transactions like sub-transactions for sub-baskets, but also stakeholder payments, refunds, and the like. These are linked with each other.
The original transaction, the sub-transaction, but also Loyalty Transactions, appear in the Smart Transaction.
Your application needs to know the original transaction to receive push messages for the entire payment.
As marketplace, your application also needs to know the respective sub-transactions to refund payments, or to signalise shipment (only needed for invoice payment).
This means, you need to figure out which Payment Transaction is which. You need to assign the Smart Transaction and the original Payment Transaction to your order. And you need to assign the sub-transactions to the sub-baskets.
Smart Transaction
Assuming you create this Smart Transaction for an order with two sub-baskets calling POST /api/v2/Smart/Transactions:
POST /api/v2/Smart/Transactions HTTP/1.1Host: connect-testing.secupay-ag.deAuthorization: Bearer qb56tjj1bcvo9n2nj4u38k84loContent-Type: application/jsonAccept: application/json{ "is_demo": true, "contract": { "id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0" }, "intent": "sale", "customer": { "contact": { "forename": "Max", "surname": "Mustermann", "email": "max@examepl.net", "address": { "street": "Musterstr.", "street_number": "12", "postal_code": "09678", "city": "Musterstadt", "country": "DE" } } }, "basket": { "products": [ { "item_type": "sub_transaction", "desc": "Warenkorb Musterhändler 1", "reference_id": "sb0", "contract_id": "GCR_EHSXUGFDAYR59SJ844OXGJLEX50M3X", "sum": 2400, "sub_basket": [ { "id": 1, "item_type": "article", "desc": "Kaffeepads Aromata 50 Stück", "articleNumber": "1", "quantity": 2, "priceOne": 1000, "tax": 19 }, { "id": 2, "item_type": "shipping", "desc": "Standardversand", "quantity": 1, "priceOne": 400, "tax": 19 }, { "item_type": "stakeholder_payment", "desc": "Gebühr für Mustermarktplatz", "reference_id": "sb0fee", "contract_id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0", "sum": 100 } ] }, { "item_type": "sub_transaction", "desc": "Warenkorb Musterhändler 2", "reference_id": "sb1", "contract_id": "GCR_RPVN7U916USSIR1F1MNYHB58U097RT", "sum": 2500, "sub_basket": [ { "id": 1, "item_type": "article", "desc": "Kugelschreiber", "articleNumber": "1", "quantity": 1, "priceOne": 2000, "tax": 19 }, { "id": 1000, "parent": null, "item_type": "shipping", "desc": "Standardversand", "quantity": 1, "priceOne": 500, "tax": 19 }, { "item_type": "stakeholder_payment", "desc": "Gebühr für Mustermarktplatz", "reference_id": "sb1fee", "contract_id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0", "sum": 100 } ] } ], "type": "mixed" }, "basket_info": { "sum": 4900, "currency": "EUR" }, "payment_context": { "auto_capture": true }}Please note that we have passed unique reference_ids for each sub-basket ("sb0", "sb1") and also for the stakeholder payments within them.
The authorisation and capture would only need one call to POST /api/v2/Smart/Transactions/STX_WMS58S5DU2PAAE4EEEUVB6MC0K4MAZ, since it uses auto_capture. If everything is fine, it would respond with something like this:
HTTP/1.1 200 OKContent-Type: application/json{ "object": "smart.transactions", "id": "STX_WMS58S5DU2PAAE4EEEUVB6MC0K4MAZ", "merchant": { "object": "general.merchants", "id": "MRC_CT3L0A4HX3DKHENS2XUIJIAO1I1R6V" "companyname": "Mustermarktplatz AG" }, "contract": { "object": "general.contracts", "id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0" }, "customer": { "object": "payment.customers", "id": "PCU_W4XKM7SJ22PAAE5H6GJJNPWZ0ZJ2AJ", "contact": { "name": "Max Mustermann", "forename": "Max", "surname": "Mustermann", "email": "max@examepl.net", "address": { "street": "Musterstr.", "street_number": "12", "postal_code": "09678", "city": "Dresden", "country": "DE" } } }, "container": { "object": "payment.containers", "id": "PCT_3NV506CZA2PAAE5RVSTZCX0RGCJQA2", "type": "bank_account" }, "transactions": [ { "object": "payment.transactions", "id": "PCI_296F94HVPPDN9B2WTEPCY248W8CPMH", "trans_id": 110143331, "transaction_hash": "wjtrmjjwvesq11095745" }, { "object": "payment.transactions", "id": "PCI_4HXWPSWNSV4AYQ36Z7JKZ248W8CPMJ", "trans_id": 110143333, "transaction_hash": "wjtrmjjwvesq11095745_110143333", "reference_id": "sb1" }, { "object": "payment.transactions", "id": "PCI_648F7VUS8FN8HXEJZ8V8U248W8CPMZ", "trans_id": 110143332, "transaction_hash": "wjtrmjjwvesq11095745_110143332", "reference_id": "sb0" } ], "created": "2023-11-07T18:17:16+01:00", "updated": "2023-11-07T18:18:49+01:00", "status": "ok", "intent": "sale", "basket": { "products": [ { "item_type": "sub_transaction", "desc": "Warenkorb Musterhändler 1", "reference_id": "sb0", "contract_id": "GCR_EHSXUGFDAYR59SJ844OXGJLEX50M3X", "sum": 2400, "sub_basket": [ { "id": 1, "item_type": "article", "desc": "Kaffeepads Aromata 50 Stück", "articleNumber": "1", "quantity": 2, "priceOne": 1000, "tax": 19 }, { "id": 2, "item_type": "shipping", "desc": "Standardversand", "quantity": 1, "priceOne": 400, "tax": 19 }, { "item_type": "stakeholder_payment", "desc": "Gebühr Mustermarktplatz", "reference_id": "sb0fee", "contract_id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0", "sum": 100 } ] }, { "item_type": "sub_transaction", "desc": "Warenkorb Musterhändler 2", "reference_id": "sb1", "contract_id": "GCR_RPVN7U916USSIR1F1MNYHB58U097RT", "sum": 2500, "sub_basket": [ { "id": 1, "item_type": "article", "desc": "Kugelschreiber", "articleNumber": "1", "quantity": 1, "priceOne": 2000, "tax": 19 }, { "id": 1000, "item_type": "shipping", "desc": "Standardversand", "quantity": 1, "priceOne": 500, "tax": 19 }, { "item_type": "stakeholder_payment", "desc": "Gebühr für Mustermarktplatz", "reference_id": "sb1fee", "contract_id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0", "sum": 100 } ] } ], "type": "mixed" }, "basket_info": { "sum": 4900, "currency": "EUR" }, "payment_method": "debit", "trans_id": 110143331, "is_demo": true, "payment_context": { "auto_capture": true }}You might have received the same representation of the Smart Transaction from:
POST /api/v2/Smart/Transactions/STX_WMS58S5DU2PAAE4EEEUVB6MC0K4MAZ/start after a separate call for authorisation
GET /api/v2/Smart/Transactions/STX_WMS58S5DU2PAAE4EEEUVB6MC0K4MAZ after authorsation and capture
There are three transactions in the field transactions now:
|
Role |
reference_id |
ID |
|
Original transaction |
n/a |
PCI_296F94HVPPDN9B2WTEPCY248W8CPMH |
|
Sub-transaction for sub-basket #1 |
sb0 |
PCI_648F7VUS8FN8HXEJZ8V8U248W8CPMZ |
|
Sub-transaction for sub-basket #2 |
sb1 |
PCI_4HXWPSWNSV4AYQ36Z7JKZ248W8CPMJ |
The Payment Transactions may appear on different points in time:
The original transaction is created (and perhaps replaced) with every authorisation attempt.
The sub-transactions are created with the actual capture (except prepayment and invoice payment).
Please remember that there may be also Loyalty Transactions. Your application must recognise such with "object": "payment.transactions" only.
Original Payment Transaction
Now let's also see the Payment Transactions. You may need to read them at a callback event (push service).
The original transaction appears at the very moment of the authorisation attempt. It can be read with GET /api/v2/Payment/Transaction/PCI_296F94HVPPDN9B2WTEPCY248W8CPMH. It would respond with:
HTTP/1.1 200 OKContent-Type: application/json{ "object": "payment.transactions", "id": "PCI_296F94HVPPDN9B2WTEPCY248W8CPMH", "merchant": { "object": "general.merchants", "id": "MRC_CT3L0A4HX3DKHENS2XUIJIAO1I1R6V", "type": 46, "user": { "name": "Maritta Mustermann", "companyname": "Mustermarktplatz AG", "project_name": "Mustermarktplatz AG" } }, "contract": { "object": "general.contracts", "id": "GCR_5U563VNRWGUQPZ79R85JZHBN0R2OW0" }, "related_transactions": [ { "object": "payment.transactions", "id": "PCI_648F7VUS8FN8HXEJZ8V8U248W8CPMZ", "hierarchy": "child", "ref_type_id": 86, "ref_type_raw": "Aufteilung Warenkorb", "trans_id": 110143332 }, { "object": "payment.transactions", "id": "PCI_4HXWPSWNSV4AYQ36Z7JKZ248W8CPMJ", "hierarchy": "child", "ref_type_id": 86, "ref_type_raw": "Aufteilung Warenkorb", "trans_id": 110143333 } ], "trans_id": 110143331, "product_id": 20, "product": "Lastschrift Demo", "product_raw": "Lastschrift Demo", "zahlungsmittel_id": 941956, "contract_id": 49760, "amount": 4900, "currency": "EUR", "created": "2023-11-07T18:18:47+01:00", "completion_date": "2023-11-07T18:19:04+01:00", "updated": "2023-11-07T18:19:04+01:00", "description": "Bestellung am 07.11.2023 via secupay bei Secupay Test-Shop (264748)", "description_raw": "Bestellung am 07.11.2023 via secupay bei Secupay Test-Shop (264748)", "status": 6, "status_text": "abgeschlossen", "details": { "cleared": "open", "status": 6, "status_text": "abgeschlossen", "status_simple": 1, "status_simple_text": "accepted", "amount": 4900, "description": "Bestellung am 07.11.2023 via secupay bei Secupay Test-Shop (264748)", "description_raw": "Bestellung am 07.11.2023 via secupay bei Secupay Test-Shop (264748)" }, "customer": { "forename": "Max", "surname": "Mustermann", "name": "Max Mustermann", "email": "max@examepl.net", "address": [ { "type": "invoice", "address_components": [ { "long_name": "12", "short_name": "55", "types": [ "street_number" ] }, { "long_name": "Musterstraße", "short_name": "Musterstr.", "types": [ "route" ] }, { "long_name": "Dresden", "short_name": "Dresden", "types": [ "locality", "political" ] }, { "long_name": "Germany", "short_name": "DE", "types": [ "country", "political" ] }, { "long_name": "09678", "short_name": "09123", "types": [ "postal_code" ] } ], "address_formatted": "Musterstraße 12, 09678 Dresden, Germany" } ] }, "payment_data": "DE02 XXXX XXXX XXXX XX04 02", "transaction_hash": "wjtrmjjwvesq11095745"}The sub-transactions appear in related_transactions. All sub-transactions have "ref_type_id": 86.
Payment Transaction for Sub-Basket
The sub-transactions can appear later with the capture of the payment. One of the sub-transactions can be read with GET /api/v2/Payment/Transaction/PCI_648F7VUS8FN8HXEJZ8V8U248W8CPMZ. It would respond with:
HTTP/1.1 200 OKContent-Type: application/json{ "object": "payment.transactions", "id": "PCI_648F7VUS8FN8HXEJZ8V8U248W8CPMZ", "merchant": { "object": "general.merchants", "id": "MRC_ZU440OOX2U6PVVX9VB0HUEWZ5G044L", "type": 46, "user": { "name": "Marina Mustermann", "companyname": "Musterhändler 1" } }, "platform": { "object": "general.merchants", "id": "MRC_CT3L0A4HX3DKHENS2XUIJIAO1I1R6V" }, "contract": { "object": "general.contracts", "id": "GCR_EHSXUGFDAYR59SJ844OXGJLEX50M3X" }, "parents": [ { "object": "payment.transactions", "id": "PCI_296F94HVPPDN9B2WTEPCY248W8CPMH", "ref_type_id": 86, "trans_id": 110143331 } ], "trans_id": 110143332, "product_id": 20, "product": "Lastschrift Demo", "product_raw": "Lastschrift Demo", "zahlungsmittel_id": 941956, "contract_id": 2109134, "amount": 2400, "currency": "EUR", "created": "2023-11-07T18:18:47+01:00", "completion_date": "2023-11-07T18:19:04+01:00", "updated": "2023-11-07T18:19:04+01:00", "description": "Warenkorb Musterfirma", "description_raw": "Warenkorb Musterfirma", "status": 6, "status_text": "abgeschlossen", "details": { "cleared": "open", "status": 6, "status_text": "abgeschlossen", "status_simple": 1, "status_simple_text": "accepted", "amount": 2400, "description": "Warenkorb Musterfirma", "description_raw": "Warenkorb Musterfirma" }, "customer": { "forename": "Max", "surname": "Mustermann", "name": "Max Mustermann", "email": "max@examepl.net", "address": [ { "type": "invoice", "address_components": [ { "long_name": "12", "short_name": "55", "types": [ "street_number" ] }, { "long_name": "Musterstraße", "short_name": "Musterstr.", "types": [ "route" ] }, { "long_name": "Dresden", "short_name": "Dresden", "types": [ "locality", "political" ] }, { "long_name": "Germany", "short_name": "DE", "types": [ "country", "political" ] }, { "long_name": "09678", "short_name": "09678", "types": [ "postal_code" ] } ], "address_formatted": "Musterstraße 12, 09678 Dresden, Germany" } ] }, "payment_data": "DE02 XXXX XXXX XXXX XX04 02", "transaction_hash": "wjtrmjjwvesq11095745_110143332", "reference_id": "sb0"}The original transaction appears in parents. It has "ref_type_id": 86. The reference_id is "sb0", which refers to the first sub-basket of our Smart Transaction.