Payouts (B2C) API
Payouts API is an API used to make payments from a Business (Payouts) to Customers, Partners and Suppliers among others. Example use cases, among many
- Salary payments
- Lottery winnings payouts
- Financial institutions funds withdrawals
- Loans disbursements
- Suppliers payments
Below is the Payouts transactions sequence diagram:
Transaction flow description:
- The Payout originator (Client) sets all the required parameters for the payout request and sends it to:
- POST https://dev.payouts.lipad.io/v1/banks for bank payouts
- POST https://dev.payouts.lipad.io/v1/mobile-money for Mobile Money Payouts
- The request is validated and an acknowledgement is sent before proceeding with processing.
- LIPAD Payouts service receives the request, validates it and proceeds with processing
- LIPAD Payouts service then sends the payout result back to the payout originator (Client) via the callback URL created on our system. (URL Type: B2C Notifications)
- LIPAD Payouts service sends an SMS notification to the customer on the payments received.
NOTE :
- For you to use this API on production you are required to complete onboarding with LIPAD, fund your FLOAT Wallet and obtain production API Keys from https://dashboard.lipad.io Settings>API Keys section
- For production payouts replace dev on the payouts url with api .
- For sandbox testing, test funds will be availed in your sandbox Float account. Use sandbox API Keys from https://dev.dashboard.lipad.io Settings>API Keys section
HINT: See Our POSTMAN COLLECTION for guidance.
Authentication
All requests made to LIPAD Payouts APIs will require token authentication. Authentication requests are send to:
POST https://dev.lipad.io/v1/auth
Authentication Request body
{
"consumer_key": "Xjpe948ixgdhlUrRNlOwc",
"consumer_secret": "hNjZK2JVm4Uc1whgskjsiY9G"
}
Response Body
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIxNiIsImRlc2lnbmF0aW9uIjoiQXBpIFVzZXIiLCJhdXRob3JpemVkIjp0cnVlLCJpYXQiOjE2Nzc3MDY4ODgsImV4cCI6MTY3NzcxMjg4OH0.kADugWTjIrXokYYhDTXg4idmsLy6pUTv6N0Hi-ZMkrI",
"expiresIn": 6000
}
Use the token returned under access_token for all requests made to the Payouts APIs. The token should be passed as a Request Header x-access-token
. The token will be valid for up to 1 hour.
Create Float Account
Endpoints:
- Sandbox: POST
https://dev.payouts.lipad.io/v1/accounts
- Live: POST
https://api.payouts.lipad.io/v1/accounts
Request Payload
{
"name":"Fred Delivery",
"currency":"KES"
}
Request Parameters Description
Parameter | Description |
---|---|
name | Name of the float account |
currency | Float account currency |
Response Payload
{
"name": "Test Account Creation",
"code": "FLO_DEMO_KES_XJB",
"account_number": "10000198"
}
Response parameters definition
Parameter | Description |
---|---|
name | Name of the float account |
code | Float account unique code for use with payouts API requests |
account_number | Float account number |
Float Account Balance
Endpoints:
- Sandbox: GET
https://dev.payouts.lipad.io/v1/accounts/{{account_number}}/balance
- Live: GET
https://api.payouts.lipad.io/v1/accounts/{{account_number}}/balance
Float account balance request response
{
"balance": "110.00",
"currency":"KES",
"status":"ACTIVE"
}
Response parameters definition
Parameter | Description |
---|---|
balance | Float account available balance |
currency | Float account currency |
status | Float account balance |
Payout Types
LIPAD supports payouts to the following destinations:
- Mobile Money Wallets
- Bank Accounts
Payouts Destination Types
LIPAD supports payouts to the following destinations. They are to be used as they are in the subsequent sections.
Destination | Description |
---|---|
mobile_money_wallet | Payouts to individual momo wallets |
bank_account | Payouts to individual bank accounts |
Mobile Money Wallets Payouts
These a disbursements made to customers mobile money wallets accounts. LIPAD supports payouts to the following mobile money wallets service providers:
- Safaricom M-PESA
- Airtel Money
Mobile Money Operators
These are the supported Mobile Money wallet services providers
Operator | Description |
---|---|
AIRTEL_KEN | Airtel Money services Kenya |
MPESA_KEN | M-PESA Services in Kenya |
Mobile Money Payout Request Body
{
"payout_reference": "b2-18-9839",
"wallet_account": "FLO_TEST-ONE288M",
"service_code": "<client service code>",
"recipient_name": "Test Payee",
"destination_type": "mobile_money_wallet",
"recipient_phone_number": "254******484",
"mobile_money_operator": "AIRTEL_KEN",
"source_currency": "KES",
"destination_currency": "KES",
"amount": 200,
"payment_description": "Test transaction"
}
Request Parameters Description
Parameter | Description | Parameter Type | Sample Values | Required |
---|---|---|---|---|
payout_reference | Merchant generated Payout Reference | String | f4401bd2 | Yes |
wallet_account | Wallet Account to make payouts from (Obtain from https://dev.dashboard.lipad.io Wallets Section) | String | FLO_LIPAD-ONE288M | Yes |
service_code | LIPAD provided client-service code(Obtain from dashboard https://dev.dashboard.lipad.io Settings > Services ) | String | CLIENTX_PAYOUTS | Yes |
recipient_name | Name of the payment recipient | String | Supplier Job | Yes |
destination_type | LIPAD defined destination types. Refer to Destination types section | Enum | mobile_money_wallet | Yes |
mobile_money_operator | The MNO of the recipient mobile money wallet(Refer to Mobile Money Operators section) | Enum | MPESA_KEN | Yes |
source_currency | Float account currency | String | KES (Currency ISO code) | Yes |
destination_currency | Mobile money wallet currency | String | KES (Currency ISO Code) | Yes |
amount | Payout amount | Number | 100 | Yes |
payment_description | Payout narration | String | Salary Payment | Yes |
Response Body
{
"payout_reference": "ms8367839",
"response_code": 720,
"response_description": "Payout request has been accepted for processing"
}
Response Parameters Description
Parameter | Description |
---|---|
payout_reference | Payout Originator generated payout reference |
response_code | LIPAD Request acknowledgement code. Refer to Payouts Response Codes section |
response_description | Acknowledgement description |
Error Response Body
{
"payout_reference": "ms8367839",
"response_code": 722,
"response_description": "Payout with that reference exists",
"error_code": "DUPLICATE_IGNORED"
}
Error Response Parameters Description
Parameter | Description |
---|---|
payout_reference | Payout Originator generated payout reference |
response_code | LIPAD Request acknowledgement code. Refer to Payouts Response Codes section |
response_description | Acknowledgement description |
error_code | Request error code. Refer to Payouts Error Codes section |
Bank Payouts
These are payouts made to individual bank accounts. LIPAD supports payments to all Pesalink participating banks.
Bank Payouts Channels
Below are the Bank transfer services supported by LIPAD
Service | Description |
---|---|
pesalink | Transfer to all Pesalink participating bank accounts |
A list of all Pesalink participating banks and their pesalink codes can be obtained from this endpoint:
GET https://dev.payouts.lipad.io/pesalink-banks
Request body
{
"payout_reference": "ms8367839",
"wallet_account": "FLO_TEST-WT3SS5D",
"service_code": "<client service code>",
"destination_type": "bank_account",
"transfer_service": "pesalink",
"bank": {
"name": "Test Bank",
"code": "AD",
"account_name": "Test Payee",
"account_number": "082********783849",
"phone_number": "254******2689",
"country_code": "KEN"
},
"transfer": {
"amount": 100,
"currency": "KES",
"description": "Test bank transfer"
}
}
Request Parameters Description
Parameter | Description | Parameter Type | Sample Values | Required |
---|---|---|---|---|
payout_reference | Payout originator defined payout reference | String | ysus-teyhd-udh | Yes |
wallet_account | Float Account name to make payouts from (Obtain from https://dev.dashboard.lipad.io Wallets Section) | String | FLO_TEST-WT3SS5D | Yes |
service_code | LIPAD provided client-service code(Obtain from dashboard https://dev.dashboard.lipad.io Settings > Services ) | String | CLIENTX_PAYOUTS | Yes |
destination_type | LIPAD defined destination types. Refer to Destination types section | Enum | bank_account | Yes |
transfer_service | Bank transfer channel. Refer to Bank Payouts channels | Enum | pesalink | Yes |
bank.name | Name of the recipient bank | String | Test Bank | Yes |
bank.code | Transfer service specific bank code. Refer to bank codes section | String | 10 | Yes |
bank.account_number | Recipient account number | String | 098678989789 | Yes |
bank.phone_number | Account holder phone number | String | 254700000000 | Yes |
bank.country_code | Bank domicile country | String | KEN | Yes |
transfer.amount | Payout amount | Number | 100 | Yes |
transfer.currency | Recipient account currency | String | KES | Yes |
Response Body
{
"payout_reference": "ms8367839",
"response_code": 720,
"response_description": "Payout request has been accepted for processing"
}
Response Parameters Description
Parameter | Description |
---|---|
payout_reference | Payout Originator generated payout reference |
response_code | LIPAD Request acknowledgement code. Refer to Payouts Response Codes section |
response_description | Acknowledgement description |
Error Response Body
{
"payout_reference": "ms8367839",
"response_code": 722,
"response_description": "Payout with that reference exists",
"error_code": "DUPLICATE_IGNORED"
}
Error Response Parameters Description
Parameter | Description |
---|---|
payout_reference | Payout Originator generated payout reference |
response_code | LIPAD Request acknowledgement code. Refer to Payouts Response Codes section |
response_description | Acknowledgement description |
error_code | Request error code. Refer to Payouts Error Codes section |
Callbacks
After Payout processing is completed, LIPAD Payouts service sends the result to the callback endpoint registered for B2C Notifications. NOTE:
- All callbacks from LIPAD employ Basic authentication with the username and password registered alongside the callback url. See Basic Authentication rfc for guidance.
- Do not rely entirely on webhooks for payouts status. Use the LIPAD Payouts Status API to verify a Payout Status
- Acknowledge webhook receipt with a 200 http status code. Any non 200 Status code will be treated as a non-acknowledge and webhooks will be re-tried 3 times over the next 48 hours after which no further webhooks will be sent.
Bank Payout Result Body
{
"payout_reference": "ms83-367839",
"destination": "bank_account",
"data": {
"payment_status": 700,
"amount": "100.00",
"currency": "KES",
"bank_name": "Test Bank",
"bank_account_number": "08292******849",
"payout_description": "Test bank transfer",
"created": "2023-03-02T05:17:36.802Z",
"updated": "2023-03-02T05:17:39.386Z",
"bank_pesalink_code": "AD",
"message": "Payout was processed successfully"
}
}
Mobile Money Payout Result Body
{
"payout_reference": "b2-18-o39",
"destination": "mobile_money_wallet",
"data": {
"payment_status": 700,
"amount": "50.00",
"currency": "KES",
"mobile_money_operator": "Mpesa Kenya",
"recipient_phone_number": "254*****484",
"payout_description": "Airtime allowance",
"created": "2023-03-01T14:37:27.415Z",
"updated": "2023-03-01T14:37:27.583Z",
"mobile_network_operator_id": "MPESA_KEN",
"message": "Payout was processed successfully"
}
}
Payout Result Parameters description
Parameter | Parameter Description | Scope |
---|---|---|
payout_reference | Payout Originator defined reference provided at payout request | All |
destination | Payout intended destination | All |
data.payment_status | Payout result. See Payouts Payment status codes Section | All |
data.amount | Payout amount | All |
data.currency | Payout destination currency | All |
data.mobile_money_operator | Recipient momo wallet MNO name | mobile_money_wallet |
data.recipient_phone_number | MOMO wallet phone number | mobile_money_wallet |
data.payout_description | Payout Narration | All |
data.created | Date payout was creates | All |
data.updated | Date payout result was processed | All |
data.mobile_network_operator_id | LIPAD defined momo wallets providers IDs. Refer to Mobile Money Operators section | mobile_money_wallet |
data.message | Result description | All |
data.bank_name | Recipient bank name | bank_account |
data.bank_account_number | Recipient bank account number | bank_account |
data.bank_pesalink_code | Recipient bank pesalink code | bank_account |
Payout Status
For status verification or in the event when result callbacks fail, the Payout Status API can be employed. Requests to check payout status are sent to
GET https://dev.payouts.lipad.io/v1/status/{payout_reference}
Payout Status Response Body (Bank Payout)
{
"payout_reference": "ms83-367839",
"destination": "bank_account",
"data": {
"payment_status": 700,
"amount": "100.00",
"currency": "KES",
"bank_name": "Test Bank",
"bank_account_number": "08292******3783849",
"payout_description": "Test bank transfer",
"created": "2023-03-02T05:17:36.802Z",
"updated": "2023-03-02T05:17:39.386Z",
"bank_pesalink_code": "AD",
"message": "Payout was processed successfully"
}
}
Payout Status Response Body (Mobile Money)
{
"payout_reference": "b2-18-9839",
"destination": "mobile_money_wallet",
"data": {
"payment_status": 700,
"amount": "200.00",
"currency": "KES",
"mobile_money_operator": "Airtel Kenya",
"recipient_phone_number": "254*****484",
"payout_description": "Test transaction",
"created": "2023-03-02T08:34:48.913Z",
"updated": "2023-03-02T08:34:53.501Z",
"mobile_network_operator_id": "AIRTEL_KEN",
"message": "Payout was processed successfully"
}
}
Payout Status Response Parameters Description NOTE: The Payout Status API Response Parameters are the same as callback result Parameters. Please refere to the Callbacks section for guidance
Payouts Response Codes
See below definition for the payout request-response codes
Code | Description |
---|---|
720 | Payout request has been validated and accepted for processing |
721 | Payout request is rejected for failing to meet certain criteria. See response_description and Error Code for more information |
722 | Duplicate ignored code. A payout with the same response has already been submitted for processing |
723 | Payout record not found for Status API - No payout record matches the reference provided |
Payouts Error Codes
See below definitions for payouts error codes. These error codes serve to give more information on why a payout request was rejected.
Code | Description |
---|---|
INSUFFICIENT_BALANCE | Float account does not have sufficient funds to complete the payout request |
SERVICE_NOT_ALLOWED | Payouts service is forbidden for the originating client |
INVALID_ACCESS_TOKEN | Invalid authentication token |
INVALID_DESTINATION_TYPE | The destination type specified is not supported by LIPAD Payouts service |
INVALID_PHONE_NUMBER | Phone number validation failed |
INVALID_PAYMENT_METHOD | Payment method requested is not supported by LIPAD Payouts service |
INVALID_WALLET | Wallet provided does not exist |
UNAUTHORIZED | Generic authentication failure |
RESOURCE_NOT_FOUND | Generic resource not found error |
DUPLICATE_IGNORED | Duplicate submission errror |
FAILED | Generic service outage error |
Payout-Payment Status Codes
See below descriptions for various payouts payment status.
Code | Description |
---|---|
700 | Payout was processed successfully |
701 | Payout processing failed |
702 | Payout processing was reversed |
703 | Payout processing is Pending |
704 | Payout processing is Jammed - Requires Manual intervention |