Introduction

The purpose of this guide is to explain split payments logic, its concept, and the way it works within the system.

Intended Audience

This guide will be useful for the PSPs, software platforms, marketplaces or merchants who need to implement split payments functionality within their system.

Overview

In today's world, there are many software platforms that are customer-oriented, including, for example, POS platforms and fitness center platforms. An important part of these software platforms is used to accept card present transactions and settle payment obligations between a business and its customers. In the past, merchants worked directly with their customers making their profit and paying processing fee to software platforms while these platforms assisted them in doing business, taking no part in the merchant-customer relationship.
But in the era of globalization, market development and social media marketing, the world is much more interconnected and interdependent. As a result, a new generation of software platforms has appeared – marketplaces, which not just aggregate merchants but also serve as platforms for the interaction between merchants and customers. Because of this interaction, new players in the transaction processing arena have emerged and the process of settling payment obligations has become much more complicated. This has created a need for a new mechanism to settle payment obligations between the parties. This is called the split payments mechanism.

Real World Context

In the real world, the split payments is the mechanism that distributes funds between several recipients – the merchant, the marketplace, and the affiliates.
A merchant is a company or person selling products or services to customers. It is the main recipient of funds received as the result of a payment and is the one that shares its profit with the partners. In the gateway, a merchant is represented as a separate entity. As merchants are the actual recipients of funds, they undergo an onboarding procedure and need to have fees and processor-profile settings configured. After created within the gateway, a PSP can assign any fee type to the merchant.
A marketplace is a software platform that allows its users - merchants and customers - to exchange their products and services and makes profit from merchants for providing its services. Airbnb, Amazon and Uber are examples of present-day marketplaces. In the gateway, this entity is represented as an affiliate.
An affiliate is a company or person that is a partner of a merchant or marketplace. It makes profit from merchants and marketplaces by promoting their products and services. To advertise products, affiliates can use blogs, portals, websites, coupons and other means. In the gateway, this entity is represented as an affiliate similar to a marketplace. The followimg rules must be followed when creating affiliates:

• affiliates are not merchants, but their partners, which are not primary recipients of funds. For this reason, they do not have to undergo the onboarding procedure as well as have fees and a provider profile configured;
• as an affiliate is not a business in the same context as a merchant is, it cannot have multiple locations. For this reason, the affiliate must be always created with a singular merchant profile;
• after created within the gateway, the affiliate is automatically assigned with the cycle-cycle fee type.

Basically, the split payments mechanism helps a merchant share its revenue with its partners in cases of a successful sale and get the funds back in case of a successful money return (credit, void, chargeback, etc).

Gateway Context

In the gateway, the split payments mechanism is the part of the remittance mechanism responsible for funds distribution between a merchant and its affiliates according to particular split rules. These rules can be specified within a transaction either as embedded or predefined split schema. Transactions with split payments can be created via API only. These transactions may either include items or not.
The gateway does not limit the number of items in a transaction.
An item is a purchased product or service that may be the basis for a transaction split and further funds distribution. An item plays either an informational or functional role. When an item plays an informational role, the transaction can include one or more items and the split payment scenario will not be affected. When an item plays a functional role, the transaction can include one or more items and each item specified in the transaction serves as the basis for the split payment scenario.

The split payments mechanism involves two phases: transaction processing and remittance.

Transaction Processing

During the transaction processing, a real-time (credit card/direct debit) or batch transaction is made. The amount of the transaction is distributed between the recipients based on the split rules. All the amounts intended for the recipients are recorded and split-in/split-out transactions are generated.
Split rules are the rules that control how funds should be distributed between recipients. When the split rules are embedded, they are only available for real-time API transactions. When the split rules are set as a predefined split schema, they are available for both real-time and batch transactions and should be created in advance of use.
A predefined split schema is a split rules template that sets the scenario for funds distribution between the transaction participants. The template can only be created via the API and is primarily used in situations when the same split rules are repeatedly used or batch processing is required.
In the gateway, each split schema has a particular identifier that can be either internal or external. The internal identifier is a unique value that is assigned by the system and submitted via the split schema id field in API or the user interface. The external identifier is an identifier submitted via a split schema code, a code that is assigned by a submitter within the system. To learn more about the differences between internal and external identifiers and the ways of submission, review this link
When creating a split schema within the gateway, the split schema code should be assigned following these rules: 1) The value is required to be assigned specifically within the context of the account. 2) The value is required to be unique at merchant level.

