Create Fee Rule

A Fee Rule Object defines how payments accepted on behalf of a sub-account are routed by xenPlatform. Include the fee_rule_id returned in the response in supported transaction endpoints - Invoices, Credit Cards, Virtual Accounts, eWallets, QR Codes, Direct Debits - to automatically charge a Platform fee and route payments to a different Account once payments settle.

Endpoint: Create Fee Rule

POST https://api.xendit.co/fee_rules

Example: Create Fee Rule

curl -- request POST \
   --url https://api.xendit.co/fee_rules \
   --header 'Authorization: Basic xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:' \
   --header 'Content-Type: application/json' \
   --data-raw '{
    "name": "20210908 Test",
    "description": "Platform fee for all transactions accepted on behalf of vendors",
    "routes": [{
      "unit": "flat",
      "amount": 3000,
      "currency": "IDR"
    }]
}'

  <?php
      $url = 'https://api.xendit.co/fee_rules';
      $apiKey = 'xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:';
      $headers = [];
      $headers[] = 'Content-Type: application/json';
      $data = [
          'name' => 'standard_platform_fee',
          'description' => 'fee_for_all_transactions_accepted_on_behalf_of_vendors',
          'routes' => [
              [
                  'unit' => 'flat',
                  'amount' => 3000,
                  'currency' => 'IDR'
              ]
          ]
      ];

      $curl = curl_init();

      $payload = json_encode($data);
      curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
      curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
      curl_setopt($curl, CURLOPT_URL, $url);
      curl_setopt($curl, CURLOPT_POST, true);
      curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

      $result = curl_exec($curl);
      echo $result;

from xendit import Xendit

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
xendit_instance = Xendit(api_key=api_key)
XenPlatform = xendit_instance.XenPlatform

xenplatform_fee_rules = XenPlatform.fee_rules(
    name="standard_platform_fee",
    description="fee_for_all_transactions_accepted_on_behalf_of_vendors",
    routes={
      "unit": "flat",
      "amount": 3000,
      "currency": "IDR"
    }
)
print(xenplatform_fee_rules)

Request Parameters

Body Parameter	Type	Description
name required	string	Name to identify fee rule. Not required to be unique. Typically based on transaction and/or sub-merchant types. e.g. “standard_platform_fee”, “commission”
description optional	string	Description to identify fee rule e.g. “Fee charged to insurance agents based in Java”
routes required	array	Array of objects that define how the platform wants to route the fees and to which accounts. Each Route object is equivalent to a single fee route from the end-customer to a destination account. Note: Currently, you may only enter a single Route object in the route parameter unit required string Available values: percent or flat amount required number fee amount based on unit. All units must be a positive number Percent amounts have to be between 0 and 100 Percent amounts are rounded off to the nearest monetary unit (e.g. 0.50 IDR will be rounded to 1 IDR; 0.49 IDR will be rounded to 0 IDR) currency required string ISO 4217 Currency Code Note: Will return an error if currency does not match transaction/account currency Available values: IDR;PHP destination_account_id optional string Destination account where the amount will be routed to. Note: if this parameter is empty, it will default to your master account business id

Response Parameters

Example: Fee Rules Response

{
    "id": "xpfeeru_d9e069f2-4da7-4562-93b7-ded87023d749",
    "name": "Standard platform fee",
    "description": "Platform fee for all transactions accepted on behalf of vendors",
    "routes": {
      "unit": "flat",
      "amount": 3000,
      "currency": "IDR",
      "destination_account_id": "5cafeb170c2b18519b148768"
    },
    "created": "2020-09-01T07:00:00.007Z",
    "updated": "2020-09-01T07:00:00.007Z",
    "metadata": {}
}

Parameter	Type	Description
id required	string	Xendit system generated unique ID. Format: xpfeeru_{{id}} e.g. xpfeeru_NF5p90U3MQ5MXAuH1NF
name required	string	Name to identify fee rule. Not required to be unique. Typically based on transaction and/or sub-merchant types
description optional	string	Description to identify fee rule. Otherwise NULL
routes required	array	Array of objects that define how the platform wants to route the fees and to which accounts. Each Route object is equivalent to a single fee route from the end-customer to a destination account. Note: Currently, you may only enter a single Route object in the route parameter unit required string Available values: percent or flat amount required number fee amount based on unit. All units must be a positive number Percent amounts have to be between 0 and 100. Percent amounts are rounded off to the nearest monetary unit (e.g. 0.50 IDR will be rounded to 1 IDR; 0.49 IDR will be rounded to 0 IDR) currency required string ISO 4217 Currency Code Note: Will return an error if currency does not match transaction/account currency Available values: IDR;PHP destination_account_id required string Destination account where the amount will be routed to. Note: if this parameter is empty, it will default to your master account business id
created required	string	Timestamp in ISO 8601 when the fee rule object was created Format: YYYY-MM-DDTHH:mm:ssZ Timezone: UTC+0
updated required	string	Timestamp in ISO 8601 when the fee rule object was updated Format: YYYY-MM-DDTHH:mm:ssZ Timezone: UTC+0
metadata optional	object	Object of additional key-value pairs that the merchants may use like internal system parameters (business ID, shopping cart). User defines the JSON properties and values. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Otherwise NULL

Error Codes

Error Code	Description
INVALID_FEE_AMOUNT 400	Fee amount and/or unit is negative number or incorrect format.
API_VALIDATION_ERROR 400	Inputs are failing validation. The errors field contains details about which fields are violating validation.
RELATIONSHIP_NOT_FOUND 400	Returned when destination_account_id at the route does not have relationship with the Business ID initiating the request