Overview

Use Payment Splitting to define and route payments to designated child accounts, making reconciliation easier.

Split Payment Types

When setting up a split payment, you have several options depending on how you want to distribute the funds. Each type of split allows you to define a specific amount or percentage to be allocated to a sub-account.

Transfer To

Either the full net amount or the remaining amount after the split would be deposited to the merchant or sub-account specified.

Percentage Net

A type of split where a percentage of the net amount is defined to be deposited to the merchant or sub-account specified.

Fixed Amount

A type of split where an exact value is defined to be deposited to the merchant or sub-account specified.

Split Type Attributes

The following table details the key attributes you'll use when configuring a split payment.

Attribute	Definition
`transfer_to`	The transfer_to field specifies the recipient of the remaining net amount after the payment has been split. The merchant assigned to this field will also be responsible for any associated fees. If no recipient is provided, the entire net amount will be transferred to the specified merchant. If the transfer_to field is left blank but a recipient is defined, the system defaults to transferring the net amount to the merchant who created the resource.
`recipients[].merchant_id`	The identifier for the associated recipient merchant.
`recipients[].split_type`	Determines the method of payment splitting. Possible values for now are `fixed` and `percentage_net`. If left blank, this would automatically be set to `fixed`.
`recipients[].value`	Defines the values of the split payment. For `fixed` split type, this field expects an integer in cents (e.g., 100 equals 1.00 in the respective currency). For `percentage_net`, this field expects an integer representing a percentage in basis points (bps) (e.g., 100 equals 1%).

To see these in action, refer to some sample split payment computations

Implementation

Here is the step-by-step for creating a split payment:

1. Create a Payment Intent or Checkout Session

Start by creating a Payment Intent workflow or Checkout API workflow. The key distinction is that you must specify the payment split during the creation of the payment intent or the checkout session by utilizing the split_payment attribute found in the respective creation process.

You may find the guides for both in the workflow links.

2. Add the necessary details under split_payment attribute

See the example below for how it looks in the Payment Intent and Checkout Session Request Body:

{
    "data": {
        "attributes": {
            "amount": 10000,
            "payment_method_allowed": [
                "gcash"        
            ],
            "payment_method_options": {
                "card": {
                    "request_three_d_secure": "automatic"
                }
            },
            "description": "Payment Intent with split payments",
            "statement_descriptor": "Company 1",
            "currency": "PHP",
            "split_payment": {
                "transfer_to": "org_RXm2cKMjjG88qriue913mhG3",
                "recipients": [
                    {
                        "merchant_id": "org_aw5CNAR7HSOnsa1923Wwsm", 
                        "split_type": "percentage_net",
                        "value": 100 // 1%
                    },
                    {
                        "merchant_id": "org_Xs7JUHY7I7bKY1BgFhAIJ2uWsq1", 
                        "split_type": "fixed",
                        "value": 500 // 5.00
                    }
                ]
            }
        }
    }
}

{
    "data": {
        "attributes": {
            "billing": {
                "address": {
                    "line1": "address line 1",
                    "line2": "address line 2",
                    "city": "Taguig",
                    "state": "Metro Manila",
                    "postal_code": "1234",
                    "country": "PH"
                },
                "name": "John doe",
                "email": "[email protected]",
                "phone": "09111111111"
            },
            "cancel_url": "https://paymongo.com",
            "description": "Checkout Session with split payment",
            "payment_method_types": [
                "gcash"
            ],
            "line_items": [
                {
                    "amount": 10000,
                    "quantity": 10,
                    "name": "Sample Product",
                    "description": "Sample Product",
                    "currency": "PHP",
                },
            ],
            "merchant": "Test Store",
            "reference_number": "test_ref_1234",
            "send_email_receipt": false,
            "show_description": true,
            "show_line_items": true,
          	"split_payment": {
                "transfer_to": "org_RXm2cKMjjG88qriue913mhG3",
                "recipients": [
                    {
                        "merchant_id": "org_aw5CNAR7HSOnsa1923Wwsm", 
                        "split_type": "percentage_net",
                        "value": 100 // 1%
                    },
                    {
                        "merchant_id": "org_Xs7JUHY7I7bKY1BgFhAIJ2uWsq1", 
                        "split_type": "fixed",
                        "value": 500 // 5.00
                    }
                ]
            },
            "success_url": "https://paymongo.com"
        }
    }
}

3. Ensure Proper Split Configuration

If the total defined payment split exceeds the net amount of the payment, the payment will proceed. However, the splitting mechanism will fail, resulting in no allocated amounts to the recipients. In this case, the entire net amount will be received solely by the merchant who created the resource.

❗️
Result of Improper Split Configuration
There is currently no automated way to proceed with the split in such cases, so the merchant will need to handle and settle the splitting manually.