Sospeter Mong'are

Posted on Jan 3

How to Integrate Instant Payment Notification(IPN) with KCB Bank Buni API Gateway

#api #programming #beginners #tutorial

In the current dynamic and fast-paced financial ecosystem, seamless communication between payment systems is crucial for efficient operations. KCB Bank’s Buni API Gateway facilitates such interactions through its Instant Payment Notification (IPN) API service, enabling third-party systems to receive real-time updates about transactions. This guide provides a comprehensive overview of interacting and integrating with KCB’s IPN service.

What is IPN?

Instant Payment Notification (IPN) is a service that allows KCB Bank to notify a third-party system of specific transaction events, such as successful account credits. These notifications are sent as HTTP POST requests to a designated endpoint provided by the third-party system. The integration is synchronous, meaning the third-party system must acknowledge receipt of the notification in real-time.

Technical Overview

Transport Protocol: Communication happens over HTTPS.HTTPS ensures secure communication
Interaction Type: The communication is synchronous (real-time response is expected).
HTTP Method: The system sends requests using the POST method.POST requests are used for data transmission
Message Format: All data is exchanged in JSON format.JSON is the standard format for payloads

Headers

The Signature header indicates a security measure. It is likely a cryptographic signature to verify the integrity and authenticity of the message.

Integration Steps

Set Up Your Callback URL(API Endpoint):
- Ensure your endpoint is publicly accessible and supports HTTPS.
- Design the endpoint to process incoming notifications and respond appropriately.
Authenticate Notifications:
- Use the Signature header sent with each request to validate the authenticity of the notification.
Handle Notifications:
- Process the payload received from KCB Bank’s IPN service.
- Log the notification for audit purposes.
Send Acknowledgment:
- Respond with the required JSON payload to confirm receipt of the notification.

Notification Flow

KCB sends a notification to your API endpoint(Callback URL) after a successful account credit transaction.
Your system acknowledges receipt of the notification by responding with the specified payload.

Notification Payloads

Request Payload (Notification from KCB to Your Endpoint)

Endpoint Overview

Method: POST
URL: https://sandbox.buni.kcbgroup.com/ipn/1.0.0/v1/instant-payment-notification
Authentication: No Authentication. It requires an signature shared via the API Documentation-IPN Account.

Below are the fields(Payload) sent from KCB Bank to Your Callback URL/Endpoint:

Field	Type	Required	Description
`transactionReference`	String	Mandatory	Unique identifier for the transaction.
`requestId`	String	Mandatory	Request identifier from KCB.
`channelCode`	String	Mandatory	Channel used for the transaction.
`timestamp`	Timestamp	Mandatory	Date and time of the transaction.
`transactionAmount`	String	Mandatory	Amount of the transaction.
`currency`	String	Mandatory	Currency of the transaction (e.g., KES).
`customerReference`	String	Mandatory	Reference provided by the customer.
`customerName`	String	Mandatory	Name of the customer.
`customerMobileNumber`	String	Mandatory	Customer's mobile number.
`balance`	String	Mandatory	Account balance after the transaction.
`narration`	String	Mandatory	Description of the transaction.
`creditAccountIdentifier`	String	Mandatory	Identifier for the credited account.
`organizationShortCode`	String	Mandatory	Short code for the organization.
`tillNumber`	String	Mandatory	Till number used for the transaction.

Response Body/Payload (Your Acknowledgment to KCB)

Your system must respond with the following fields:

Field	Type	Required	Description
`transactionID`	String	Mandatory	Unique identifier for the transaction.
`statusCode`	Integer	Mandatory	Status of the acknowledgment (e.g., 0 for success).
`statusMessage`	String	Mandatory	Description of the acknowledgment status.

Sample Payloads

Request Example (Notification from KCB):

{
  "transactionReference": "FT00026252",
  "requestId": "c7d702cb-6b5f-4fa6-8b57-436d0f789017",
  "channelCode": "202",
  "timestamp": "2021111103005",
  "transactionAmount": "100.00",
  "currency": "KES",
  "customerReference": "INV-0001",
  "customerName": "John Doe",
  "customerMobileNumber": "25471111111",
  "balance": "100000.00",
  "narration": "Payment for goods",
  "creditAccountIdentifier": "JD001",
  "organizationShortCode": "777777",
  "tillNumber": "150150"
}

Response Example (Acknowledgment from Your System):

{
  "transactionID": "123456789",
  "statusCode": 0,
  "statusMessage": "Notification received"
}

Security Considerations

HTTPS: Ensure your API endpoint uses HTTPS to encrypt data in transit.
Signature Validation: Use the Signature header to authenticate the notification’s origin and ensure its integrity.
Logging: Log all incoming requests and responses for troubleshooting and audit purposes.

Key Benefits of IPN Integration

Real-Time Notifications: Receive instant updates on transactions.
Improved Efficiency: Automate transaction tracking and reconciliation processes.
Enhanced Security: Secure communication with HTTPS and signature-based authentication.

GOING LIVE

To go live with the IPN integration, a formal request letter must be submitted. The letter, signed by the account signatories, should include all necessary details and be forwarded to buni@kcbgroup.com. This request is a mandatory requirement to transition from the testing environment to the live environment.

Conclusion

Integrating with KCB Bank’s Buni API Gateway for Instant Payment Notifications ensures smooth, secure, and efficient transaction updates. By following the outlined steps and adhering to the payload structures, third-party systems can seamlessly receive and process notifications, enhancing their financial operations. For further assistance, refer to the full API documentation or contact KCB Bank’s support team.

DEV Community