Process Payout

This endpoint allows you to initiate a single payout by providing recipient details, amount, currency, reference, and payout method.

💡 The payout process is completed in two steps

1. Initiate: Create the payout request.
2. Execute: Process and complete the payout transaction.

Step 1: Initiate Request

Create a payout request by providing recipient details, payout method, amount, currency, and a transaction reference. No funds are debited at this stage.

URL: {BaseURL}/initiates

Field Name	Structure/Key	Type	Description
Transaction ID	transactionId	string	This is the unique identifier for the transaction
Amount	amount	numeric string	The total value of the transaction to be processed, represented as a string of digits (e.g., "5000").
Wallet Currency	currency	string	Specifies the currency in which the transaction is conducted, typically represented using the ISO 4217 currency code (e.g., KSH, GHS, NGN etc). Note that this must correspond with the wallet you have created on your account.
Payment Method ID	payoutMethodId	string	A Brij-generated unique ID identifying the payment method used in the transaction.
Description	description	string	A brief note about the payment, such as the purpose of the transaction or details for the payer. This helps provide context for both the merchant and the customer
Account ID	accountId	string	The recipient’s account id for the payout either mobile money number, bank account ID
Sender	sender	Object	Contains detailed information about the sender
Sender Email	sender.email	string	The sender’s email
Sender Firstname	sender.firstname	string	The sender’s firstname
Sender Lastname	sender.lastname	string	The sender’s lastname
Sender Address	sender.address	string	Address of the sender
Sender’s Phone	sender.phone	string	Senders phone number
Beneficiary	beneficiary	object	Contains detailed information about the beneficiary
Beneficiary Firstname	beneficiary.firstname	string	The beneficiary’s firstname
Beneficiary Lastname	beneficiary.lastname	string	The beneficiary’s lastname
Beneficiary Phone	beneficiary.phone	string	The beneficiary’s phone number
Beneficiary Email	beneficiary.email	string	The beneficiary’s email

PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '{{BaseURL}}/initiates',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "transactionId": "Transaction ID",
    "amount": "Amount",
    "currency": "Wallet currency",
    "payoutMethodId": "Payment Method ID",
    "description": "Payout description",
    "accountId": "Account ID",
    "sender": {
        "firstname": "Sender Firstname",
        "lastname": "Sender Lastname",
        "email": "Sender Email",
        "address": "Sender Address",
        "phone": "Sender’s Phone"
    },
    "beneficiary": {
        "firstname": "Beneficiary Firstname",
        "lastname": "Beneficiary Lastname",
        "phone": "Beneficiary Phone",
        "email": "Beneficiary Email"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_SECRET_KEY'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Node

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{BaseURL}}/initiates',
  'headers': {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization: Bearer YOUR_SECRET_KEY'
  },
  body: JSON.stringify({
    "transactionId": "Transaction ID",
    "amount": "Amount",
    "currency": "Wallet Currency",
    "payoutMethodId": "Payment Method ID",
    "description": "Payout description",
    "accountId": "Account ID",
    "sender": {
      "firstname": "Sender Firstname",
      "lastname": "Sender Lastname",
      "email": "Sender Email",
      "address": "Sender Address",
      "phone": "Sender’s Phone"
    },
    "beneficiary": {
      "firstname": "Beneficiary Firstname",
      "lastname": "Beneficiary Lastname",
      "phone": "Beneficiary Phone",
      "email": "Beneficiary Email"
    }
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Curl

curl --location '{{BaseURL}}/initiates' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "transactionId": "Transaction ID",
    "amount": "Amount",
    "currency": "Wallet Currency",
    "payoutMethodId": "Payment Method ID",
    "description": "Payout description",
    "accountId": "Account ID",
    "sender": {
        "firstname": "Sender Firstname",
        "lastname": "Sender Lastname",
        "email": "Sender Email",
        "address": "Sender Address",
        "phone": "Sender’s Phone"
    },
    "beneficiary": {
        "firstname": "Beneficiary Firstname",
        "lastname": "Beneficiary Lastname",
        "phone": "Beneficiary Phone",
        "email": "Beneficiary Email"
    }
}'

{
    "status": 200,
    "data": {
        "accountId": "Account ID",
        "accountName": "Account Name",
        "brijTransactionId": "Brij Transaction ID",
        "transactiondId": "Transaction ID"
    },
    "message": "Payout process has been initiated"
}

Response

Step 2: Execute Request

The Execute step is used to process the payout. After a payout has been successfully initiated, you must call the execute endpoint to complete the transaction.

URL: {BaseURL}/executes

Field Name	Structure/Key	Type	Description
Transaction ID	transactionId	string	The unique transaction ID provided by the merchant during initiation

PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '{{BaseURL}}/executes',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "transactionId": "Transaction ID"
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_SECRET_KEY'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Node

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{BaseURL}}/executes',
  'headers': {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization: Bearer YOUR_SECRET_KEY'
  },
  body: JSON.stringify({
    "transactionId": "Transaction ID"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Curl

curl --location '{{BaseURL}}/executes' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data '{
    "transactionId": "Transaction ID"
}'

{
   "status": "1006",
   "data": {
       "brijTransactionId": "Brij Transaction ID",
       "transactiondId": "Transaction ID"
   },
   "message": "Payout transaction is being processed"
}

Response