Split payments

Last changes: 05-30-2022

Split payments and payment distribution

SmartPay split payment feature allows the distribution of one consumer payment towards multiple merchant accounts.

Two models are supported: marketplace model and reseller model.

Marketplace model

Description

Marketplace model is used by marketplace setups, characterized by having a marketplace operator who assumes ownership of a marketplace and merchants who sell goods and services on this marketplace. The end consumer would purchase goods and service from a merchant on the marketplace. The marketplace operator acts as an intermediary. typically providing shop infrastructure and general payment integration.

SmartPay supports those models by opening merchant clearing accounts, used as transition accounts and merchant accounts for marketplace operator and onboarded merchants. The end consumer payment is authorized and captured towards the transition account as deposit transaction. Based on the provided payment split, this deposit transaction is shared between multiple merchant accounts, as instructed by the marketplace platform.

Sample use-case

OEM offers a marketplace, on which different vendors/merchants are onboarded to sell goods and services towards end consumers. Each transaction on the marketplace consists of a share for the marketplace operator (e.g., service fee) and for the merchant selling. So, the end consumer payment will be split and credited and paid out to marketplace operator and involved merchant.

Reseller model

Description

This model is used for reselling or revenue share business cases. Those cases are characterized by having

Marketplace operator who assumes ownership of the marketplace as well as the consumer relation
One or more sub-providers onboarded to the marketplace as merchant.

The end consumer purchases goods and services from the "primary merchant" (marketplace operator or other onboarded merchant), whereby the "primary merchant" is purchasing the goods and services from sub-providers / merchants at the marketplace.

For revenue share case, the primary merchant may transfer a share of the transaction as kickback to the sub-merchant.

Sample use-case

OEM setup an online marketplace to sell digital licenses directly to end consumer. As OEM decided to sell directly to end consumer, the end consumer has a direct contractual relationship with the OEM only.

In this scenario, the consumer was convinced by an independent dealership to purchase the license online. To incentivize dealers to push license sales and to compensate for the effort, OEM decides to pay dealership a kickback for each arranged license sale.

So, the consumer pays the full amount to the OEM account and selects his dealership on checkout. Based on this information, the marketplace system calculates the kickback for the dealer and instructs SmartPay to forward the funds to the merchant account of the dealership.

Integration journey

General considerations

Split payment functionality is seamlessly integrated towards the SmartPay integration journey. You simply need to add the payment split object to our existing APIs.

paymentSplit

"paymentSplit": {
       "paymentSplitDestinations": [
           {
               "destinationReference": "destinationMerchantAccountAlias_1",
               "currencyCode": "EUR",
               "amount": 50.99,
               "description": "SMP-Split-Transaction-1",
           },
           {
               "destinationReference": "destinationMerchantAccountAlias_2",
               "currencyCode": "EUR",
               "amount": 50.99,
               "description": "SMP-Split-Transaction-2",
           }
       ]
   },

This object consists of a paymentSplitDestinations array holding the accounts and information for the split:

destinationReference: identifier of the target account for the split
currencyCode: Currency of split amount
amount: Amount to be credited to the destinationReference account
description: Description of the split transaction, will be shown on the destinationReference account statement

Further details can be found in our data model.

Please note following considerations / limitations:

Your system needs to calculate the split and allocate it to the splitDestinations.
Only one split to unlimited target destinations per SmartPay transaction allowed and only until the total transaction amount is reached. Split of previously split-transactions or "partial" splits are not supported.
For marketplace model, the transition account must have zero balance after split execution. Make sure to split the entire amount. SmartPay will validate this requirement and reject incomplete split transactions.
For reseller model, the total amount split to destinations can be less or equal the total transaction amount.
Currency conversion within the split is not supported.

paymentSplitResults

{
            "modificationData": {
                "type": "CAPTURE",
                "modificationId": "CPT-jIrMCqHUOd",
                "reconciliationReferenceId": "JnNWK4sbXEbr7JiLYnhVO",
                "paymentSplitResults": [
                    {
                        "destinationReference": "destinationMerchantAccountAlias_1",
                        "description": "SMP-Split-Transaction-1",
                        "amount": 50.99,
                        "currencyCode": "EUR",
                        "status": "Success",
                        "reconciliationReferenceId": "NKYIgeCAphaNycREqQ0w1"
                    },
                    {
                        "destinationReference": "destinationMerchantAccountAlias_2",
                        "description": "SMP-Split-Transaction-2",
                        "amount": 50.99,
                        "currencyCode": "EUR",
                        "status": "Success",
                        "reconciliationReferenceId": "j7reNq9fgM4GOXPI2sQA7"
                    }
                ]
            },
            "modificationAmount": {
                "amount": 101,98,
                "currencyCode": "EUR"
            },
            "status": "CAPTURED",
            "creationDate": "2022-05-19T13:56:40.580Z",
            "lastStatusDate": "2022-05-19T13:56:42.068Z",
            "statusHistory": [
                {
                    "status": "CAPTURE_PENDING",
                    "statusDate": "2022-05-19T13:56:40.580Z",
                    "modificationAmount": {
                        "amount": 101,98,
                        "currencyCode": "EUR"
                    }
                },
                {
                    "status": "CAPTURED",
                    "statusDate": "2022-05-19T13:56:42.068Z",
                    "modificationAmount": {
                        "amount": 101,98,
                        "currencyCode": "EUR"
                    }
                }
            ]
        },

