Merchant

Request for Merchant Bulk Transfer

For this request to work, the partner needs to have requested for their merchant account (i.e., payerAccountId] to be whitelisted. If it is, then verification is carried out, otherwise the request will be rejected.

This API is used by merchant accounts to disburse funds to Choice internal as well as external parties. All KES accounts of a whitelisted payment institution/service provider can be used for transitional fund settlement, and no OTP validation is required for transfers from that account to the beneficiaries, no matter which bank they are in.

POST /trans/batchTransitionalFundsDisbursement

Parameters

Fields	Type	Description	Required?
payerAccountId	string	Allow merchant account only Verification: the merchant account must be associated with a BaaS channel, otherwise the request will fail	Mandatory
orgBatchId	string	The unique batch ID generated by the merchant for this bulk payment request	Optional
beneficiaryArray	array	Array of the beneficiary details	Mandatory
Beneficiary Details/Array
orgTxId	string	The unique transaction ID generated by the merchant for this specific transaction.	Optional
payeeAccountName	string	Payee account name	Mandatory
payeeAccountId	string	Payee account number For Mpesa paybill/paytill, its the shortcode number	Mandatory
payeeBankCode	string	Refer to Choice BaaS Bank Code List Kenya Bank Code and Wallet Entities tab.	Mandatory
payeeType	string	0 for Individual 1 for business payeeType only be mandatory if payeeBankCode is M-PESA, otherwise it's optional.	Conditional
payType	string	0 for paybill 1 for paytill	Optional
payeeSubAccount	string	For paybill cases	Optional
currency	string	Allow KES only for now	Mandatory
amount	string	Amount to be transferd	Mandatory
paymentPurpose	string	Purpose of bank transfer (Use Pesalink Codes)	Optional
remark	string	Message to the beneficiary
payeeMobileForNotification	string	The mobile number of the beneficiary of the sms notification to remind beneficiary of this inbound.	Optional

Response

00000

{
  "orderId": ""
}

Result

Please refer to 0004 - Merchant Bulk Fund Transfer Result Notification

Query Merchant Bulk Transfer Details

POST /trans/getInternalBatchTransactionResult

<Use this endpoint to query merchant account details>

Parameters

Parameters	Type	Description	Is Required
orderId	string	The orderId returned by Choice	TRUE

Response

00000

{
  "orderId": "",
  "resultArray": [
    {
      "payeeAccountId": "",
      "payeeAccountName": "",
      "payerAccountId": "",
      "payeeType": "",
      "currency": "",
      "amount": "",
      "txId": "",
      "txStatus": "",
      "completedTime": ""
    }, {}
  ]
}

Query Merchant Account Details

POST /query/getMerchantAccountDetails

<Use this endpoint to query merchant account details>

Parameters

Parameters	Type	Description	Is Required
accountId	string	Merchant account number	TRUE

Response

00000

{
  "accountId": "",
  "accountName": "",
  "customerId": "",
  "currency": "",
  "accountType": "",
  "shortCode": "",
  "createTime": "",
  "balance": "", //available balance
  "frozenBalance": "",
  "dormantStatus": "", //0-Normal; 1-Dormant
  "abnormalStatus": "",//0-Normal; 1-Dormant; 2-Restricted; 3-Frozen
  "restrictStatus": "",//0-Normal; 1-Restrict In; 2-Restrict Out
  "freezeStatus": "", //0-Normal; 1-Frozen;
}