Home > Guides

Guide Contents

Split Payments Management Guide v1.0

Added on:  06/07/17     Updated on:  03/21/24
Table of Contents

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).
Use Case
A merchant, who is a writer, wrote a book that was published by a publishing company called EveryBook. In addition to being a publishing company, EveryBook is also a marketplace that promotes the books of different writers sold through its platform in different ways. EveryBook sells the book of the abovementioned merchant for $100. As a publisher, EveryBook charges 30% of the price for every book sold. As an online platform, it additionally charges 10% of the price for every book sold via the platform. In total, EveryBook gets 40% of the cost from every purchase.

To promote its books Everybook cooperates with two groups of bloggers who advertise books in their blogs. The first group is bloggers who reward their readers for reposting on social media (through the ClickBank affiliate program); the second group is bloggers cooperating with web content writers who write articles with links to their posts. Thus, EveryBook has to pay $10 out of their own share to the blogger who facilitates a purchase of the book. The reposter/web content writer who promoted the book gets $5 out of this $10. As the result, upon the purchase, the funds should be distributed between several recipients: the merchant, EveryBook as a publisher and a marketplace, the blogger, and the reposter/web content writer (only on condition that the purchase was facilitated by them).

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:
For merchant 2000 and its account 2001, there is a split schema with a split schema code basicsplit1aff. If it is required to create another split schema for the same or a different account associated with this merchant, a split schema with another split schema code must be created, for example, basicsplit2aff. If there is an attempt to create a split schema with the same code, the system will automatically decline it, considering the new one to be a duplicate of the existing split schema and, therefore, not allowing it to be duplicated on any of the accounts of this merchant.

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:
A merchant sells a product for $100.00 and has agreed to split 20% of it to affiliate A and another 30% to affiliate B. The breakdown of the transaction would be as follows (excluding any processing fees):
  • The merchant would see a successful transaction for $100.00
  • The merchant would see a split-out of $20.00 (displayed as - $20.00) to affiliate A and a split-out of $30.00 (displayed as -$30.00) to affiliate B.
  • Affiliate A would receive a split-in transaction of $20.00 (displayed as + $20.00) from the merchant and affiliate B would receive a split-in transaction of $30.00 (displayed as + $30.00) from the merchant.

After that, a customer returns a product they have bought for $100. In the case of a refund the total amount of the original transaction is pulled from the merchant to refund the customer. The system would then attempt to pull funds that were split to any affiliate to reimburse the merchant for the affiliate’s portion of the refund as follows:
  • If the merchant needs to refund the $100.00 transaction from above the merchant would see a refund for $100.00. The merchant would also see a refund transaction from each of the affiliates displayed as pull-in transactions for + $20.00 and + $30.00 respectively.
  • Affiliate A and B would see pull-out transactions showing the amount withdrawn as - $20.00 and - $30.00 respectively.

Chargebacks and direct debit returns function the same way as refunds. In case when a void is done, split-in and split-out transaction gets voided with no pull-in/pull-out generated.


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:
A merchant processes a transaction for $100. As a result of a split scenario specified within a split schema, the affiliate should get $20. But the merchant owes $95 to the gateway, so the merchant should first transfer $95 to the gateway (merchant of record in action), and only after that, $5 to the affiliate. The remaining $15 is recorded to the split balance to be recovered in favor of the affiliate as soon as the merchant has sufficient funds in the account.

  • 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:
A merchant processes a transaction for $100. As a result of a split scenario specified within a split schema, $20 is transferred to the affiliate. After that, the credit transaction gets initiated. As a result, the gateway withdraws $100 from the merchant and transfers the amount to the cardholder without regard to the fact that $20 was previously transferred to the affiliate (merchant of record in action). But along with that, the system returns $20 to the merchant via a split-out transaction that withdraws $20 from the affiliate and transfers the amount back to the merchant via the split-in transaction (balance tracking in action).
  • 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:
A merchant, whose fees settings are configured as demand-demand, processes a transaction for $100. Out of this amount, $20 should be transferred to the affiliate. But in fact, the funds are transferred only when the remittance is done. After that, the credit transaction gets initiated. As a result, $100 is withdrawn from the merchant during the remittance process. Then, either of the following scenarios may take place:
a) If at the moment of the merchant’s remittance, the affiliate has not had the remittance done yet, the funds are withdrawn from the merchant. After that, during the subsequent affiliate’s remittance, the amount of the debt is withdrawn from the affiliate. If, during the subsequent affiliate’s remittance, it turns out that there are insufficient funds in the affiliate's account to pay back the merchant, the amount of the debt is recorded to the split balance. The debt is shown on the merchant statement to be subsequently recovered in favor of the merchant as soon as the affiliate has sufficient funds in the account.
b) If at the moment of the merchant’s remittance, the affiliate has already had its remittance done and it turns out that there are sufficient funds in the affiliate's account, these funds are transferred to the merchant. As a result, at the moment of the merchant’s remittance, the amount required for the credit is withdrawn from the merchant’s account. But by that time, the funds, owed by the affiliate should have already been transferred to the merchant.
c) If at the moment of the merchant’s remittance, the affiliate has already had the remittance done and it turns out that there are insufficient funds in the affiliate's account, the amount of the debt is recorded to the split balance and is shown on the merchant statement. As a result, at the moment of merchant’s remittance, the amount required for credit is withdrawn from the account, but the funds from the affiliate will be transferred to the merchant as soon as the affiliate has sufficient funds in the account.
  • 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:
A merchant processes a transaction for $100. Out of this amount, $20 has to be transferred to the affiliate. After some time, the cardholder decides to get a refund. As a result, a credit transaction is initiated. As soon as the credit has been processed, the split-out transaction for $20 is generated on the affiliate's side and the split-in transaction for $20 is generated on the merchant’s site. Then, either of the following scenarios may take place:

a) If at the moment of the affiliate’s remittance the affiliate has $20 in the account, this $20 is transferred to the merchant and is shown on the merchant statement as a split-out record for $20.
b) If at the moment of the affiliate’s remittance the affiliate has no funds in the account, then $20 is recorded to the affiliate’s split balance and is shown on the merchant statement as a debt for $20. A split-out record for $20 is created in order to be recovered in favor of the merchant as soon as the affiliate has sufficient funds on the account.
c) If at the moment of the affiliate’s remittance the affiliate has only $10 in the account (insufficient funds to cover the debt), the $10 debt amount is recorded to the affiliate's split balance and is shown on the merchant statement along with a split-out for $10. As a result, the existing $10 is withdrawn in favor of the merchant and the $10 debt amount will be recovered as soon as there are sufficient funds in the affiliate’s account and the remittance is done.
  • 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:
a) A merchant has received a payment for $100. As a result of a split scenario specified within a split schema, the transaction amount should be distributed between the Merchant and the affiliates (Affiliate A and Affiliate B) as $50/$25/$25. After the transaction has been processed, $5 is withdrawn from the $100 as a processing fee. The remaining $95 amount is distributed between the Merchant, Affiliate A and Affiliate B. Affiliate A gets $25, Affiliate B gets $25 and the Merchant gets $45 as he paid $5 to cover processing fees.
b) A merchant has received a payment for $100. As a result of a split scenario specified within a split schema, the transaction amount should be distributed between the Merchant and the affiliates (Affiliate A and Affiliate B) as $50/$25/$25. However, the Merchant has a $50 debt to the gateway. For this reason, after the transaction gets processed, $5 and $50 are withdrawn from the $100 as a processing fee and debt amount respectively. The remaining $45 amount is distributed between Affiliate A and Affiliate B. Affiliate A gets $25 and Affiliate B gets $20, which is $5 less than they are supposed to get. The remaining $5 amount is recorded to the split balance in favor of Affiliate B and shown as a record on the merchant statement.

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:

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:
Opening merchant balance Merchant Affiliate A Affiliate B Affiliate C Affiliate D Final merchant balance
Split-out Split-in
+$100 $30 $10 $5 $5 $30 $10 $5 $5 -$50

Credit/refund/chargeback/return transaction split:
Opening merchant balance Affiliate A Affiliate B Affiliate C Affiliate D Merchant Final merchant balance
Pull-out Pull-in
-$100 $30 $10 $5 $5 $30 $10 $5 $5 +$50

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:
https://[server-name]/gates/xurl?requestType=split-schema&userName=api-mypos&password=myP%40ssword&accountId=8001&description=split+for+everybook&splitSchemaCode=split1aff&splits=(accountId=2001;amount=R30000)(accountId=3001;amount=R10000)(accountId=4001;amount=R5000)(accountId=5001;amount=R5000)
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.
responseType=split-schema&splitSchemaId=112
3.1 To process a sale transaction with a predefined split schema, the API request will look similar to the one below:
https://[server-name]/gates/xurl?requestType=sale&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=100000&transactionIndustryType=RE&splitSchemaId=112

