Split Payment

Split Payments allow you to automatically distribute a single customer payment between multiple recipients (subaccounts). This is commonly used for:

• Marketplaces (vendor payout + platform commission)
• Multi-branch businesses
• Partner settlements
• Affiliate revenue sharing

Splits are configured using subaccounts and included during payment initialization. The customer pays once, and Chapa routes the defined portions to the specified subaccounts based on your split rules.

Key Concepts

Subaccount

A subaccount represents a beneficiary (vendor/partner) with settlement details and split configuration.

Create subaccounts using:

POST /v2/subaccounts

The response returns:

• subaccount_reference — used later when initializing a payment.

Split Rule

Each split entry defines:

• Which subaccount receives funds (subaccount_reference)
• How much they receive (split_type + split_value)

1) Create a Subaccount

Endpoint:

POST /v2/subaccounts
Host: api.chapa.co

Example Request:

POST https://api.chapa.co/v2/subaccounts
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "subaccount_name": "Acme Vendor Wallet",
  "account": {
    "account_number": "251987654152",
    "account_name": "Anwar",
    "bank_slug": "telebirr",
    "bank_name": "telebirr Mobile Money"
  },
  "currency": "ETB",
  "split_type": "percentage",
  "split_value": 10,
  "min_amount": 50,
  "max_amount": 50000
}

Example Response:

{
  "status": "success",
  "message": "Subaccount created successfully",
  "data": {
    "subaccount_reference": "SUB_ABCDEF123456",
    "created_at": "2025-02-02T11:30:00Z",
    "updated_at": "2025-02-02T11:30:00Z"
  }
}

2) Initialize a Payment With Split Rules

When initializing hosted checkout, pass a subaccounts array.

Endpoint:

POST /v2/payments/hosted
Host: api.chapa.co

Example Request (Split Payment):

POST https://api.chapa.co/v2/payments/hosted
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 25000,
  "currency": "ETB",
  "merchant_reference": "ORDER_1001",
  "subaccounts": [
    {
      "subaccount_reference": "SUB_REF_001",
      "split_type": "percentage",
      "split_value": 10
    },
    {
      "subaccount_reference": "SUB_REF_002",
      "split_type": "flat",
      "split_value": 243
    }
  ],
  "meta": {
    "order_id": "ORD-99887",
    "notes": "Hosted payment with split rules"
  }
}

Split Types

Webhook Behavior for Split Payments

Split payments use the same webhook structure as normal payments.

• The primary payment webhook reports the full payment amount
• Your system should reconcile splits using:
  • merchant_reference
  • meta.order_id
  • The split rules you stored during initialization

Common payment events still apply:

• payment.success
• payment.failed
• payment.cancelled
• payment.partially_refunded
• payment.fully_refunded

Refunds & Splits

Refund events are communicated via:

• payment.partially_refunded
• payment.fully_refunded

Recommended approach:

• Track refunded amount at the payment level
• Apply your own business logic for how refunds should affect subaccount settlement reporting (depending on your marketplace policy)

Validation Rules (Common Errors)

Best Practices

• Create subaccounts once and reuse references
• Store subaccount_reference + split rules in your database
• Use Idempotency-Key when initializing payments to avoid duplicates
• Validate splits (types, values, and business rules) before initialization
• Always verify payment success before triggering settlement or fulfillment logic

Next Steps

• Accept Payments - Full hosted payment integration
• Webhooks - Handle payment events in real-time
• Verify Payments - Confirm payment status