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

Transaction flow description:

• The Payout originator (Client) sets all the required parameters for the payout request and sends it to:

1. POST https://sandbox.api.gateway.kasapay.com/v1/payouts/initiate for local payouts
2. POST https://sandbox.api.gateway.kasapay.com/v1/payouts/imt/initiate for International Money Transfers

• The request is validated and an acknowledgement is sent before proceeding with processing.
• GATEWAY Payouts service receives the request, validates it and proceeds with processing
• GATEWAY 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)
• GATEWAY 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, fund your FLOAT Wallet and obtain production API Keys from https://dashboard.kasapay.com Settings>API Keys section
2. For sandbox testing, test funds will be availed in your sandbox Float account. Use sandbox API Keys from https://sandbox.dashboard.kasapay.com Settings>API Keys section

Authentication

All requests made to GATEWAY Payouts APIs will require token authentication. Authentication requests are send to:

POST https://sandbox.api.gateway.kasapay.com/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:

1. Sandbox: POST https://sandbox.api.gateway.kasapay.com/v1/accounts
2. Live: POST https://api.gateway.kasapay.com/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:

1. Sandbox: GET https://sandbox.api.gateway.kasapay.com/v1/accounts/{{account_number}}/balance
2. Live: GET https://api.gateway.kasapay.com/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

Payouts Destination Types

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

Destination	Description
MOBILE	Payouts to MOBILE MONEY wallets
BANK	Payouts to bank accounts

Payout Types

The gateway supports payouts to the following destinations:

1. Local B2C Payouts
2. International Money Transfer

Local B2C Payouts

These are disbursements made to Kenyan mobile money wallets accounts.

Send Money Locally This endpoint allows you to submit a local payout request

Endpoint
    https://sandbox.api.gateway.kasapay.com/v1/payouts/initiate
Method
    POST
Header
    key : x-access-token
    value : <access_token_from_auth>

Request Body

