Skip to main content

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:
  1. POST https://dev.payouts.lipad.io/v1/banks for bank payouts
  2. 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 :

  1. 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
  2. For production payouts replace dev on the payouts url with api .
  3. 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.

Payout Types

LIPAD supports payouts to the following destinations:

  1. Mobile Money Wallets
  2. Bank Accounts

Payouts Destination Types

LIPAD supports payouts to the following destinations. They are to be used as they are in the subsequent sections.

DestinationDescription
mobile_money_walletPayouts to individual momo wallets
bank_accountPayouts 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

OperatorDescription
AIRTEL_KENAirtel Money services Kenya
MPESA_KENM-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

ParameterDescriptionParameter TypeSample ValuesRequired
payout_referenceMerchant generated Payout ReferenceStringf4401bd2Yes
wallet_accountWallet Account to make payouts from (Obtain from https://dev.dashboard.lipad.io Wallets Section)StringFLO_LIPAD-ONE288MYes
service_codeLIPAD provided client-service code(Obtain from dashboard https://dev.dashboard.lipad.io Settings > Services )StringCLIENTX_PAYOUTSYes
recipient_nameName of the payment recipientStringSupplier JobYes
destination_typeLIPAD defined destination types. Refer to Destination types sectionEnummobile_money_walletYes
mobile_money_operatorThe MNO of the recipient mobile money wallet(Refer to Mobile Money Operators section)EnumMPESA_KENYes
source_currencyFloat account currencyStringKES (Currency ISO code)Yes
destination_currencyMobile money wallet currencyStringKES (Currency ISO Code)Yes
amountPayout amountNumber100Yes
payment_descriptionPayout narrationStringSalary PaymentYes

Response Body

{
"payout_reference": "ms8367839",
"response_code": 720,
"response_description": "Payout request has been accepted for processing"
}

Response Parameters Description

ParameterDescription
payout_referencePayout Originator generated payout reference
response_codeLIPAD Request acknowledgement code. Refer to Payouts Response Codes section
response_descriptionAcknowledgement 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

ParameterDescription
payout_referencePayout Originator generated payout reference
response_codeLIPAD Request acknowledgement code. Refer to Payouts Response Codes section
response_descriptionAcknowledgement description
error_codeRequest 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

ServiceDescription
pesalinkTransfer 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

ParameterDescriptionParameter TypeSample ValuesRequired
payout_referencePayout originator defined payout referenceStringysus-teyhd-udhYes
wallet_accountFloat Account name to make payouts from (Obtain from https://dev.dashboard.lipad.io Wallets Section)StringFLO_TEST-WT3SS5DYes
service_codeLIPAD provided client-service code(Obtain from dashboard https://dev.dashboard.lipad.io Settings > Services )StringCLIENTX_PAYOUTSYes
destination_typeLIPAD defined destination types. Refer to Destination types sectionEnumbank_accountYes
transfer_serviceBank transfer channel. Refer to Bank Payouts channelsEnumpesalinkYes
bank.nameName of the recipient bankStringTest BankYes
bank.codeTransfer service specific bank code. Refer to bank codes sectionString10Yes
bank.account_numberRecipient account numberString098678989789Yes
bank.phone_numberAccount holder phone numberString254700000000Yes
bank.country_codeBank domicile countryStringKENYes
transfer.amountPayout amountNumber100Yes
transfer.currencyRecipient account currencyStringKESYes

Response Body

{
"payout_reference": "ms8367839",
"response_code": 720,
"response_description": "Payout request has been accepted for processing"
}

Response Parameters Description

ParameterDescription
payout_referencePayout Originator generated payout reference
response_codeLIPAD Request acknowledgement code. Refer to Payouts Response Codes section
response_descriptionAcknowledgement 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

ParameterDescription
payout_referencePayout Originator generated payout reference
response_codeLIPAD Request acknowledgement code. Refer to Payouts Response Codes section
response_descriptionAcknowledgement description
error_codeRequest 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:

  1. All callbacks from LIPAD employ Basic authentication with the username and password registered alongside the callback url. See Basic Authentication rfc for guidance.
  2. Do not rely entirely on webhooks for payouts status. Use the LIPAD Payouts Status API to verify a Payout Status
  3. 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

ParameterParameter DescriptionScope
payout_referencePayout Originator defined reference provided at payout requestAll
destinationPayout intended destinationAll
data.payment_statusPayout result. See Payouts Payment status codes SectionAll
data.amountPayout amountAll
data.currencyPayout destination currencyAll
data.mobile_money_operatorRecipient momo wallet MNO namemobile_money_wallet
data.recipient_phone_numberMOMO wallet phone numbermobile_money_wallet
data.payout_descriptionPayout NarrationAll
data.createdDate payout was createsAll
data.updatedDate payout result was processedAll
data.mobile_network_operator_idLIPAD defined momo wallets providers IDs. Refer to Mobile Money Operators sectionmobile_money_wallet
data.messageResult descriptionAll
data.bank_nameRecipient bank namebank_account
data.bank_account_numberRecipient bank account numberbank_account
data.bank_pesalink_codeRecipient bank pesalink codebank_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

CodeDescription
720Payout request has been validated and accepted for processing
721Payout request is rejected for failing to meet certain criteria. See response_description and Error Code for more information
722Duplicate ignored code. A payout with the same response has already been submitted for processing
723Payout 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.

CodeDescription
INSUFFICIENT_BALANCEFloat account does not have sufficient funds to complete the payout request
SERVICE_NOT_ALLOWEDPayouts service is forbidden for the originating client
INVALID_ACCESS_TOKENInvalid authentication token
INVALID_DESTINATION_TYPEThe destination type specified is not supported by LIPAD Payouts service
INVALID_PHONE_NUMBERPhone number validation failed
INVALID_PAYMENT_METHODPayment method requested is not supported by LIPAD Payouts service
INVALID_WALLETWallet provided does not exist
UNAUTHORIZEDGeneric authentication failure
RESOURCE_NOT_FOUNDGeneric resource not found error
DUPLICATE_IGNOREDDuplicate submission errror
FAILEDGeneric service outage error

Payout-Payment Status Codes

See below descriptions for various payouts payment status.

CodeDescription
700Payout was processed successfully
701Payout processing failed
702Payout processing was reversed
703Payout processing is Pending
704Payout processing is Jammed - Requires Manual intervention