Merchant

Request for Merchant Bulk Transfer

For this request to work, the partner needs to have requested for whitelisting for their merchant account (i.e., payerAccountId)

This API is used by merchant accounts to disburse funds to internal (Choice) parties as well as external. 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 Pay Bill 1 for Pay Till	Optional
payeeSubAccount	string	For Paybill cases	Optional
currency	string	Allow KES only for now	Mandatory
amount	string	Amount to be transfered	Mandatory
paymentPurpose	string	Purpose of bank transfer (Use Pesalink Codes)	Optional
remark	string	Message to the beneficiary For transfers to Airtel Money, remark should not have any special characters and should be alphanumeric and max length is 64 characters.
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;
}