B2B API

This section outlines the structure and requirements for initiating B2B payouts, handling callbacks, and querying transaction status. The API facilitates seamless business-to-business transactions by enabling payments to various recipient types, such as paybills, tills, or bank accounts.

Endpoints

• Payout Request: POST /v1/payouts/b2b/initiate
• Authentication: POST /v1/auth
• Status Query: GET /v1/payouts/b2b/{payout_reference}/status

Description

The B2B Payouts API allows businesses to send funds to another business or entity. The payout request payload specifies the recipient, amount, and other transaction details. Authentication is required via an access token, and transaction status updates are delivered via callbacks or status queries.

Authentication

All requests to the B2B Payouts API require an access token obtained by exchanging a consumer_key and consumer_secret via the authentication endpoint. The access token is passed in the x-access-token header for subsequent requests.

Authentication Endpoint

POST /v1/auth

Authentication Request Payload

{
    "consumer_key": "<your_consumer_key>",
    "consumer_secret": "<your_consumer_secret>"
}

Authentication Field Descriptions

Field	Type	Required	Description
consumer_key	String	Yes	Unique key
consumer_secret	String	Yes	Secret key

Example Authentication Request

curl -X POST https://sandbox.api.gateway.kasapay.com/v1/auth \
-H "Content-Type: application/json" \
-d '{
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret"
}'

Authentication Response

Example Success Response

{
    "access_token": "xyz789abc123",
    "expiresIn": 3600
}

Example Error Response

{
    "statusCode": 400,
    "message": "Invalid Authentication Credentials",
    "error": "Bad Request"
}

Using the Access Token

Include the access token in the x-access-token header for all API requests.

Header Name	Value	Description
x-access-token	<access_token>	Access token obtained from /v1/auth.

Authentication Notes

• Obtaining Credentials: From the merchant portal, navigate to My Business > API Keys.
• Token Expiry: The access_token is valid for up to one hour. Re-authenticate to obtain a new token after expiry.
• Security: Keep consumer_key, consumer_secret, and access_token confidential. Do not expose them in client-side code or public repositories.

Payout Request Payload

The following JSON payload is required to initiate a B2B payout:

{
    "payout_reference": "145245624652",
    "service_code": "SERVICE_CODE",
    "payment_account_reference": "0101",
    "recipient_name": "Test Limited",
    "recipient_type": "PAYBILL",
    "recipient_account_number": "5656",
    "amount": "10",
    "payment_description": "Test",
    "payment_method": "MPESA_B2B",
    "currency_code": "KES",
    "country_code": "KEN",
    "callback_url": "https://payments.x.xyz/result"
}

Payout Request Field Descriptions

Field	Type	Required	Description
payout_reference	String	Yes	Unique reference ID for the transaction (e.g., 145245624652).
service_code	String	Yes	Code identifying the service On KASAPAY (e.g., 12346).
payment_account_reference	String	Yes	Reference to the recipient's account (e.g., account xyz).
recipient_name	String	Yes	Name of the recipient entity (e.g., Test Limited).
recipient_type	String	Yes	Type of recipient account. Valid values: PAYBILL, TILL, BANK_ACCOUNT_NUMBER.
recipient_account_number	String	Yes	Account number of the recipient (e.g., PAYBILL_NUMBER).
amount	String	Yes	Transaction amount (e.g., 10).
payment_description	String	Yes	Brief description of the payment (e.g., Test).
payment_method	String	Yes	Method of payment (e.g., MPESA_B2B for PAYBILL and TILL and BANK for BANK_ACCOUNT_NUMBER).
currency_code	String	Yes	ISO 4217 currency code (e.g., KES, USD)
country_code	String	Yes	ISO 3166-1 alpha-3 country code (e.g., KEN)
callback_url	String	Yes	URL to receive transaction status updates (e.g., https://payments.x.xyz/result).

Example Payout Request

curl -X POST https://sandbox.api.gateway.kasapay.com/v1/payouts/b2b/initiate \
-H "Content-Type: application/json" \
-H "x-access-token: xyz789abc123" \
-d '{
    "payout_reference": "ms83-367839",
    "service_code": "12346",
    "payment_account_reference": "666666",
    "recipient_name": "Test Limited",
    "recipient_type": "BANK_ACCOUNT_NUMBER",
    "recipient_account_number": "08292******849",
    "amount": "100.00",
    "payment_description": "Test bank transfer",
    "payment_method": "MPESA_B2B",
    "currency_code": "KES",
    "country_code": "KEN",
    "callback_url": "https://example.com/callback"
}'

Payout Response

Upon successful submission, the API returns a confirmation of the transaction request.

Example Success Response

{
    "payout_reference": "a99658d5-3100-45e6-9649-b311d41ab615",
    "response_code": 720,
    "response_description": "Payout request has been accepted for processing"
}

