Reference
Need help?

Configuration

Below is a comprehensive guide for merchants on how to integrate and implement the Split Payment feature through the Merchant Admin Portal.

Sub-Merchant configuration In Merchant Admin:

  • Once split payment option is enabled on merchant’s store, they will be able to access ‘Split Payment’ button in Merchant admin “Integrations” page

Adding Sub-Merchant:

  • Merchants can add Sub-Merchants (Beneficiaries) under the ‘Split Payment’ section of their store.
  • To add a Sub-Merchant, the merchant will click the ‘Add’ button and fill in the following details:
  1. Payout Currency
  2. Payout Method
  3. Beneficiary Type (New and Existing)
  4. Sub-merchant Name
  5. Split Type (Percentage or Flat)
  6. Split value (Exact value for flat split)
  7. Email (Sub merchant email ID)
  8. Payout Interval (Weekly and Monthly)
  9. Payout Minimum
  10. Check box for shared details confirmation.

Percentage and Flat Split Validation:

  • If the split type is Percentage, the system will ensure the value does not exceed 100%.
  • If the split type is Flat, and the amount exceeds the transaction value, the transaction will be blocked.

Notification & Sub-Merchant Approval:

  • After submitting the details, a system-generated email is sent to the Sub-Merchant (Email provided in the Sub merchant details).
  • The email will contain a link to the Terms and Conditions, which the Sub-Merchant must review and accept.
  • Upon acceptance, the Sub-Merchant is redirected to a form where they will need to provide the following details:
  1. Bank Name
  2. Account Name
  3. Account Number
  4. Swift Code
  5. IBAN
  6. Company Type
  7. Emirates ID (No restriction on upload number)
  8. Bank Statement (Restriction to upload only 1 document)
  9. Trade Licence (Restriction to upload only 1 document)
  10. VISA (No restriction on upload number)
  11. Passport (No restriction on upload number)
  12. Enter Code (after clicking on ‘Generate Code’ Sub-Merchant will receive code on their email address. They will enter the code and ‘Verify’, after only verifying the code, they can submit the details)
  • Once a Sub-Merchant is created, an application is added under the "KYC Application" section with the following details:
  1. Application ID (Unique Identifier)
  2. Sub-Merchant Name
  3. Email ID (Sub-Merchant's Email ID)
  4. Status
  • On the ‘Split Payment Details’ page in the Merchant Admin, the following three buttons will be available:

  1. Add (To add a new entry into the system)

  2. KYC Applications (Displays the status of the Sub-Merchant's KYC entry)

  1. Add Logo (Allows the merchant to upload their logo, which will be displayed on the Sub-Merchant Application page.)
  • After the application is approved by Telr a unique Split ID is generated and displayed on the merchant dashboard with the following details:
  1. Split ID (Sub-Merchant Unique ID)
  2. Split Type (Percentage or Flat)
  3. Split Value
  4. Payout currency
  5. Account Name
  6. Payout Account
  • Sub-merchant entry “Delete option”:

If the merchant opens a Split ID, they will see a Delete option. Using this button, they can deactivate the existing Split ID. (Refer to the screenshot below for details.)

User permission for split payment option

  • Additional permissions are required for Merchant Admin users to provide access to the Split Payment option. This ensures that only authorized users can manage split payments.

Single Sub-Merchant in Single Transaction Request:

  • Once the Sub merchant details is added, merchant will have a unique Split ID for different sub merchant on their store. Merchant can pass the single Split ID in the transaction request and the split amount will be settled to the account linked to that ID.

Split payment in API, Quicklink and E-Invoicing option:

  • After creating a Sub-Merchant account, the merchant will see a Split ID dropdown option in both the Quicklink and E-Invoicing creation screens. For API transactions, merchants must include the Sub-Merchant Split ID in the additional parameter “split_id” to activate split payment for that transaction.
  1. Quicklink:
  1. E-Invoicing:

Additional Split Payment Parameter in API request:

Merchant integrated with Telr using the Hosted Payment Page API Guide (V2) can utilize the following additional parameters in their API requests.

  • For form based request use the “split_id” parameter in the transaction request.

For JSON requests Use the “splitpayment” parameter in the following format. 

"splitpayment": { "id": <id_value> }

Merchants must pass the Split ID as the value in the split_id parameter to identify the Sub-Merchant for whom the split payment needs to be processed. Once the transaction is completed, the split settlement will be processed based on the details provided when creating the Split ID.

Additionally, during order creation, merchants can modify the split value and split type associated with the Split ID by using the split_type and split_value fields. The values specified in these fields will override the ones initially set during the Split ID creation. This provides flexibility to adjust the split details for a specific order, allowing for dynamic control over the split payment distribution.

For form-based requests, use the split_type and split_value parameters in the transaction request.

For JSON requests, use the splitpayment parameter in the following format:

"splitpayment": { "type": "<type>", "value": "<value>" }
  • 'type' can be either flat or percentage, indicating whether the split amount is a fixed value or a percentage of the transaction. System will only accept type values only as "flat" or "percentage".
  • 'value' must be a non-zero integer representing the split amount. For percentage type the value range is from 1 to 100, and for flat the value can be any value above zero.
  • Split charges will be applied after merchant service fee is deducted from the transaction value.

Note: Split functionality is currently unavailable for Remote transactions.

Payouts and Split details entries in the system:

  • In the Accounts section, a new column called SplitAmt has been added to display split payment details in both the Pending Transactions and Transaction Details entries.
  • The SplitAmt column will show the split value allocated to the Sub-Merchant for each transaction.
  • The transaction flow will proceed as usual. After the transaction is completed, its details will be recorded in the Payout History under the Accounts tab in the Merchant Admin.
  • The transaction amount will be distributed and settled between the Merchant and Sub-Merchant accounts as specified during the creation of the Split Payment ID.
  • Payout fees will be deducted from the primary merchant’s settlement account.
  • The payout interval (monthly, weekly, or same as the primary merchant) can be configured during the application creation process.

Test Split ID values for order JSON API:

Using the Test Split ID in a transaction request will process the transaction under the split payment flow. The following values can be used in the order.json API to simulate split payment transactions in test mode with "test" parameter as "1":

  1. If Split ID value is passed anything from 1 to 100, it will act as flat settlement functionality for sub merchant. (E.g.: split_id=5, then the settlement amount will be flat 5AED on that transaction)
  2. If Split ID value is passed anything from 1000 – 100000, it will act as percentage settlement functionality for sub merchant. Value will be multiples of 1000 and will be treated as percentage values (E.g.: 1000 = 1%, 2000 = 2%, 30000 = 30% and it goes on).
  3. If the split id value is more than 100 which are not multiple of 1000 or more than 100000, then the request will be declined with an exception.

Note: Settlement will not be done in Split payment test mode. The test split ID’s will not be visible on the merchant dashboard. Split type and Split value parameters are not supported in test mode.