Split Payments

This document goes over how you can share your transaction settlement with a third party.

Split payments are carried out by first creating a subaccount, then initializing the split payment. Utilizing split payment is essential in scenarios where there is a shared payment between a service provider and platform provider.

Create a subaccount

Subaccounts can be created easily via the Chapa Dashboard or using the Create Subaccount API:

• bank_code and account_number: The bank account details for this subaccount. The bank_code is the bank id (you can get this from the get banks endpoint).

When you are in Test Mode, you can use any of our test account numbers as your subaccount.

• business_name: The vendor/merchant detail the subaccount for.
• account_name: The vendor/merchant account’s name matches from the bank account.
• split_type: The type of split you want to use with this subaccount.
  • Use percentage if you want to get a percentage of each transaction.
  • Use flat if you want to get a flat fee from each transaction, while the subaccount gets the rest.
• split_value: The amount you want to get as commission on each transaction. This goes with the split_type, for example:
  • to collect 3% from each transaction, split_type will be percentage and split_value will be 0.03.
  • to collect 25 Birr from each transaction, split_type will be flat and split_value will be 25.

Note that subaccounts are working with ETB currency as a default settlment. This means if we get subaccount in your payload regardless of the currency we will convert it to ETB and do the settlment.

curl https://api.chapa.co/v1/subaccount
    -H "Authorization: Bearer YOUR_SECRET_KEY"
    -H "Content-Type: application/json"
    -d '{ "business_name": "Abebe Souq", 
          "account_name": "Abebe Bikila"
          "bank_code": "001", 
          "account_number": "0123456789", 
          "split_value": 0.2,
          "split_type": "percentage" 
        }'
    -X POST

If creating this account is successful we will return the subaccount id which you will need it when you initiate a transaction.

Initializing Split Payment

Subaccounts can be created via the Initialize Transaction API:

curl https://api.chapa.co/v1/transaction/initialize
    -H "Authorization: Bearer YOUR_SECRET_KEY"
    -H "Content-Type: application/json"
    -d '{ "email": "customer@email.com", 
          "amount": "200", 
          .... 
          "subaccounts[id]": "3380b03b-1142-44sb2-b6ab-9aec740fbe49" 
          
        }'
    -X POST

Overriding the defaults

When collecting a payment, you can override the default split_type and split_value you set when creating the subaccount, by specifying these fields in the subaccounts item:

• split_type: The type of commision to charge for this transaction:
  • flat if you want to get a flat fee while the subaccount gets the rest, or
  • percentage if you want to get a percentage of the settlement amount.
• split_value: The amount to charge as commission on the transaction. It is important to match the split_value for example:

for example: - to collect 3% from each transaction, split_type will be percentage and split_value will be 0.03. - to collect 25 Birr from each transaction, split_type will be flat and split_value will be 25.

Here are some examples. In each of these transactions, let’s suppose the whole amount paid is 100 ETB and Chapa fees are 6 ETB.

subaccounts: [
  {
    id: "3380b03b-1142-44b2-b6ab-9asec740fbe49",
    // If you want the subaccount to get 69 ETB only
    // Subaccount gets: 69
    // You get: 100 - 6 - 25 = 69
    split_type: "flat",
    transaction_charge: 25,
  },
],

Keep in Mind!!!!

Knowing your vendors/sub-accounts is your responsibility and if there is any dispute or chargeback raised we will be taking it from your account and it will be reflecting in your image.

• Chapa fees are taken from you / customer.

---

Verify Payments

← Previous

HTML Checkout

Next →

Related Docs

• Banks
• Testing Bank Accounts
• Testing Cards