🚧

Account activation and configuration is required before development

A configured merchant relationship is required to use the Payment Splitting feature. If you need assistance, please reach out to [email protected].

Overview

The Payment Splitting feature enables Platform accounts to split payments to multiple connected child accounts. It's designed to support flexible payment distribution across various parties. To create child accounts and get started, refer to our Onboarding API.

Available Split Features

1. Transfer To: Either the full net amount or the remaining amount after the split would be deposited to the merchant or sub-account specified.
2. 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.
3. Fixed Amount: A type of split where an exact value is defined to be deposited to the merchant or sub-account specified.

Use Cases

The Split Payments API is ideal for scenarios such as:

• Marketplaces that need to allocate payments to sellers and service providers.
• Platforms that facilitate transactions between multiple parties and require automatic fund distribution.

How to use the Split Payment feature

The Split Payments API can be utilized with both the Payment Intent workflow and the 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.

{
    "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"
        }
    }
}

Newly Introduced Attributes

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

📘

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. Note: 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.