To see these two rules in action review the following example:

To keep a record of the flow of split payments between merchants and affiliates the following transaction types are used:

For sale transactions: A split-in transaction - is a transaction generated in the context of the split payments functionality based on a sale transaction, which creates a record that an affiliate has received the commissions as a part of the original sale transaction processed by a merchant. On the user interface, a split-in transaction is always displayed with “+” symbol.
A split-out transaction - is a transaction generated in the context of the split payments functionality based on a sale transaction, which creates a record that a merchant, that processed the original transaction, has transferred the commissions to an affiliate. On the user interface, a split-out transaction is always displayed with “-” symbol.

For credit/refund/chargeback/return transactions: A pull-in transaction - is a transaction generated in the context of the split payments functionality based on the credit/refund/chargeback/return of the original transaction and creates a record that the merchant has received the commissions, previously charged via split-in, from the affiliate.
A pull-out transaction - is a transaction generated in the context of the split payments functionality based on the credit/refund/chargeback/return of the original transaction and creates a record that the affiliate has transferred the commissions, previously charged via split-out, to the merchant.

These transactions are always generated in pairs each type of a transaction. They exist as records in the system and do not influence the authorized amount is withdrawn from the card holder’s account and transferred to merchant’s account. The general practice is to do this at the end of the business day. There are two possible settlement mechanisms commonly referred to as terminal capture and host capture: When terminal capture is used, the information about each transaction to include in settlement has to be supplied at the settlement time (generally through a settlement file). When host capture is used, the underlying processing system (the host) keeps track of all of the transactions and it is usually sufficient to simply send a settlement message without including transaction details. " >settlement process that occurs on the processor side. In other words, the processor processes only the information submitted within the original transaction with no splits.
To show how split-in/split-out and pull-in/pull-out transactions actually work, let's review the most common use case:

Remittance

During the remittance phase, the funds are transferred to the recipients. The process is based on the balance tracking mechanism that is part of the remittance mechanism.

Balance tracking keeps a record of merchants’ and affiliates’ debts and is activated only after the system calculates the amount processed by the merchant. The merchant who has processed the transaction is the one who is financially responsible for all the calculations with the gateway - fees, commissions, refunds, chargebacks, returns. This merchant is referred to as the merchant of record.
The process of the transaction splitting and further balance tracking works as it is shown in the diagrams below for sale and credit transactions respectively. When the funds actually enter the system, they belong to the merchant and are automatically transferred to the affiliates under the condition that it is authorized by the merchant. When it is required to return the funds, then a total transaction amount is primarily withdrawn from the merchant regardless of whether the affiliates have sufficient funds in the account or not. After that, the system attempts to withdraw the funds from the affiliates in favor of the merchant. To learn basic principles of funds distribution priority within the gateway, see Funds Distribution Priority section of Remittance Management Guide.

Sale transaction split

Credit/refund/chargeback/return transaction split
To see how balance tracking and merchant of record work together in the gateway, review the use cases below:

• If a merchant has a debt against the gateway, the merchant is required to settle the debt primarily with the gateway notwithstanding that it owes money to an affiliate. If after settling the debt with the gateway, the merchant does not have sufficient funds to settle the debt with the affiliate, the debt is recorded to the split balance to be withdrawn from the merchant as soon as funds are available. To understand how this principle works, let’s review the following example:

• If a merchant processes a transaction and part of the transaction amount is transferred to its affiliate, then the transaction is credited to the cardholder, the total transaction amount is withdrawn from the merchant. Additionally, the system helps the merchant return the funds via pull-in/pull-out transactions that withdraw the funds from the affiliates and transfer them to the merchant. To understand how this principle works within the system, let’s review the following example:

• If a merchant processes a transaction and part of the transaction amount is transferred to its affiliate and then the transaction is credited to the cardholder, the total transaction amount is withdrawn from the merchant, and depending on the timing of the merchant’s and affiliate’s remittance, the system withdraws the funds from the affiliate and transfers them to the merchant. Therefore, for the full remittance cycle to occur, the remittance (which frequency depends on the merchant fee settings) should occur for both the merchant and the affiliate. To understand how this principle works within the system, let’s review the following example:

