Creating a payment split

Qualy lets you to split the payout of a Payment Intent to multiple beneficiaries. That means, when a contact pays a Payment Intent, the money can be sent to multiple bank accounts. Using the Payment Split API, you can specify how much to send and to whom.

Before you start

You need to have a Payment Intent _id to create a Payment Split, follow this guide to create a Payment Intent.

Creating a payment split

To create a payment split on Qualy, you will have to use the Payment Splits API.

When you create the Payment Split, you can specify options like the amount, partnership, and more:

try {
  const response = await fetch('https://api.qualyhq.com/v1/payment-splits/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "type": "percentage-on-amount",
      "currency": "AUD",
      "amount": 3000,
      "partnership": "63a87a04ab1d29a82b52da9d",
      "item": "661e9bc0e0eb901d6b2f2682",
      "contact": "65d4bda07d46a66920967c39",
      "split": "63fdfda0c7ca4bb64baa50a3",
      "dueAt": "2024-08-20T17:39:31.219Z",
      "tax": "63d8f17ad1544ab1b4d6ef47",
      "percentage": 0.3,
      "paymentIntent": "661e9bbfe0eb901d6b2f2670"
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

All Payment Splits are associated with a Payment Item

When creating a Payment Split you will need the Payment Intent _id and the Payment Item _id for which the Payment Split should be associated with. Use the property item to do that.

Types

Payment splits can have different types. The type property helps customers in their reporting and analytics activities, and it's uses by Qualy when calculating and handling payouts. Make sure to select the correct type when creating a payment split.

Type	Description
`percentage-on-amount`	Choose this type when the `amount` and `percentage` fields of the Payment Split are being calculated based on the `amount` of the Payment Item.
`percentage-on-splits`	Choose this type when the Payment Split's `amount` and `percentage` is being calculated based on the `amount` of a different Payment Split.
`fixed`	Choose this type whne the `amount` of the Payment Split is a flat amount.
`keep-percentage`	This type has special rules on how Qualy treats payouts, calculation of taxes and more. Choose this type when you want to instruct Qualy to keep an specific percentage. It differs from `percentage-on-amount` due to internal rules. Use the field `keep` to specifiy how much you want to keep. The field amount will still represent how much the partnership is receiving. Learn more below, on what to expect when using this type.

Qualy also support the values self and supplier, but these are used internally and we don't recommend their usage, as it can create unexpected payout conflicts.

Understanding the "keep-percentage" behavior

Here are some of the rules Qualy applies when a Payment Split is of type keep-percentage.

The field taxTotal will be calculated based on the keep field, instead of the amount field.
If the Payment Intent has a supplier associated with it, the amount the Tenant would receive of Payout will be impacted. If no keep-percentage Payment Split is defined, the whole amount will be sent to the supplier and other partnerships.
If a Payment Split type percentage-on-splits is referecing a Payment Split type keep-percentage, the amount the Tenant will receive will be affected, especially if the payment has a supplier associated with it.

This Payment Split type exists to accommodate needs of Tenants that commercialize a product they don't own, and need to retain their commission and send most of the Payment Intent amount to their supplier. A common example of this use case would be education agents in the international education industry.

Tax calculation

Qualy's v1 API calculates the payment split tax based on the total amount. If you need to apply different tax rates based on the payment item, you must create different payments.

Check our Tax API to retrieve, and create taxes. Use the created tax _id in the payment split creation to get the tax calculated automatically by Qualy.