Guides
These docs are for v1.0.1. Click to read the latest docs for v2.1.0.

Marketplace

With our marketplace integration, you can start splitting payouts of a single transaction with as many sub-merchants as you want and add your marketplace fee to take your part out of the transaction. Your transactions are fully compliant to financial regulatory standards and you do not act as a middle-man since the money flow does not happen via your bank accounts. We currently support Mastercard and Visa transactions within our marketplace integration.

📘

Interested in adding marketplace payments to your solutions? Get in touch!

Whether you already have a fully operational marketplace or you are just getting started, we might be the best choice for you! Get in touch with us today and we'll make sure to advise you accordingly. Send us a message anytime by using this link.

Process Overview

A marketplace transaction follows the same behavior as other integrations: You initially create an Authorization which can involve goods of several sellers (sub-merchants) on your marketplace (eg. CHF 10.00). This transaction can be done with or without 3D Secure, depending on your acquiring agreement. Once the transaction has been completed, you can start with the settlements, which will define which portion of the transaction a sub-merchant will receive (eg. split in two - CHF 4.00 for sub-merchant 1 and CHF 6.00 for sub-merchant 2).

Marketplace Requests

For the marketplace approach to work, you need to process your authorizations with a Deferred Settlement request. This can be done by sending the parameter reqtype=NOA in your requests. After a transaction has been fully authorized, you can start sending your settlement requests. For each sub-merchant, you will have to send a separate settlement request, where you define the portion that the sub-merchant gets and a marketplace fee. You need to include a marketplace fee that is higher than the acquiring fees, else your transaction may result in an error within the acquirer's payout process.

Additional parameters

The following parameters are additionally required in marketplace Deferred Settlement and refund requests:

  • closeTransaction: Defines if the transaction should be closed for further settlements. Switch the value from no to yes in your last settlement request. This parameter is not required for refunds.
  • subMerchantId: The ID of your sub-merchant as defined by your acquirer.
  • fee - amount, currency: Your fee for your marketplace offerings that you want to take out of each operation. The acquiring fees will be automatically deducted from this amount.

Refunds

You can only refund the amount that was previously authorized. If you have an authorization amounting to CHF 10.00 , the maximum amount you are allowed to refund are CHF 10.00. You can also refund a lower amount if required, which would trigger a partial refund. For authorizations that were split, such as the example with two sub-merchants (CHF 6.00 + CHF 4.00), you will have to send two refund requests to refund the full amount of the authorization.

The cardholder will receive the full amount credited to their card account. The marketplace will receive the scheme and acquiring fees back from the refunded transaction and also the marketplace fee defined in the refund request. The marketplace fee from the refund will be charged to the sub-merchant. Refunds will be initiated once enough transactions have been processed to cover the amounts to be refunded.

Onboarding of New Sub-merchants

Each seller needs to be onboarded by the marketplace owner and will be verified by the acquirer - involving their own KYC and AML requirements. Once a sub-merchant has been successfully onboarded, a new subMerchantId will be assigned. Store these IDs to process your settlement requests. Please be aware that the onboarding process of new sub-merchants is performed by your acquirer.

Sample Requests

📘

More infos needed? Check out the API reference.

For a detailed description of the available parameters for your requests please check the API Reference page of our marketplace solution.

Partial Settlements

Example Request for Sub-merchant 1

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<paymentService version="1">
<body merchantId="1000011011">
	<transaction refno="123456789">
		<request>
		<amount>400</amount>
		<currency>CHF</currency>
		<uppTransactionId>200504160029573476</uppTransactionId>
		<reqtype>COA</reqtype>
		<transtype>05</transtype>
		<closeTransaction>no</closeTransaction>
		<marketplace>
			<subMerchantId>174322627</subMerchantId>
			<fee>
				<amount>80</amount>
				<currency>CHF</currency>
			</fee>
		</marketplace>
		</request>
	</transaction>
</body>
</paymentService>'
EOF

<?xml version='1.0' encoding='UTF-8'?>
<paymentService version='1'>
    <body merchantId='1000011011' status='accepted'>
        <transaction refno='123456789' trxStatus='response'>
            <request>
                <amount>400</amount>
                <currency>CHF</currency>
                <uppTransactionId>200504160029573476</uppTransactionId>
                <reqtype>COA</reqtype>
                <transtype>05</transtype>
                <closeTransaction>no</closeTransaction>
                <marketplace>
                    <subMerchantId>174322627</subMerchantId>
                    <fee>
                        <amount>80</amount>
                        <currency>CHF</currency>
                    </fee>
                </marketplace>
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>settlement succeeded</responseMessage>
            </response>
        </transaction>
    </body>
</paymentService>

Example Request for Sub-merchant 2

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<paymentService version="1">
<body merchantId="1000011011">
	<transaction refno="123456789">
		<request>
		<amount>600</amount>
		<currency>CHF</currency>
		<uppTransactionId>200504160029573476</uppTransactionId>
		<reqtype>COA</reqtype>
		<transtype>05</transtype>
		<closeTransaction>yes</closeTransaction>
		<marketplace>
			<subMerchantId>174322659</subMerchantId>
			<fee>
				<amount>120</amount>
				<currency>CHF</currency>
			</fee>
		</marketplace>
		</request>
	</transaction>
</body>
</paymentService>'
EOF

<?xml version='1.0' encoding='UTF-8'?>
<paymentService version='1'>
    <body merchantId='1000011011' status='accepted'>
        <transaction refno='123456789' trxStatus='response'>
            <request>
                <amount>600</amount>
                <currency>CHF</currency>
                <uppTransactionId>200504160029573476</uppTransactionId>
                <reqtype>COA</reqtype>
                <transtype>05</transtype>
                <closeTransaction>yes</closeTransaction>
                <marketplace>
                    <subMerchantId>174322659</subMerchantId>
                    <fee>
                        <amount>120</amount>
                        <currency>CHF</currency>
                    </fee>
                </marketplace>
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>partialDebit succeeded</responseMessage>
            </response>
        </transaction>
    </body>
</paymentService>

Credit / Refund

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<paymentService version="1">
<body merchantId="1000011011">
	<transaction refno="123456789">
				<request>
		<amount>600</amount>
		<currency>CHF</currency>
		<uppTransactionId>200504160029573476</uppTransactionId>
		<reqtype>COA</reqtype>
		<transtype>06</transtype>
		<marketplace>
			<subMerchantId>174322659</subMerchantId>
			<fee>
				<amount>120</amount>
				<currency>CHF</currency>
			</fee>
		</marketplace>
		</request>
	</transaction>
</body>
</paymentService>'
EOF

<?xml version='1.0' encoding='UTF-8'?>
<paymentService version='1'>
    <body merchantId='1000011011' status='accepted'>
        <transaction refno='123456789' trxStatus='response'>
            <request>
                <amount>600</amount>
                <currency>CHF</currency>
                <uppTransactionId>200504160029573476</uppTransactionId>
                <transtype>06</transtype>
                <marketplace>
                    <subMerchantId>174322659</subMerchantId>
                    <fee>
                        <amount>120</amount>
                        <currency>CHF</currency>
                    </fee>
                </marketplace>
                <reqtype>COA</reqtype>
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>credit succeeded</responseMessage>
                <uppTransactionId>200504162800157621</uppTransactionId>
                <authorizationCode>800187622</authorizationCode>
                <acqAuthorizationCode>162800</acqAuthorizationCode>
            </response>
        </transaction>
    </body>
</paymentService>

Updated about 4 years ago

What’s Next