• If a merchant needs to return funds to a cardholder, a credit transaction is initiated. As soon as the credit has been processed, the split-out transaction is generated on the affiliate's side, and the split-in transaction is generated on the merchant’s side. If at the moment of the affiliate's remittance, it turns out that the affiliate has sufficient funds in the account, these funds are transferred to the merchant. And if it is found that there are insufficient funds or even no funds to cover the split-out transaction that has been generated, then the amount of the debt is recorded to the split balance and is shown as a record on the merchant statement. To understand how this principle works within the system, let’s review the following example:

• As soon as a merchant processes a transaction, the system first withdraws fees and debts for returns and chargebacks, if there are any. Once the fees and debts are withdrawn, the affiliates of the merchant receive payouts. Having paid to the affiliates, the merchant receives the rest of the transaction amount. If after the fees and debts are withdrawn, the merchant has insufficient funds to pay to all the affiliates, one or more affiliates (which depends on the debt amount) gets less than they are supposed to, or nothing. If the merchant is not able to send payouts to its affiliates, the debt amount is recorded to the merchant’s split balance and shown as a record in the statement. The debt amount will be covered once the merchant has money in its account from future transactions - as soon as the merchant has sufficient funds to send payouts.

To understand how this works, let’s review the following two examples:

Operations with Split Payments on the User Interface

For operations with split payments on the user interface there are available the following forms:

The Transactions form allows to review the original transaction that was split and the split-in/split-out transactions associated with it. This form is available at the following places:

• Perspective => Console Perspective => Transactions
• Perspective => Management => Merchant Perspective => Processing => Transactions
• Perspective => Administration => Monitoring Perspective => Transactions

The Statements form allows to review the merchant statements of a merchant and affiliates that include a summary of the amount that was received/withdrawn as a result of split-in/out transactions. This form is available at the following places:

• Perspective => Console Perspective => Statements
• Perspective => Management => Merchant Perspective => Remittance
• Perspective => Administration => Monitoring Perspective => Statements

The View Transaction form allows to review the detailed information about an original transaction that was split, the split-in/split-out transactions associated with it and the items that serve as the basis for the transaction split. This form is available at the following place:

• Perspective => Console Perspective => Transactions
• Perspective => Management => Merchant Perspective => Processing => Transactions
• Perspective => Administration => Monitoring Perspective => Transactions

The Split Schema form allows to review any unpaid balances that a merchant may carry with any of its affiliates (or vice versa). This form is available at the following place:

• Perspective => Management => Merchant Perspective => Remittance => Split Schema

The New Merchant form allows to create an affiliate that will receive funds as the result of split payments. This form is available at the following place:

• Perspective => Merchant Perspective => New Merchant
• Perspective => Merchant Perspective => New Merchant (Extended)
• Perspective => Merchant Perspective => New Affiliate (Onboarding)

The Balances form allows for reviewing the split balance specifying the current debt amounts between merchants and their affiliates. This form is available at the following places:

• Perspective => Console => Remittance=>Balances
• Perspective => Management => Merchant => Remittance => Balances

To learn how to manage split payments in the system, review these associated tutorials:

• Creating an affiliate
• How to review a split schema
• Reviewing split transactions
• How to review items

Use Cases

To see the split payments mechanism in action, we will review the use cases with the following participants present:
Merchant - a writer who sells their books;
Affiliate A - the publishing company EveryBook that publishes the books of Merchant А;
Affiliate B - the marketplace EveryBook that promotes the books of Merchant А;
Affiliate C - a blogger who promotes the books sold by EveryBook, gets paid for this and rewards their readers for reposting on social media;
Affiliate D - a reader who reposts the posts of Affiliate C;
Affiliate E - a blogger who promotes the books sold by EveryBook, gets paid for this and rewards web content writers who write articles with links to the blog;
Affiliate F - a web content writer who cooperates with Affiliate E.

To show all the use cases possible within the split payments, the use cases will describe the following scenarios of funds distribution:

• The scenario specifying the recipients with positive balance
• The scenario specifying that one of the affiliates does not have sufficient funds on the account to settle a debt owed to the merchant.
• The scenario specifying that one of the affiliates does not have funds to settle a debt owed to the merchant.

The scenarios below will include the following fixed amounts:

