Configure the payin

Currently only one platform amount split is allowed per payin config or capture payin request. This can be used to charge a percentage rate and flat fee to the merchant in addition to merchant billing fees. This fee is deposited to the platform on a monthly basis, on the first business day of the month, in a platform fee deposit.

Defining the amount split

Rate and rate cap

The amount split rate and rate cap are optional fields. The rate and rate cap will both default to 0 if not provided in the amount split configuration.

When rate and rate cap are set, they can only be set to the values of:

Rate: >= 0% and <= 25%
Rate Cap: >= $0 and <= $100,000

Additionally, the following validation must be met:

If the rate is greater than 0%, then the rate cap must be greater than $0. For example, to bill a rate of 1% up to $100 set the rate cap value to 10000.
If the rate is 0%, then the rate cap must be $0.

Amount, currency code, and type

The amount, currency code, and type fields are required.

Amount: >= $0 and <= less than the payin amount
Currency Code: USD
Type: PLATFORM

You can utilize the rate, rate cap and amount fields to apply both a percentage and flat fee to the merchant.

Payin config request

The platform amount split can be configured on the create payin config request:

  {
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "amount_splits": [
+     {
+       "rate": 3000, // in per cent mille (1 PCM = 0.001%)
+       "rate_cap": 1000, // in minor units
+       "amount": 500, // in minor units
+       "currency_code": "USD",
+       "type": "PLATFORM"
+     }
+   ]
  }

In this example, the total amount split for this $100 payin would be $8 ($3 from the rate, $5 from the flat fee amount). This would result in $92 (minus billing fees) being deposited to the merchant and $8 being deposited to the platform.

To define only a rate, set the amount to $0:

  {
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "amount_splits": [
+     {
+       "rate": 3000, // in per cent mille (1 PCM = 0.001%)
+       "rate_cap": 1000, // in minor units
+       "amount": 0, // in minor units
+       "currency_code": "USD",
+       "type": "PLATFORM"
+     }
+   ]
  }

To define only a flat fee amount, omit the rate and rate cap fields.

  {
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "amount_splits": [
+     {
+       "amount": 500, // in minor units
+       "currency_code": "USD",
+       "type": "PLATFORM"
+     }
+   ]
  }

If no amount splits are provided, the total amount will be allocated to the specified merchant. Additionally, any remaining amount not specified by the amount splits will be allocated to the specified merchant

Auth and capture

When utilizing the two-step authorization and capture payment flow, you can define an amount split on capture payin. This will override the amount split configuration on the payin config..

Configure deposit report

When embedding the Deposit Report Component, you should display the amount split fee to your merchant by customizing the activity columns in the integrated Deposit Details Component.

See the activity column configuration of the deposit report component guide for details on how to customize the columns. The following column should be added:

{
    "name": "Platform Fees",
    "type": "builtin",
    "value": "split_remainder_amount"
}