Sub-Merchant Settlement & Commission Splitting

Empower your business ecosystem with our Automated Commission Splitting. Onboard sub-merchants, define custom fee structures for every payment channel, and let our API handle the complex math of revenue distribution in real-time.

1. Overview

This feature allows you to route payments and manage settlements for your sub-entities (branches, vendors, or partners) using a single integration. By including a sub_merchant_code in your billing requests, Flip will automatically identify the transaction's destination, apply the pre-configured commission rules, and ensure funds are allocated correctly to your sub-merchant's account.

Key Features

The Splitting Commission Fee feature allows Parent Merchants to:

• Onboard & Manage Sub-Merchants: Register and update sub-merchant profiles, including their bank account details for settlements.
• Custom Fee Configuration: Set specific commission fees (either a fixed nominal amount or a percentage) for different payment categories like Virtual Accounts, E-Wallets.
• Automated Commission Calculation: Automatically calculate the "net amount" and "commission fee" for every transaction processed through a sub-merchant.

2. How to Get Started (Onboarding)

To use this feature, you must first register your sub-merchants in our system. During this initial release phase, registration is handled manually:

1. Contact your Sales Representative or Account Manager to provide the details of the sub-merchants you wish to onboard.
2. Our team will configure the sub-merchant profiles and set up their specific commission fee structures.
3. Once completed, you will receive a unique sub_merchant_code that you can use for each sub-entity. Use these sub_merchant_code in your API requests create bill to trigger the splitting logic.

This feature only available in the Flip Accept Payment API V3

3. Updated API Specification: Create Bill V3

The Create Bill V3 endpoint now includes an optional field to support multi-entity business models. When this field is utilized, our system triggers the automated splitting and settlement logic pre-configured for that specific sub-entity.

Create Bill Payment Link

STAGING DOMAIN URL

Currently, the feature is only available in our production environment. Please contact your Sales Representative or Account Manager to use this feature.

API Endpoint

Environment	Method	URL
Live Mode	POST	https://bigflip.id/api/v3/pwf/bill

Request Header

Key	Value	Description
Authorization	Basic Base64(<FLIP_API_SECRET_KEY + :>)	The API key used to authenticate the request. For more details, refer to this.
Content-Type	application/json	Specifies the media type of the request body, ensuring it is in JSON format.

Request Details

In this step, after the customer redirected to Flip Payment checkout page, the customer is required to enter their information, such as name, email, and other details, before selecting a payment method on the Flip Checkout page. This ensures the necessary data is collected directly from the customer.

Requirement	Required	Description
title	Yes	The title of the bill, displayed on the Flip payment checkout page.
type	Yes	Bill type. Acceptable values: SINGLE or MULTIPLE.
step	Yes	Specifies the step customers are redirected to when opening the payment redirection link. More details here.
amount	No	Payment amount, minimum Rp10,000. For the checkout step, leave blank for a flexible amount. The amount is required for the checkout-seamless step.
redirect_url	No	The merchant's redirect URL, used after successful customer payment.
reference_id	No	A field to store your transaction identifier.
expired_date	No	Bill expiry date. The bill cannot be used beyond this date. Format: YYYY-MM-DD HH:mm.
is_phone_number_required	No	flag with boolean value if user required to input their phone number before select payment method in the Flip checkout page. Default: false
is_address_required	No	flag with boolean value if user required to input their address before select payment method in the Flip checkout page. Default: false
sub_merchant_code	No	The unique identifier for your sub-merchant. Note: This code must be obtained from your Sales Representative prior to making the API call. If the code is not registered or is inactive, the transaction will be processed as a standard bill under your parent account without splitting logic.

Minimum Sample Request:

curl --location 'https://<flip-staging-domain>/big_api/v3/pwf/bill' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64(YOUR_FLIP_SECRET_KEY + :)>' \
--data '{
  "title": "SubMerchant A Payment Order",
  "type": "single",
  "step": "checkout",
  "amount": 7000000,
  "sub_merchant_code": <sub_merchant_code>
}'

Sample Response:

Here is the sample api response for step with minimum request with sub_merchant_code field.

{
  "link_id": 2502091430251230005,
  "link_url": "https://flip.id/$merchantname/#billv3testing5324694598-4860",
  "title": "SubMerchant A Payment Order",
  "type": "SINGLE",
  "amount": 7000000,
  "redirect_url": "",
  "expired_date": null,
  "created_from": "API",
  "status": "ACTIVE",
  "is_address_required": false,
  "is_phone_number_required": false,
  "step": "checkout",
  "company_code": "YOUR_FLIP_COMPANY_CODE",
  "product_code": "FLIP_UNIQUE_PRODUCT_CODE",
  "reference_id": "",
  "sub_merchant_code": "<your_sub_merchant_code>"
}

Error Handling

If you pass a sub_merchant_code that does not exist in our records, the API will return a 422 Unprocessable Entity:

Sample Error Response:

{
    "code": "VALIDATION_ERROR",
    "errors": [
        {
            "attribute": "sub_merchant",
            "code": 1024,
            "message": "Sub merchant not found"
        }
    ]
}

Solution: Verify the sub_merchant_code with your Sales Representative or ensure there are no typos in your request string.

4. How the Field Influences the Transaction Flow

Identification: When sub_merchant_code is present, the system maps the transaction to the specific bank account and fee configuration associated with that sub-merchant.

Fee Calculation: Instead of applying your standard parent merchant rates, our system applies the custom Fixed (Nominal) or Percentage fee configured during the manual onboarding of that sub-merchant.

The Sub-Merchant Settlement feature is designed to simplify how you manage complex business structures. By integrating the sub_merchant_code into your existing workflow, you can automate your revenue sharing and reduce manual reconciliation. To begin your onboarding and receive your unique merchant codes, please contact your Sales Representative or reach out to our Account Management team.