$100/100% - the cost of one book sold via the marketplace EveryBook;
$30/30% - a fee charged for every book sold by EveryBook as a publishing company; $20/20% - a fee charged for every book sold by EveryBook as a marketplace and via the blogger;
$10/10% - a fee charged by EveryBook to the blogger who facilitated the purchase (withdrawn from the amount charged by EveryBook as a marketplace);
$5/5% - a fee charged by the blogger to the reposter who facilitated the purchase (withdrawn from the amount charged by the blogger);
$5/5% - a fee charged by the blogger to the web content writer who facilitated the purchase(withdrawn from the amount charged by the blogger).

In the use cases, the payouts above are handled via the split-in/split-out and pull-in/pull-out transactions as it is shown in the tables below for sale and credit/refund/chargeback/return transactions respectively:
Sale transaction split:
Credit/refund/chargeback/return transaction split:

Purchase/Sale

A customer buys a merchant’s book following a repost in a social network that subsequently led them to the EveryBook marketplace. After the sale transaction is done, it is necessary to split funds between the merchant, the publishing company, the marketplace, the blogger and the reposter. In the gateway, this example is implemented through a sale transaction with a subsequent funds distribution between Merchant, Affiliate A, Affiliate B, Affiliate C and Affiliate D.
In the gateway, this scenario will look as follows:
1. A split schema specifying the payouts to Affiliate A, Affiliate B, Affiliate C, Affiliate D is created. To create a split schema, the API request will look similar to the one below: The step is optional for real-time transactions and required for batch transactions.
2. Once the API response is retrieved, the splitSchemaId field value should be extracted for further submission within the sale request. 3.1 To process a sale transaction with a predefined split schema, the API request will look similar to the one below:
3.2. To process a sale transaction with embedded split rules, the API request will look similar to the one below: After the remittance is done, the split balance will look as follows:

• If there are no debts between the merchant and affiliates, there will be no record in the split balance.
• If Affiliate C owes $5 to Merchant, the split balance will look as follows:

Purchase Return/Credit

A customer bought a book found via a repost in a social network but decided to return it. As a result of the credit operation, it is necessary to withdraw previously distributed funds from the merchant, the publishing company, the marketplace, the blogger and the reposter. In the gateway, this scenario is implemented through a sale transaction with a subsequent refund via credit transaction. Thus, the funds are withdrawn from all the affiliates (Affiliate A, Affiliate B, Affiliate C, and Affiliate D) and subsequently transferred to the Merchant.
In the gateway, this scenario will look as follows:

1. To process a credit transaction with a predefined split schema, the API request will look similar to the one below: 2. To process a credit transaction with the embedded split rules, the API request will look similar to the one below:

After the remittance is done, the split balance will look as follows:

• If there are no debts between the merchant and affiliates, there will be no record in the split balance.
• If Affiliate C has only $2 in the account, the split balance will look as follows:

• If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:

Unauthorized Purchase/Chargeback

A customer has not received the book they found via the blog and disputes charges to their credit card. After a chargeback is made, it is necessary to withdraw previously distributed funds from the merchant, the publishing company, the marketplace, the blogger, and the reposter. In the gateway, this scenario is implemented through a sale transaction with a subsequent dispute process (if chargeback dispute is supported for a particular merchant). Thus, the funds are withdrawn from Affiliate A, Affiliate B, Affiliate C and Affiliate D and subsequently transferred to Merchant.
In the gateway, this scenario will look as follows:

1. A sale transaction is generated and according to a split scenario, specified payouts go to Affiliate A, Affiliate B, Affiliate C and Affiliate D. 2. After the returns file with a chargeback is received, the system automatically issues a chargeback.

After the remittance is done, the split balance will look as follows:

• If there is no debts between the merchant and affiliates, there will be no record in the split balance.
• If Affiliate C has only $1 on the account, the split balance will look as follows:

• If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:

Failed Purchase/DD Return

A customer pays for a book found by following a repost in a social network via direct debit, but it turns out that there are insufficient funds in the customer’s account to buy the book. After the direct debit return is received, it is necessary to withdraw previously distributed funds from the merchant, the publishing company, the blogger, and the reposter in favor of the gateway. In the gateway, this scenario is implemented through a direct debit transaction and subsequent generation of the returns file. As the result, a transaction amount is withdrawn from all the affiliates (Affiliate A, Affiliate B, Affiliate C, and Affiliate D) and subsequently transferred to Merchant.

