Split Payments
In the Platform API scenarios, usually a payment is split between the platform merchant and the sub-merchant. This guide explains how to achieve it using the KOMOJU Platform API.
Impersonating the Sub-merchant via Dual Authentication
The split payment can take the full advantage of Dual Authentication. By using Dual Authentication the Platform merchant is essentially impersonating as a sub-merchant. This means that the transaction is performed as if the API was called by a sub-merchant.
In this scenario, the sub-merchant (the party indicated by the 2nd part of the Dual Authentication token) will be used as the "currently authenticated merchant", and consequently all merchant-related configurations are read from that sub-merchant. For example, the sub-merchant's Fraud Prevention rules will be used, instead of the platform merchant. For another example, the payment methods enabled for that sub-merchant (during the Onboarding Process) will be used, instead of the platform merchant.
The Two Parameters
Exactly two additional parameters are needed to make the payment in question a split one, i.e. platform_amount and platform_merchant.
Those are the only two necessary information to convey the desired payment-split arrangement.
The two parameters need to be supplied during a call to the POST /api/v1/payments API.
The platform_amount parameter
This parameter is an integer, and it plays together with the ordinary amount and currency parameters.
For an example, suppose that the ordinary amount and currency parameters were specified as 50000 and JPY, respectively.
In that case, we are instructing the KOMOJU system to create a JPY 50,000 transaction.
Now let us specify platform_amount as 5000.
In that case, we are further instructing the KOMOJU system to split a part of JPY 5,000 out of the JPY 50,000 transaction to the platform merchant.
The platform_merchant parameter
This parameter is a string, indicating the ID of the platform merchant to which the split part is routed.
Continuing with the example above, if we specify the platform_merchant paramter as somelongid,
then the merchant identified by the ID somelongid will act as the platform merchant that receives the 5000 JPY split.
The sub-merchant (the party indicated by the 2nd part of the Dual Authentication token) will receive the remaining 45,000 JPY.
However, in practice, the platform merchant will usually not receive exactly 5000 JPY due to the fees explained below. The sub-merchant, however, does not incur those fees and therefore will receive exactly 45000 JPY.
Transaction fee
Only the platform merchant is charged with the transaction fee, and not the sub-merchant.
Depending on the payment method, different transaction fee rates are applied.
Customer fee
Like the transaction fee, the customer fee applies also only to the platform merchant, and not the sub-merchant.
We charge a customer fee only for some payment methods, e.g. Konbini.
Refunding
Refunding happens according to the same split ratio that was specified when the payment was initially created. Continuing with the example above, the ratio is calculated as 5000/450000, i.e. 1/9.
Therefore, if a partial refunding happens, say, JPY 100. Then JPY 10 routes to the platform merchant, and JPY 90 routes to the sub-merchant.
If any fee was involved during refunding, they will ONLY be routed to the platform merchant, since the sub-merchant was never charged with any fee in the first place when the payment was captured.
Safety
For safety, proper permission checks are in place so that the sub-merchant being impersonated is guaranteed to be accessible by the platform merchant. The 1st part of the Dual Authentication token defines the platform merchant in question, which consequently defines the set of possible merchants that are accessible.
Platform merchant ID is a free parameter, in which the user has every freedom to reference an unrelated merchant not owned by her. However, this is not allowed. We do NOT allow the partaking merchants to be owned by different users.
Regarding the merchant with whom the payment is being split, the API caller is not allowed to specify the same merchant as the currently authenticated merchant. In other words, Splitting payments with oneself is not permitted.
Last but not least, we do NOT allow deactivated merchants or accounts to be specified as the partaking parties.