The developer.datatrans.com Developer Hub

Welcome to the developer.datatrans.com developer hub. You'll find comprehensive guides and documentation to help you start working with developer.datatrans.com as quickly as possible, as well as support if you get stuck. Let's jump right in!

Marketplace Payments

With our marketplace integration, you can start splitting payouts from a single transaction with multiple sub-merchants. Additionally, you can also add your marketplace commissions which will be deducted from every transaction. Your transactions are fully compliant with financial regulatory standards and you remain out of the funds flow. We currently support Mastercard, Visa, Apple Pay, Google Pay, Twint, and SEPA Direct Debit transactions within our marketplace integration.

Interested in our Marketplace solution? Get in touch!

Our Marketplace solution was recently released. Get in touch with us today if you are interested in joining our beta. Send us a message anytime by using this link and we'll get back to you.

Process Overview

A marketplace transaction initially follows the same behavior as any other integration: You create an authorization with deferred settlement, which involves goods from several vendors. This authorization can be done via a customer-initiated payment or merchant-initiated payment flow, with or without 3D Secure, depending on your acquiring agreement or the type of transaction. Once the authorization has been successfully completed, you can continue with the marketplace settlement requests, where you will define which share of the transaction a sub-merchant or your marketplace account will receive.

For that, we work with so-called splits. Each split will define what share of the transaction has to be transferred to a sub-merchant or your marketplace balance. An example could be a multi-basket transaction of 10.00 CHF split into three sub-merchants, the first split amounting to CHF 5.00, another CHF 3.00, and the last one CHF 2.00. A split may also contain an optional marketplace commission, that will allow you to deduct a specific amount of that split and add it to your account.

Collectors & Acquiring Setups

Before you can start splitting payouts, you will have to sign an agreement with a collector. The available collectors, acquirers, and payment methods will depend on your marketplace requirements. You have the option to either use the collector's acquiring agreement or can link your own acquiring agreement. Please get in touch so we can advise you what setup is more adequate for your project's needs.

Adding Sub-merchants

Each seller needs to be onboarded by the marketplace owner and will be verified by the collector - involving their own KYC and AML requirements. Once a sub-merchant has been registered, a new subMerchantId will be provided. Store these IDs to process your settlement requests. Please be aware that the onboarding process of new sub-merchants is performed by your collector and payouts will be blocked until the KYC and AML process has been completed. Depending on your collector's requirements, the sub-merchant will have to upload various documents to allow the onboarding to be completed.

Payouts

Payouts to your sub-merchants' accounts and to your marketplace account are processed at least twice a month and happen automatically. Upon request, the payout frequency can be increased.

Settlement Splits

For settlement requests to work, you need to process your authorizations with a deferred settlement ("autoSettle":false). After a transaction has been authorized, you can start sending your settlement requests together with your splits. Below is an example of a settlement request payload that can be sent to our settle API. The following account flows would result:

  • The cardholder's account would be debited 10.00 CHF.
  • The first sub-merchant 133701 would be credited 4.00 CHF.
  • The second sub-merchant 133702 would be credited 2.50 CHF.
  • The third sub-merchant 133703 would be credited 2.00 CHF.
  • Your marketplace account would be credited 1.50 CHF.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/settle' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"amount": 1000,
	"refno": "Test-1234-settled"
	"marketplace" : {
		"splits" : [ {
			"subMerchantId": 133701,
			"amount": 500,
			"commission": 100
		},
		{
			"subMerchantId": 133702,
			"amount": 300,
			"commission": 50
		},
		{
			"subMerchantId": 133703,
			"amount": 200
		} ]
	}
}'

The following rules apply for settlements:

  • Partial settlements are allowed, however, we only accept one settlement per transaction.
  • The transaction amount has to match the sum of all splits amounts.
  • The amount of any split has to be greater than 0.
  • Your marketplace commission - deducted from the split amount and paid out to your marketplace account - is optional. It may never be higher than the split amount.
  • Only one split per sub-merchant is allowed.

Refund Splits

Once a settlement has been completed, you may also perform refunds if needed. Below is an example of a refund request payload that can be sent to credit API. The following account flows would result:

  • The cardholder's account would be credited 5.00 CHF.
  • The first sub-merchant 133701 would be debited 2.00 CHF.
  • The second sub-merchant 133702 would be debited 2.00 CHF.
  • Your marketplace account would be debited 1.00 CHF.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/settle' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"amount": 500,
	"refno": "Test-1234-refund"
	"marketplace" : {
		"splits" : [ {
			"subMerchantId": 133701,
			"amount": 300,
			"commission": 100
		},
		{
			"subMerchantId": 133702,
			"amount": 200
		} ]
	}
}'

The following rules apply for refunds:

  • Multiple partial refunds are allowed. We block refunds once the sub-merchant's or marketplace balances are at 0 (amount or split.amount).
  • The transaction amount has to match the sum of all split amounts.
  • The amount of any split has to be greater than 0 but not higher than the available balance.
  • Your marketplace commission - deducted from the split amount and taken from your marketplace account - is optional. It may never be higher than the split amount.
  • Only one split per sub-merchant is allowed.

Updated 7 days ago

Marketplace Payments


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.