Split Payments

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

What is a subaccount?

A subaccount holds the external bank information for a third-party seller, vendor, or service provider with whom you want to split payments. When a split payment is made, the funds are sent to the bank account associated with the subaccount.

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).

• 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 settlement. This means if we get subaccount in your payload regardless of the currency we will convert it to ETB and do the settlement.

Endpoint https://api.chapa.co/v1/subaccount

Method GET

• Authorization : Pass your secret key as a bearer token in the request header to authorize this call.

1import requests
2  import json
3
4  url = "https://api.chapa.co/v1/subaccount"
5  payload = {
6      "business_name": "Abebe Souq",
7      "account_name": "Abebe Bikila ",
8      "bank_code": 128,
9      "account_number": "0123456789",
10      "split_value": 0.2,
11      "split_type": "percentage"
12  }
13  headers = {
14      'Authorization': 'Bearer CHASECK-XXXXXXXXXXXXXXX',
15      'Content-Type': 'application/json'
16  }
17
18  response = requests.post(url, json=payload, headers=headers)
19  data = response.text
20  print(data)

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

Split payments can be initialized via the Initialize Transaction API or Direct Charge API:

Endpoint https://api.chapa.co/v1/transaction/initialize or https://api.chapa.co/v1/charges?type={payment_method}

Method POST

• Authorization : Pass your secret key as a bearer token in the request header to authorize this call.

1import requests
2  import json
3
4  url = "https://api.chapa.co/v1/transaction/initialize"
5  payload = {
6      "amount": "10",
7      "currency": "ETB",
8      "email": "abebech_bekele@gmail.com",
9      "first_name": "Bilen",
10      "last_name": "Gizachew",
11      "phone_number": "0912345678",
12      "tx_ref": "chewatatest-6663",
13      "callback_url": "https://webhook.site/077164d6-29cb-40df-ba29-8a00e59a7e60",
14      "return_url": "https://www.google.com/",
15      "customization": {
16  "title": "Payment for my favourite merchant",
17              "description": "I love online payments."
18          },
19          "subaccounts": {
20              "id": "ac2e6b5b-0e76-464a-8c20-2d441fbaca6c"
21          }
22      }
23      headers = {
24          'Authorization': 'Bearer CHASECK-XXXXXXXXXXXXXXX',
25          'Content-Type': 'application/json'
26      }
27      
28      response = requests.post(url, json=payload, headers=headers)
29      data = response.json()
30      
31      if response.status_code == 200 and data.get('status') == 'success':
32          checkout_url = data['data']['checkout_url']
33          print(f"Checkout URL: {checkout_url}")
34      else:
35          error_message = data['message']
36          print(f"Transaction initialization failed: {error_message}")
37          

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, For example if 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",
    split_value: 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.