In the gateway, this scenario will look as follows:

1. A batch file with a specified split schema is submitted.
2. If the transaction is declined by the bank, the returns file with a declined transaction is received.

After the remittance is done, the split balance will look as follows:

• If the affiliates have positive balances, there will be no record in the split balance.
• If Affiliate C has only $1 in the account, the split balance will look as follows:

• If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:

Multi-item Purchase/Sale with Items

A customer has bought two books from the merchant. The first one was found via the article of a web content writer; the second one was found directly on the website of the marketplace. After the sale transaction is done, it is necessary to transfer funds from the first book purchase to the merchant, the publishing company, the marketplace, the blogger and the web content writer; funds from the second book purchase have to be distributed between the merchant, the publishing company and the marketplace. In the gateway, this scenario is implemented through a sale transaction with two items. Upon purchase of the book found via the link in the article (split scenario is tied to item 1), the funds are distributed between Merchant, Affiliate A, Affiliate B, Affiliate E and Affiliate F. And upon purchase of the book found on the website of the marketplace (split scenario is tied to the item 2), the funds are distributed between Merchant, Affiliate A and Affiliate B.

In the gateway, this scenario will look as follows:

1. Two different split schemas specifying the payouts to Affiliate A, Affiliate B, Affiliate E and Affiliate F for book/item1 and to Affiliate A and Affiliate B for book/item2 are created.
2. Once the responses are retrieved, the splitSchemaId field value should be extracted for further submission within the sale request:
3. 1 To process a sale transaction with items and the predefined split schemas, the API request will look similar to the one below:
3.2 To process a sale transaction with items and the embedded split rules, the API request will look similar to the one below:
After the remittance is done, the split balance will look as follows:

• If the affiliates have positive balances, there will be no record in the split balance.
• If Affiliate F owes $4 to the merchant, the split balance will look as follows:

Partial Purchase Return/Partial Void

A customer has bought two books from the merchant but decides to return the first book right after the purchase is made. As a result of the void operation, it is necessary to return the amount paid for the first book, that was previously distributed between the merchant, the publishing company, the marketplace, the blogger, and the web content writer. In the gateway, this process is implemented through a sale transaction with two items and subsequent partial void made for Item 1. As a result, the funds are withdrawn from Affiliate A, Affiliate B, Affiliate E, and Affiliate F (split scenario is tied to the Item 1) and subsequently transferred to Merchant.

1. To return the funds paid for the Item1, a void request for Merchant should include an itemId returned in the initial sale response:
2. After a void transaction has been processed, void is generated for previuosly created split-in and split-out transactions.

After the remittance is done, the split balance will look as follows:

• If the affiliates have positive balances, there will be no record in the split balance.
• If Affiliate F has only $1 in the account, the split balance will look as follows:

• If Affiliate F does not have funds available to pay back to the merchant, the split balance will look as follows:

Total Purchase Return/Credit

A customer has bought two books from the merchant but decided to return both books 7 days after the purchase is made. After the credit transaction is done, it is necessary to return the total amount paid for both books that was previously distributed between the merchant, the publishing company, the marketplace, the blogger and the web content writer for the first book and between the merchant, the publishing company and the marketplace for the second book. In the gateway, this scenario is implemented through a sale transaction with two items and subsequent refund via a credit transaction with two items. As a result, upon the return of item 1, the funds are withdrawn from Affiliate A, Affiliate B, Affiliate E and Affiliate F (split scenario is tied to the item 1) and subsequently transferred to Merchant. And, upon the return of item 2, the funds are withdrawn from Affiliate A and Affiliate B (split scenario is tied to the item 2) and subsequently transferred to Merchant.
In the gateway, this scenario will look as follows:

1. To process a credit transaction with two previously created predefined split schemas, the API request will look similar to the one below:
2. To process a credit transaction with the embedded split rules, the API request will look similar to the one below:
After the remittance is done, the split balance will look as follows:

• If the affiliates have positive balances, there will be no record in the split balance.
• If Affiliate F has only $5 in the account, the split balance will look as follows:

• If Affiliate F does not have funds available to pay back to the merchant, the split balance will look as follows: