Menu
Language

Step 2: Create a Settlement Account via API

You can create settlement accounts by either

  • Logging into your Kopo Kopo merchant account and adding settlement accounts in the Account Settings section or
  • Via the Kopo Kopo Connect API as detailed below.

Create a Merchant Bank Settlement Account via API

We will create a merchant settlement Bank Account

The following information is required for a Verified Bank Account. In this example we will be creating a Merchant Bank Account as a destination of your funds.

POST https://sandbox.kopokopo.com/merchant_bank_accounts
Content-Type: application/json
Accept: application/json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
  "account_number": "1234567890",
  "account_name": "Jane Merchant",
  "bank_branch_ref": "9ed38155-7d6f-11e3-83c3-5404a6144203",
  "settlement_method": "EFT"
}

HTTP/1.1 201 Created
Location: https://sandbox.kopokopo.com/api/v1/merchant_bank_accounts/AB443D36-3757-44C1-A1B4-29727FB3111C

settlement_account = {
  type: 'merchant_bank_account',
  account_name: 'account_name',
  account_number: 'account_number',
  bank_branch_ref: 'bank_branch_ref',
  settlement_method: 'settlement_method'
}

# Using K2Connecct - https://github.com/kopokopo/k2-connect-ruby (Recommended)
# Add a merchant mobile wallet
k2_settlement.add_settlement_account(settlement_account)
k2_settlement.location_url # => "https://sandbox.kopokopo.com/api/v1/merchant_bank_accounts/AB443D36-3757-44C1-A1B4-29727FB3111C"

var requestBody = {
  'accountName': 'John Doe',
  'bankBranchRef': 'c7f300c0-f1ef-4151-9bbe-005005aa3747',
  'accountNumber': '123456789',
  'settlementMethod': 'EFT',
  'accessToken': 'myRand0mAcc3ssT0k3n'
}

//  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-node (Recommended)
const TransferService = K2.TransferService

TransferService
  .createMerchantBankAccount(requestBody)
  .then( response => {
    console.log(response) // => 'https://sandbox.kopokopo.com/api/v1/merchant_bank_accounts/d76265cd-0951-e511-80da-0aa34a9b2388'
  })
  .catch( error => {
    console.log(error)
  })


# Using K2Connect - https://github.com/kopokopo/k2-connect-python (Recommended)
k2connect.initialize(CLIENT_ID, CLIENT_SECRET, BASE_URL)
transfer_service = k2connect.Transfers

# create verified settlement bank account
request_body = {
            "access_token": ACCESS_TOKEN,
            "settlement_method": 'RTS',
            "account_name": 'py_sdk_account_name',
            "account_number": 'py_sdk_account_number',
            "bank_branch_ref": 'bank_branch_reference'
        }
bank_settlement_account = transfer_service.add_bank_settlement_account(request_body)
bank_settlement_account # => "https://sandbox.kopokopo.com/api/v1/merchant_bank_accounts/AB443D36-3757-44C1-A1B4-29727FB3111C"

<?
//  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-php (Recommended)
$transfer = $K2->SettlementTransferService();

$response = $transfer->createMerchantBankAccount([
    'accountName' => 'John Doe',
    'bankBranchRef' => 'c7f300c0-f1ef-4151-9bbe-005005aa3747',
    'settlementMethod' => 'EFT',
    'accountNumber' => '123456789',
    'accessToken' => 'myRand0mAcc3ssT0k3n'
]);

if($response['status'] == 'success')
{
    echo "The resource location is:" . json_encode($response['location']);
}

// Not Supported
// This feature is not currently available in the Flutter SDK.
// Please use one of the other SDKs (PHP, Ruby, Python, NodeJs) or the REST API.

When the bank account is created, you’ll receive the merchant bank account URL in the location header.

Create a Merchant Settlement Mobile Wallet via API

We will create a Wallet

The following information is required for a Verified Mobile Wallet. In this example we will be creating a Merchant Mobile Wallet as a destination of your funds.

POST https://sandbox.kopokopo.com/api/v1/merchant_wallets
Content-Type: application/json
Accept: application/json
Authorization: Bearer 0Sn0W6kzNicvoWhDbQcVSKLRUpGjIdlPSEYyrHqrDDoRnQwE7Q
{
  "first_name": "first_name",
  "last_name": "last_name",
  "phone_number": "254999999999",
  "network": "Safaricom"
}

HTTP/1.1 201 Created
Location: https://sandbox.kopokopo.com/api/v1/merchant_wallets/AB443D36-3757-44C1-A1B4-29727FB3111C

settlement_account = { 
  type: 'merchant_wallet',
  first_name: 'first_name',
  last_name: 'last_name',
  phone_number: '+254999999999',
  network: 'Safaricom'
}

# Using K2Connecct - https://github.com/kopokopo/k2-connect-ruby (Recommended)
k2_settlement.add_settlement_account(settlement_account)
k2_settlement.location_url # => "https://sandbox.kopokopo.com/api/v1/merchant_wallets/AB443D36-3757-44C1-A1B4-29727FB3111C"

var requestBody = {
  firstName: 'Jane',
  lastName: 'Doe',
  network: 'Safaricom',
  phoneNumber: '+254999999999',
  accessToken: 'myRand0mAcc3ssT0k3n'
}

//  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-node (Recommended)
const TransferService = K2.TransferService

TransferService
  .createMerchantWallet(requestBody)
  .then( response => {
    console.log(response) // => 'https://sandbox.kopokopo.com/api/v1/merchant_wallets/d76265cd-0951-e511-80da-0aa34a9b2388'
  })
  .catch( error => {
    console.log(error)
  })


# Using K2Connect - https://github.com/kopokopo/k2-connect-python (Recommended)
k2connect.initialize(CLIENT_ID, CLIENT_SECRET, BASE_URL)
transfer_service = k2connect.Transfers

request_body ={
  "access_token": ACCESS_TOKEN,
  "first_name": 'py_sdk_first_name',
  "last_name": 'py_sdk_last_name',
  "phone_number": '+254911222538',
  "network": 'Safaricom'
}

# create verified settlement mobile account
mobile_settlement_account = transfer_service.add_mobile_wallet_settlement_account(request_body)
mobile_settlement_account # => "https://sandbox.kopokopo.com/api/v1/merchant_wallets/AB443D36-3757-44C1-A1B4-29727FB3111C"

<?
//  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-php (Recommended)
$transfer = $K2->SettlementTransferService();

$response = $transfer->createMerchantWallet([
  'firstName' => 'Jane',
  'lastName' => 'Doe',
  'network' => 'Safaricom',
  'phoneNumber' => '+254999999999',
  'accessToken' => 'myRand0mAcc3ssT0k3n'
]);

if($response['status'] == 'success')
{
    echo "The resource location is:" . json_encode($response['location']);
}


// Not Supported
// This feature is not currently available in the Flutter SDK.
// Please use one of the other SDKs (PHP, Ruby, Python, NodeJs) or the REST API.

When the mobile wallet is created, you’ll receive the merchant wallet URL in the location header.

© 2025 Kopo Kopo, Inc.