Integration guide Third Party Commissions

December 18, 2024

Enable third-party commissions for your merchant.

To enable Third Party Commissions feature in your merchant, you mustsubmit a request through our support center with the following information:

• Email
• Merchant ID or Name
• How can we help you? (Other)
• Business Impact (Limited)
• Subject (Enable Third-Party Commissions feature)
• Description (Add detailed information about the request)
• Country

Once the form is submitted, you need confirmation that the feature has been enabled.

Perform the integration to accept third-party commissions

If you have ready your integration with Kajita or Kushki.js, you can skip this step.

To use the Third-Party Commissions feature, you need to integrate our frontend solutions (Kajita or Kushki.js) and link them to your backend. For this, you can check our guide Accept a card payment.

Review your Third-Party Commissions configuration

Validate if the service is active and obtain information related to the commission charges configured for your business using the getCommissionConfiguration method in Kushki.js or the Get Commission Configuration endpoint of our API. It is necessary to integrate one of these options depending on your integration type to display a breakdown to the end user with the amounts to be charged.

getCommissionConfiguration() Method in Kushki.js

Validate the configured information for your business and display a breakdown for Third-Party Commissions by consulting the getCommissionConfiguration method from Kushki.js in case you have implemented the kushki.js library. Below is an example:

Request

var callback = function (response) {
  if(!response.code){
    console.log(response);
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
};

  kushki.getCommissionConfiguration({
    totalAmount: 100, 
    currency:'USD'
  }, callback);

Required parameters

• totalAmount: Send the amount for which you want to know the commission to be charged (e.g., $100)
• currency: Send the currency configured in your merchant

Response

Once the getCommissionConfiguration method is consumed , a similar response to the following will be returned:

{
    "commissionMerchantName": "Merchant commissions",
    "parentMerchantName": "Fintech Global",
    "amount": {
        "currency": "USD",
        "iva": 0,
        "subtotalIva": 4,
        "subtotalIva0": 0
    },
    "merchantId": "20000000103814111000",
    "totalAmount": 4
}

Where

• commissionMerchantName: It is the merchant’s name that will receive the commission
• parentMerchantName: It is the main merchant’s name
• amount: The amount object indicates the commission amount based on the rules configured in the main merchant.
• merchantId: Refers to the merchant ID that will receive the commission.
• totalAmount: It is the total commission amount to be charged, which must be added to the original (in the previous example $100 for the sale + $4 for the commission = $104)

For example, if the main merchant has a 4% commission configured per transaction and a $100 transaction is made, the transaction will amount to $100 for the original sale plus $4 for the commission ($104 in total). Thus, the main merchant will receive $100, and the merchant receiving the commission will receive $4, which corresponds to the amount returned by the totalAmount field.

Get Commission configuration Endpoint via API

It is necessary to consume the Get Commission Configuration endpoint from our Online Payments API to obtain the configuration information for Third-Party Commissions in your merchant as well as the commission to be charged, allowing you to display the breakdown to the end customer on the payment screen. Below is an example:

Request

{
  "totalAmount": 100,
  "currency": "USD"
}

Response

{
    "commissionMerchantName": "Merchant commissions",
    "parentMerchantName": "Fintech Global",
    "amount": {
        "currency": "USD",
        "iva": 0,
        "subtotalIva": 4,
        "subtotalIva0": 0
    },
    "merchantId": "20000000103814111000",
    "totalAmount": 4
}

Where

• commissionMerchantName: It is the merchant’s name that will receive the commission
• parentMerchantName: It is the main merchant’s name
• amount: The amount object indicates the commission amount based on the rules configured in the main merchant.
• merchantId: Refers to the merchant ID that will receive the commission.
• totalAmount: It is the total commission amount to be charged, which must be added to the original (in the previous example $100 for the sale + $4 for the commission = $104).