Create Payout Order
HTTP Request
API EndPoint
POST baseUrl + /api/payOut
Request Parameters
| Parameter | Required | Type | Description | Example |
|---|---|---|---|---|
accountName | Y | string(32) | Beneficiary Name | John |
accountNo | Y | string(32) | Beneficiary Account, End-customer phone number | 721323213 |
accountType | Y | int | Beneficiary Account Type | Please CheckPayout Account Type |
currency | Y | string(32) | Currency code | TZS |
amount | Y | decimal(20,0) | Amount (integer), minimum 500, maximum 5000000 | 10000 |
mchOrderNo | Y | string(32) | Merchant order number | 1386556787811426305 |
notifyUrl | Y | string(250) | webhooks (callback) address | https://merchant.com/webhooks |
nonceStr | Y | string(32) | Random string | 1863484722378907648 |
idType | N | string(32) | Beneficiary ID type | Ndistinction between types yet |
idCard | N | string(32) | Beneficiary ID number | Beneficiary ID number |
phone | N | string(32) | Beneficiary phonenumber | +255xxxxxxx |
email | N | string(32) | Beneficiary email | xyz@gamil.com |
remark | Y | string(32) | Order remarks | remark |
Request Example
curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"nonceStr":"xxxxxxxx","accountName":"jack","accountNo":"713512345","accountType":"1","currency":"TZS","amount":30000,"bankId":2,"mchOrderNo":"orderxxxxxxxxxxxxx","notifyUrl":"https://xxxxx.com/payOut/callback","idType":"1","idCard":"19870331141130000329","phone":"713512345","email":"jack@gmail.com","remark":"xxxxx"}'Response Parameters
| Parameter | Type | Description |
|---|---|---|
merchantId | int | MerchantId |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
amount | decimal(20,0) | Amount |
fee | decimal(20,0) | Order Fee |
orderStatus | string | Order status, Please checkPayout Order Status Enum |
Response Example
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "1002001",
"mchOrderNo": "orderxxxxxxxxxxxxx",
"orderNo": "PAYOUTxxxxxxxxxxxxxxxxxx",
"amount": 30000,
"fee": 0,
"orderStatus": "PROCESSING"
}
}{
"msg": "System_error",
"code": 500
}Query Payout Order
API EndPoint
POST baseUrl + /api/payOutQuery
Request Parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
mchOrderNo | N | string(32) | 1863484722378907648 | Merchant order number |
orderNo | N | string(32) | PAYOUT8551739282639106048 | Platform order number |
nonceStr | Y | string(32) | 9459931608 | Random string |
TIP
We recommend using orderNo (platform order number) first. At least one of the platform order number and the merchant order number must be passed.
Request Example
curl -L 'baseUrl/api/payOutQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1863484722378907648","nonceStr":"9459931608","orderNo":"PAYOUT8551739282639106048"}'Response Parameters
| Parameter | Type | Description |
|---|---|---|
merchantId | int | Merchant id |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
channelOrderNo | string(32) | Channel order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,2) | Fee |
orderStatus | string(32) | Payout Order Status Enum |
resultDesc | string(64) | Order Status Description |
completionTime | yyyy-MM-dd HH:mm:ss | Completion time |
Response Example
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "1002001",
"mchOrderNo": "1863484722378907648",
"orderNo": "PAYOUT8551739282639106048",
"amount": "60000",
"fee": "5150",
"orderStatus": "PAYING",
"completionTime": null,
"resultDesc": null
}
}Async Webhook Notification
The webhooks url is provided by the merchant
POST Merchant NotifyUrl
Webhook Request Parameters
| Parameter | Type | Description |
|---|---|---|
merchantId | int | Merchant id |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
channelOrderNo | string(32) | Channel order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,4) | Fee |
orderStatus | string(32) | Payout Order Status Enum |
resultDesc | string(64) | Order Status Description |
completionTime | yyyy-MM-dd HH:mm:ss | Completion time |
Webhook Request Example
curl -L 'merchant.com/webhools/payout' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":60000.00,"completionTime":"2024-12-02 08:42:54","fee":5150.0000,"mchOrderNo":"1863484722378907648","merchantId":"3002124","nonceStr":"1733103774518","orderNo":"PAYOUT8551739282639106048","orderStatus":"SUCCESS","payType":"11"}'{
"amount": 60000.0,
"completionTime": "2024-12-02 08:42:54",
"fee": 5150.0,
"mchOrderNo": "1863484722378907648",
"merchantId": "1002001",
"nonceStr": "1733103774518",
"orderNo": "PAYOUT8551739282639106048",
"orderStatus": "SUCCESS",
"payType": "11"
}{
"amount": 60000.0,
"completionTime": "2024-12-02 08:42:54",
"fee": 5150.0,
"mchOrderNo": "1863484722378907648",
"merchantId": "1002001",
"nonceStr": "1733103774518",
"orderNo": "PAYOUT8551739282639106048",
"orderStatus": "FAIL",
"resultDesc": "ACCOUNT NOT EXITS",
"payType": "11"
}Order result reversal processing
Please note that in rare cases, a payment order will have a result reversal notification. Your callback processing logic should consider the processing of success->failure and failure->success status.
Webhook Response Example
{
"status": "SUCCESS"
}TIP
When the webhooks response HTTP status code is 200, 301 or 302, we believe that the merchant has successfully received and processed the callback. For other statuses, we believe that the merchant has failed to process the callback.
After the webhooks fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the webhooks will be retried 10 times in total