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

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​

Authentication​

Create Float Account​

Float Account Balance​

Payout Types​

Payouts Destination Types​

Mobile Money Wallets Payouts​

Mobile Money Operators​

Bank Payouts​

Bank Payouts Channels​

Callbacks​

Payout Status​

Payouts Response Codes​

Payouts Error Codes​

Payout-Payment Status Codes​

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

Authentication

Create Float Account

Float Account Balance

Payout Types

Payouts Destination Types

Mobile Money Wallets Payouts

Mobile Money Operators

Bank Payouts

Bank Payouts Channels

Callbacks

Payout Status

Payouts Response Codes

Payouts Error Codes

Payout-Payment Status Codes