{
    "payout_reference": "134526781672", //Required
     "wallet_account": "TEST", //Required
    "service_code": "TEST", //Required
    "recipient_first_name": "John", // Required
    "recipient_last_name": "Doe", // Required
    "destination_type": "MOBILE", // Required MOBILE or BANK
    "destination_name":"MPESA_KEN", // Required
    "recipient_phone_number": "254*******98", // Required
    "recipient_account_number": "25626252525",// Required
    "recipient_bank_code":"XYZ", //Required if destination_type is BANK
    "recipient_account_name": "John Doe", // Required
    "source_currency":"KES", // Required
    "destination_currency": "KES", // Required
    "exchange_rate": "1", // Required
    "sender_amount": "100", // Required
    "recipient_amount": "100", // Required
    "payment_description": "Salary Payment", // Required
    "callback_url": "https://payouts.com/result" // Required
}

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.kasapay.com Wallets Section)	String	KASAPAYWALLET	Yes
service_code	GATEWAY provided client-service code(Obtain from dashboard https://dev.dashboard.kasapay.com Settings > Services )	String	CLIENTX_PAYOUTS	Yes
recipient_first_name	Name of the payment recipient	String	Supplier Job	Yes
recipient_last_name	Recipient First Name	String	John	Yes
destination_type	GATEWAY 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
sender_amount	Total Amount to be sent to receiver	Number	100	Yes
exchange_rate	FX Rates	Double	1	Yes
recipient_amount	The amount the recipient recipient	Double	100	Yes
payment_description	Payout narration	String	Salary Payment	Yes
callback_url	Endpoint to receive transaction result	string	https://payouts.com/result	Yes

Response Body

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

Response Parameters Description

Parameter	Description
payout_reference	Payout Originator reference
response_code	GATEWAY 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	GATEWAY Request acknowledgement code. Refer to Payouts Response Codes section
response_description	Acknowledgement description
error_code	Request error code. Refer to Payouts Error Codes section

International Money Transfers

These are are cross border remmitance requests

Endpoint
    https://sandbox.api.gateway.kasapay.com/v1/payouts/imt/initiate
Method
    POST
Header
    key : Authorization
    value : <access_token_from_auth>

Request body

{
  "payout_reference": "123245617892", //Required
  "wallet_account": "TEST", // Required
  "service_code": "TEST", // Required
  "sender_first_name": "Fred", // Required
  "sender_middle_name": "", // Optional
  "sender_last_name": "Mtembezi", // Required
  "sender_type": "INDIVIDUAL", // Required INDIVIDUAL or COMPANY
  "sender_document_type": "National ID", // Optional
  "sender_document_number": "xxxxxxxxxx", // Optional
  "sender_country_code": "KEN", // Required
  "sender_phone_number": "25400000000", // Optional
  "recipient_first_name": "Fred", // Optional
  "recipient_middle_name": "", // Optional
  "recipient_last_name": "Mtembezi", // Optional
  "recipient_type": "INDIVIDUAL", // Required INDIVIDUAL or COMPANY
  "recipient_document_type": "ID", // Optional
  "recipient_document_number": "xxxxxxxxx", // Optional
  "recipient_phone_number": "25400000000", // Required
  "recipient_account_number": "25400000000", // Required
  "recipient_account_name": "John Mtembezi", // Required
  "recipient_occupation": "Student", // Required
  "destination_type": "MOBILE", // Required MOBILE Or BANK
  "destination_name": "MPESA_KEN", // Required
  "recipient_bank_code": "TEST", //Required if destination type is BANK
  "source_currency": "KES", // Required
  "destination_currency": "KES", // Required
  "income_source": "Employment", // Required
  "fund_purpose": "SCHOOL FEES", // Required
  "exchange_rate": "1", // Required
  "sender_amount": "100", // Required
  "recipient_amount": "100", // Required
  "payment_description": "School fees disbursement", // Required
  "callback_url": "https://payouts.com/result" // Optional
}

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.kasapay.com Wallets Section)	String	FLO_TEST-WT3SS5D	Yes
service_code	GATEWAY provided client-service code(Obtain from dashboard https://dev.dashboard.kasapay.com Settings > Services )	String	CLIENTX_PAYOUTS	Yes
destination_type	GATEWAY defined destination types. Refer to Destination types section	Enum	bank_account	Yes
destination_name	Terminal service provider name	String	MPESA	Yes
sender_first_name	Sender first name	String	John	Yes
sender_middle_name	Sender Middle Name	String	Doe	No
sender_last_name	Sender Last Name	String	Doe	Yes
sender_type	Sender Type	String	INDIVIDUAL	Yes
sender_document_type	Type of document for sender identification	String	National ID	No
sender_document_number	Document number for sender document type	String	12345	No
sender_country_code	Country code for sender	String	KES	Yes
sender_phone_number	Phone number of the sender	String		Yes
recipient_first_name	Recipient first name	String	John	Yes
recipient_middle_name	Recipient middle name	String	John	NO
recipient_last_name	Recipient last name	String	John	Yes
recipient_type	Recipient category	String	INDIVIDUAL	Yes
recipient_document_type	Type of document for identifying the payer	String	National ID	NO
recipient_document_type	Document number for the recipient document type	String	XXXXXXXX	NO
recipient_phone_number	Phone number of the recipient	String	010000000	Yes
recipient_account_number	Account number of the recipient	String	010000000	Yes
recipient_account_name	Full name of the recipient	String	Fred Mtembezi	Yes
recipient_occupation	Occupation of the recipient	String	Student	Yes
destination_type	Type of destination (e.g., bank or mobile wallet)	String	MOBILE	Yes
destination_name	Name of the destination (e.g., M-Pesa, Bank name)	String	MPESA_KEN	Yes
recipient_bank_code	Bank code of the recipient's bank (if applicable)	String	KENBANK	Yes
source_currency	Currency of the sender's transaction	String	KES	Yes
destination_currency	Currency in which the recipient receives the funds	String	KES	Yes
income_source	Source of income for the sender	String	Employment	Yes
fund_purpose	Purpose of the funds being sent	String	SCHOOL FEES	Yes
exchange_rate	Exchange rate applied to the transaction	String	1	Yes
sender_amount	Amount being sent by the sender	String	100	Yes
recipient_amount	Amount received by the recipient after conversion	String	100	Yes
payment_description	Description of the payment	String	Payment for pending bills	Yes
callback_url	URL where transaction status updates will be sent	String	https://payouts.api/result	Yes

Response Body

{
    "payout_reference": "123245617892",
    "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	GATEWAY 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	GATEWAY 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 a disbursement processing is completed, the disbursements service sends the result to the callback endpoint provided.

NOTE:

1. Do not rely entirely on webhooks for payouts status. Use the GATEWAY Payouts Status API to verify a Payout Status.
2. 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.

Callback Payload

{
  "payout_reference": "ms83-367839",
  "destination": "bank_account",
  "data": {
    "reference":"TLZYTFVAGHG"
    "payment_status": 700,
    "amount": "100.00",
    "currency": "KES",
    "account_number": "08292******849",
    "destination_name":"BANKX",
    "payout_description": "Test bank transfer",
    "transaction_time": "2023-03-02T05:17:36.802Z",
    "bank_code": "AD",
    "result_description": "Payout was processed successfully"
    "recipient_first_name": "Doe",
    "recipient_middle_name":"",
    "recipient_last_name": "John",
    "recipient_phone_number":"01000000000"
  }
}

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.recipient_phone_number	MOMO wallet phone number	All
data.recipient_first_name	First name of Recipient	All
data.recipient_middle_name	Recipient middle name	All
data.recipient_last_name	Last name of recipient	All
data.payout_description	Payout Narration	All
data.transaction_time	Date payout was created	All
data.destination_name	GATEWAY defined momo wallets providers IDs. Refer to Mobile Money Operators section	All
data.message	Result description	All
data.account_number	Recipient bank or Mobile Money account number	All
data.bank_code	Recipient bank pesalink code	BANK

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://sandbox.api.gateway.kasapay.com/v1/payouts/{payout_reference}/status

Payout Status Response Body

{
  "payout_reference": "ms83-367839",
  "destination": "bank_account",
  "data": {
    "reference":"TLZYTFVAGHG"
    "payment_status": 700,
    "amount": "100.00",
    "currency": "KES",
    "account_number": "08292******849",
    "destination_name":"BANKX",
    "payout_description": "Test bank transfer",
    "transaction_time": "2023-03-02T05:17:36.802Z",
    "bank_code": "AD",
    "result_description": "Payout was processed successfully"
    "recipient_first_name": "Doe",
    "recipient_middle_name":"",
    "recipient_last_name": "John",
    "recipient_phone_number":"01000000000"
  }
}

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 GATEWAY Payouts service
INVALID_PHONE_NUMBER	Phone number validation failed
INVALID_PAYMENT_METHOD	Payment method requested is not supported by GATEWAY 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