Our API response model has been enhanced with a paymentSplitResults object within each modificationData object. It is designed to provided you information on split results in the context of the respective modification.

For each modification which included a payment split (split creation / split refund), you'll receive the paymentSplitResults object with:

destinationReference: identifier of the target account for the split, as in the request "paymentSplit" object
description: Description of the split transaction, will be shown on the "destinationReference" account statement
amount / currencyCode: Amount and currency of the share of split to desination, as in the request paymentSplit object
status: Status of split execution
reconciliationReferenceId: Financial transaction ID on merchant account of the split receiver, to recognize transaction on account statement or merchant panel

Initial setup

Please discuss the split scenario with your rollout manager. Your rollout manager will help you with the selection of the appropriate split payment model and organizes the setup of all required accounts and configurations in SmartPay. Hereby, the destination reference can be created according to your requirements / as the merchant might be already referenced in your system.

Create split payment

You have three options to request a split payment. For all options it is assumed, that you've integrated SmartPay according to integration journey and/or integration journey MIT and completed the initial setup. Furthermore, you need to ensure that your system can calculate the split and to allocate it to the correct "destinationReference".

Create Checkout API: To request a payment split at Create Checkout API, simply provide the paymentSplit object in create checkout API body.
capture API: If the payment split is not known at create checkout step, you may provide the paymentSplit object in capture API request. To use this process, make sure to a) disable auto-capture and b) to not submit the split already in create checkout API, as a transaction can only be split once.
Create MIT Transaction API: Split payment works for MIT transaction by providing the paymentSplit object in the body of create MIT Transaction API.

Cancel split payment

Sometimes, there might be a need to stop transaction processing by cancelling a transaction.

SmartPay offers the modification APIs cancel and cancelOrRefund. Both APIs will always perform a full-chain cancel / full-chain refund, meaning the entire transaction including split will be reversed. It is not required to provide the paymentSplit inside this API calls.

Refund split payment

SmartPay can handle refund of split payment transactions flexibly by providing you the general option to:

Refund the full amount
Refund partial amounts up to the initial transaction amount

On top of this, you are requested to provide a split for the refund as well. SmartPay then uses the provided split to debit funds form the different destinations to perform the refund. With this you may achieve the following scenarios

Scenario	Details	Action
Full-chain full refund	Refund the full transaction amount based on the initial split. Hereby funds to cover the refund are taken from each merchant account, as per the initial split.	Call refund API with same paymentSplit as in payment transaction provided.
Full-chain partial refund from responsible merchant account (Refund debited from merchant account up to initial split amount)	Refund one or more partial transaction amount, whereby funds to cover are taken from each merchant account, as per the initial split. Like partial refund, unlimited amount of partial refunds can be created, until the full original transaction amount has been reached.	Calculate the paymentSplit for the partial refund (e.g., partial refund due to a return of one item, where only item from merchant 1 was returned) Call refund API with paymentSplit provided.
(Partial) refund from responsible merchant account (Refund debited from merchant account exceed initial split amount)	Some use-cases might require special refund processes, to accommodate those, one or more merchants might cover the entire refund (e.g., in scenarios where the merchant delivered the service, but marketplace had issues in delivery - so that now marketplace takes the full refund).	Calculate total refund amount. Call refund API with paymentSplit provided. paymentSplit should only contain destinationReference of the merchant(s) who cover this refund.

Please note:

Align your refund requirements with your rollout manager to ensure that refunds can be covered by respective account balances. Some scenarios may require rolling reserve or direct debit mandate to top-up the account.
In marketplace model the full refund amount need to be debited from the different merchant accounts to keep transition account at zero balance. Requests where split is less then refund amount will fail.
In reseller model is the difference between refund amount and provided paymentSplit taken from the primary merchant account.

Previous

Next