3.2. To process a sale transaction with embedded split rules, the API request will look similar to the one below:
https://[server-name]/gates/xurl?requestType=sale&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=50000&transactionIndustryType=RE&splits=(accountId=2001;amount=r30000)(accountId=3001;amount=R10000)(accountId=4001;amount=R5000)(accountId=5001;amount=R5000)
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:
Affiliate C: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate C is recorded to the split balance

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:
https://[server-name]/gates/xurl?requestType=credit&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=100000&transactionIndustryType=RE&splitSchemaId=112
2. To process a credit transaction with the embedded split rules, the API request will look similar to the one below:
https://[server-name]/gates/xurl?requestType=credit&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=50000&transactionIndustryType=RE&splits=(accountId=2001;amount=r30000)(accountId=3001;amount=R10000)(accountId=4001;amount=R5000)(accountId=5001;amount=R5000)

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:
Affiliate C: -3 is recorded to the split balance in favor of Merchant
Merchant: +3 from Affiliate C is recorded to the split balance
  • If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:
Affiliate C: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate C is recorded to the split balance


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:
Affiliate C: -4 is recorded to the split balance in favor of Merchant
Merchant: +4 from Affiliate C is recorded to the split balance
  • If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:
Affiliate C: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate C is recorded to the split balance

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:
Affiliate C: -4 is recorded to the split balance in favor of Merchant
Merchant: +4 from Affiliate C is recorded to the split balance
  • If Affiliate C does not have funds available to pay back to the merchant, the split balance will look as follows:
Affiliate C: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate C is recorded to the split balance

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:
responseType=split-schema&splitSchemaId=432 responseType=split-schema&splitSchemaId=433
3. 1 To process a sale transaction with items and the predefined split schemas, the API request will look similar to the one below:
https://[server-name]/gates/xurl?requestType=sale&userName=MerchantA&password=myP%40ssword&accountId=8001&accountType=R&accountNumber= 4111111111111111&accountAccessory=0422&holderType=P&csc=123&amount=200000&transactionIndustryType=RE&items=(code=001;description=book1;quantity=1;totalAmount=100000;splitSchemaId=432)(code=002;description=book2;quantity=1;totalAmount=100000;splitSchemaId=433)
3.2 To process a sale transaction with items and the embedded split rules, the API request will look similar to the one below:
requestType=sale&userName=myUsername&password=myP%40ssword&accountId=2001&accountType=R&accountNumber= 4111111111111111&accountAccessory=0422&holderType=P&csc=123&amount=200000&transactionIndustryType=RE&items=(code=001;description=book1;quantity=1;totalAmount=100000;splits=(accountId=2001;amount=R30000)(accountId=3001;amount=R10000)(accountId=4001;amount=R5000)(accountId=6001;amount=R5000))(code=002;description=book2;quantity=1;totalAmount=100000;splits=(accountId=2001;amount=R30000)(accountId=3001;amount=R10000))

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:
Affiliate F: -4 is recorded to the split balance in favor of Merchant
Merchant: +4 from Affiliate F is recorded to the split balance

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:
https://[server-name]/gates/xurl?requestType=void&userName=myUsername&password=myP%40ssword&accountId=2001&amount=100000&transactionId=S10001&items=(itemId=I123)
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:
Affiliate F: -4 is recorded to the split balance in favor of Merchant
Merchant: +4 from Affiliate F is recorded to the split balance
  • If Affiliate F does not have funds available to pay back to the merchant, the split balance will look as follows:
Affiliate C: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate F is recorded to the split balance

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:
https://[server-name]/gates/xurl?requestType=credit&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=100000&transactionIndustryType=RE&items=(code=001;description=book1;quantity=1;totalAmount=100000;splitSchemaId=432)(code=002;description=book2;quantity=1;totalAmount=100000;splitSchemaId=433)
2. To process a credit transaction with the embedded split rules, the API request will look similar to the one below:
https://[server-name]/gates/xurl?requestType=credit&userName=api-mypos&password=myP%40ssword&accountId=8001&accountType=R&accountNumber=4111111111111111&accountAccessory= 0422&holderType=P&csc=123&amount=200000&transactionIndustryType=RE&items= (code=001;description=book;quantity=1;totalAmount=100000;splits=(accountId=2001;amount=R30000)(accountId=3001;amount=R10000)(accountId=4001;amount=R5000)(accountId=6001;amount=R5000))(code=002;description=book;quantity=1;totalAmount=100000;splits=(accountId=2001;amount=R30000)(accountId=3001;amount=R10000))

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:
Affiliate F: -5 is recorded to the split balance in favor of Merchant
Merchant: +5 from Affiliate F is recorded to the split balance
  • If Affiliate F does not have funds available to pay back to the merchant, the split balance will look as follows:
Affiliate F: -10 is recorded to the split balance in favor of Merchant
Merchant: +10 from Affiliate F is recorded to the split balance