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:

Request to Create the Smart Transaction
POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: 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:

Response on Authorisation and Capture
HTTP/1.1 200 OK
Content-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:

Response for the Original Transaction
HTTP/1.1 200 OK
Content-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:

Response for a Sub-Transaction
HTTP/1.1 200 OK
Content-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.