# Creating a payment split

> Creating a payment split using Qualy's API.

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](/docs/guides/creating-payment-intents.md) to create a Payment Intent.

The `partnership`, `contact`, and `tax` fields accept [smart references](/docs/smart-references.md). The `paymentIntent`, `item`, `split`, `ref`, `order`, and `orderItems` fields still require ObjectIds.

## Creating a payment split

To create a payment split on Qualy, you will have to use the [Payment Splits API](https://v1-spec.qualyhq.com/#post-/v1/payment-splits/create).

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

**cURL**

```bash
curl -X POST https://api.qualyhq.com/v1/payment-splits/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "percentage-on-amount",
    "currency": "AUD",
    "amount": 3000,
    "partnership": "usyd",
    "item": "661e9bc0e0eb901d6b2f2682",
    "contact": "john.doe@example.com",
    "split": "63fdfda0c7ca4bb64baa50a3",
    "dueAt": "2024-08-20T17:39:31.219Z",
    "tax": "GST 10%",
    "percentage": 0.3,
    "paymentIntent": "661e9bbfe0eb901d6b2f2670"
  }'
```

**JavaScript**

```javascript
const res = 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: 'usyd',
    item: '661e9bc0e0eb901d6b2f2682',
    contact: 'john.doe@example.com',
    split: '63fdfda0c7ca4bb64baa50a3',
    dueAt: '2024-08-20T17:39:31.219Z',
    tax: 'GST 10%',
    percentage: 0.3,
    paymentIntent: '661e9bbfe0eb901d6b2f2670',
  }),
});

const { data: paymentSplit } = await res.json();
console.log(paymentSplit._id);
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$paymentSplit = Http::withHeaders([
    'Authorization' => 'ApiKey your-api-key-here',
    'X-TENANT-ID' => 'your-tenant-id-here',
])->post('https://api.qualyhq.com/v1/payment-splits/create', [
    'type' => 'percentage-on-amount',
    'currency' => 'AUD',
    'amount' => 3000,
    'partnership' => 'usyd',
    'item' => '661e9bc0e0eb901d6b2f2682',
    'contact' => 'john.doe@example.com',
    'split' => '63fdfda0c7ca4bb64baa50a3',
    'dueAt' => '2024-08-20T17:39:31.219Z',
    'tax' => 'GST 10%',
    'percentage' => 0.3,
    'paymentIntent' => '661e9bbfe0eb901d6b2f2670',
])->json('data');

echo $paymentSplit['_id'];
```

> **Note — 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](https://v1-spec.qualyhq.com/#post-/v1/payment-intents/-paymentIntentId-/items/create) `_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 used 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](https://v1-spec.qualyhq.com/#post-/v1/payment-intents/-paymentIntentId-/items/create). |
| `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](https://v1-spec.qualyhq.com/#post-/v1/tax/create) to retrieve, and create taxes. Use the tax ObjectId or tax name in the payment split creation to get the tax calculated automatically by Qualy.