Subaccounts

A subaccount is a settlement destination owned by your organization. Attach one to a payment and Seev splits that payment between your main balance and the subaccount, each with its own payout record. Use it when someone else has a claim on part of the money: a partner studio, a branch, a vendor on a marketplace.

How a split works

Fees come off the top, then both sides take their percentage. Each side receives its share of the gross, the fee and the net, so a partner on 30% carries 30% of the processing fee on that payment rather than having it absorbed for them.

Create a subaccount

You can create a subaccount from the dashboard or through the API. Both produce the same record and the same SUB_ code.

From the dashboard, go to Subaccounts in the sidebar. Viewing needs the payout_settings.read permission and creating or pausing needs payout_settings.manage, so a teammate on a limited role may not see the page at all.

A new subaccount is created active, and its code is returned in the form SUB_ followed by sixteen hex characters. That code is what you pass at checkout. Whether it starts verified depends on the destination, covered under How a subaccount gets verified.

Through the API

The subaccount routes take the same developer key as the Checkout API, on the same host, so sandbox and production follow the key you send. Field names are snake_case here and differ from the dashboard labels.

curl -X POST \
  https://api.seevplus.com/api/v1/developer/subaccounts \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Ama Studio",
    "settlement_bank": "mtn",
    "account_number": "0241234567",
    "account_name": "Ama Mensah",
    "default_share_percent": 30
  }'

A successful create returns 201 and the subaccount, with the account number masked to its last four digits. A request Seev refuses, such as an unknown code or a name that does not match, returns 422 with the reason in message.

Settlement codes

settlement_bank takes one of these codes. The three mobile money codes are fixed:

Bank codes come from the live list, along with the mobile money codes above, so read them from the API rather than hard-coding them:

curl https://api.seevplus.com/api/v1/developer/settlement-banks \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY"

{
    "success": true,
    "data": {
        "mobile_money": [
            { "code": "mtn", "name": "MTN MoMo", "type": "mobile_money" },
            { "code": "telecel", "name": "Telecel Cash", "type": "mobile_money" },
            { "code": "at", "name": "AT Money", "type": "mobile_money" }
        ],
        "banks": [{ "code": "300304", "name": "GCB Bank", "type": "bank" }],
        "banks_available": true
    }
}

banks_available is false on the rare occasion the bank list cannot be loaded. The mobile money codes are always returned.

Look up an account name

Before you create a mobile money subaccount, confirm who the number belongs to. The lookup returns the name the network has registered against it.

curl -X POST \
  https://api.seevplus.com/api/v1/developer/resolve-account \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settlement_bank": "mtn",
    "account_number": "0241234567"
  }'

{
    "success": true,
    "data": {
        "settlement_bank": "mtn",
        "account_number": "0241234567",
        "account_name": "AMA MENSAH"
    }
}

Pass the returned account_name straight into the create request. A number the network does not recognise returns 404. The lookup covers mobile money only; a bank code returns 422.

How a subaccount gets verified

If the network cannot be reached during a mobile money check, the subaccount is created as pending. Send the same account_number and account_name in a PATCH to run the check again.

Manage through the API

Read a subaccount's state

Pausing a subaccount has the same effect as leaving it unverified: a checkout request that names it is refused, so drop the subaccount field to take the payment in full to your main balance. Payments already split keep their share.

Split a payment through the API

Pass the subaccount code as subaccount when you create a checkout session. Everything else about the request is unchanged.

curl -X POST \
  https://api.seevplus.com/api/v1/developer/payments \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "amount": 10000,
    "currency": "GHS",
    "subaccount": "SUB_9f2k1p7qw4r8c3e1",
    "recipient": {
      "name": "Ama Mensah",
      "email": "ama@example.com"
    },
    "redirect_url": "https://yourapp.com/payment/callback"
  }'

Seev resolves the code before the session is created, and rejects the whole request rather than quietly ignoring the split if any of these does not hold.

A failure here reaches you the way every other upstream failure on this route does: a 502 whose message carries the upstream text, such as the subaccount being inactive, still pending verification, or holding a different currency. See Errors and codes for how to read one.

The session response carries a split object describing what was applied, so you can record the share against your own order:

{
    "split": {
        "subaccount": "SUB_9f2k1p7qw4r8c3e1",
        "business_name": "Ama Studio",
        "share_percent": 30
    }
}

Payouts

A split payment is paid out twice: your share to your payout destination, and the subaccount's share to the subaccount's own destination. Both follow your payout schedule. On a GH₵1,000 payment with a 1.5% fee and a subaccount on 80%:

In the dashboard, Accounts lists both kinds of payout together, with a Paid to column that names the subaccount.

Read payout history through the API

List every payout made to you and to your subaccounts, newest first:

curl "https://api.seevplus.com/api/v1/developer/payouts" \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY"

Add subaccount to get one subaccount's payouts, which is what you need to show a partner their own history inside your product. Use subaccount=main for your own payouts only.

curl "https://api.seevplus.com/api/v1/developer/payouts?subaccount=SUB_9f2k1p7qw4r8c3e1" \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY"

{
    "success": true,
    "data": {
        "payouts": [
            {
                "id": "stlp_66f1a_20260927T000000Z_20260928T000000Z_sub_9f2k1p7qw4r8c3e1",
                "account_type": "subaccount",
                "subaccount": "SUB_9f2k1p7qw4r8c3e1",
                "business_name": "Ama Studio",
                "amount": 78800,
                "gross_amount": 80000,
                "fee_amount": 1200,
                "currency": "GHS",
                "transaction_count": 1,
                "status": "paid",
                "reference": "MOMO-20260928-118",
                "period": {
                    "from": "2026-09-27T00:00:00Z",
                    "to": "2026-09-28T00:00:00Z"
                },
                "paid_at": "2026-09-28T09:14:00Z",
                "destination": {
                    "type": "mobile_money",
                    "network": "mtn",
                    "account_name": "Ama Mensah",
                    "account_number_masked": "******4567"
                }
            }
        ],
        "total": 1,
        "page": 1,
        "limit": 20,
        "env": "production"
    }
}

Common questions