Example Error Response

{
    "response_code": 721,
    "response_description": "Invalid Service",
    "error_code": "SERVICE_NOT_ALLOWED"
}

Callback Handling

The API sends asynchronous updates about the transaction status to the callback_url provided in the payout request. The callback payload is also returned when querying the transaction status. Ensure the callback URL is publicly accessible and can handle POST requests.

Callback/Status Query Payload

{
  "payout_reference": "ms83-367839",
  "transaction_id": "10001",
  "payment_reference":"TQLXMNSBBYSF",
  "wallet_account":"784789474",
  "destination": "bank_account",
  "payment_status": 700,
  "amount": "100.00",
  "currency": "KES",
  "account_number": "08292******849",
  "destination_name": "BANKX",
  "description": "Test bank transfer",
  "transaction_time": "2023-03-02T05:17:36.802Z",
  "account_balance": "100.00",
  "result_description": "Payout was processed successfully"
}

Callback/Status Query Field Descriptions

Field	Type	Description
payout_reference	String	Unique reference ID from the payout request (e.g., ms83-367839).
transaction_id	String	Unique transaction ID assigned by the API (e.g., 10001).
payment_reference	String	Unique transaction ID assigned by the payment processor (e.g., TQLXMNSBBYSF).
wallet_account	String	System float account used to process the transaction (e.g., TQLXMNSBBYSF).
destination	String	Type of destination (e.g., BANK_ACCOUNT_NUMBER, PAYBILL, TILL).
payment_status	Number	Payment Status code of the transaction (e.g., 700 for success. Refer to Payment status codes section for more payment status codes).
amount	String	Transaction amount (e.g., 100.00).
currency	String	ISO 4217 currency code (e.g., KES).
account_number	String	Recipient's account number (e.g., 08292******849).
destination_name	String	Name of the destination entity (e.g., BANKX).
description	String	Description of the payout (e.g., Test bank transfer).
transaction_time	String	ISO 8601 timestamp of the transaction (e.g., 2023-03-02T05:17:36.802Z).
account_balance	String	Payer's remaining balance after the transaction (e.g., 100.00).
result_description	String	Outcome of the transaction (e.g., Payout was processed successfully).

Payment Status Codes

Code	Description
700	Payout was processed successfully.
701	Payout failed.(check result_description).
702	Payout was reversed.
703	Payout is Pending
704	Payout is Jammed
705	Payout was refunded

Handling Callbacks

• Acknowledge Receipt: Respond with a 200 OK status to confirm receipt of the callback.
• Validate Payload: Verify if payout_reference matches your records.
• Retry Mechanism: The API may retry callbacks if no 200 OK response is received. Implement idempotency using payout_reference to avoid duplicate processing.

Status Query

To check the status of a payout, use the status query endpoint, which returns the same payload structure as the callback.

Endpoint

GET /v1/payouts/b2b/{payout_reference}/status

Query Parameters

Parameter	Type	Required	Description
payout_reference	String	Yes	The unique transaction reference (e.g., 12345678999).

Example Status Query Request

curl -X GET https://sandbox.api.gateway.kasapay.com/v1/payouts/b2b/{payout_reference}/status \
-H "x-access-token: xyz789abc123"

Example Status Query Response

{
  "payout_reference": "ms83-367839",
  "transaction_id": "10001",
  "payment_reference":"TQXLMNOPSB",
  "wallet_account":"784789474",
  "destination": "bank_account",
  "payment_status": 700,
  "amount": "100.00",
  "currency": "KES",
  "account_number": "08292******849",
  "destination_name": "BANKX",
  "description": "Test bank transfer",
  "transaction_time": "2023-03-02T05:17:36.802Z",
  "account_balance": "100.00",
  "result_description": "Payout was processed successfully"
}

Notes

• Ensure payout_reference is unique for each transaction to avoid duplication errors.
• The recipient_type in the payout request must align with the destination in the callback (e.g., BANK_ACCOUNT_NUMBER corresponds to bank_account).
• The callback_url must be a valid, accessible endpoint to receive asynchronous transaction updates.
• The account_balance reflects the payer's balance post-transaction and should be monitored to ensure sufficient funds for future transactions.

Error Handling

Common errors include:

• Missing required fields: Ensure all mandatory fields are provided in the payout request.
• Invalid recipient_type: Use one of the allowed values (PAYBILL, TILL, BANK_ACCOUNT_NUMBER).
• Network issues: Verify the callback_url is reachable.
• Insufficient funds: Ensure the payer's account has sufficient balance (check account_balance in callback).
• Authentication errors: Verify the x-access-token header contains a valid access token.
• Invalid Payout Reference: Ensure the payout_reference used in status queries is correct.