Hướng Dẫn Tích Hợp API KCB M-PESA STK Push

KCB BUNI M-PESA STK Push cho phép bạn khởi tạo yêu cầu thanh toán trực tiếp đến điện thoại của khách hàng. KCB cung cấp một API bảo mật giúp các doanh nghiệp và nhà phát triển thu thập thanh toán từ khách hàng một cách dễ dàng. Hướng dẫn này sẽ giúp bạn qua các bước xác thực, gửi yêu cầu STK Push, xử lý callback và hiểu các phản hồi có thể xảy ra.

Mục Lục

1. Xác Thực và Tạo Token
2. Khởi Tạo Yêu Cầu STK Push
3. Phản Hồi Thành Công
4. Callback Response
5. Các Phản Hồi Lỗi Có Thể Xảy Ra
6. Điều Kiện Đi Live
7. Thực Hành Tốt Nhất
8. Câu Hỏi Thường Gặp

1. Xác Thực và Tạo Token

Trước khi thực hiện bất kỳ yêu cầu API nào, bạn cần xác thực bằng Consumer Key và Consumer Secret mà bạn nhận được trong quá trình đăng ký.

Endpoint:

POST https://uat.buni.kcbgroup.com/token?grant_type=client_credentials

Headers:

Authorization: Basic {Base64(consumerKey:consumerSecret)}

Ví dụ Yêu cầu:

curl --location --request POST 'https://uat.buni.kcbgroup.com/token?grant_type=client_credentials' \
--header 'Authorization: Basic XENo...ZTdh' \
--data ''

Phản Hồi Thành Công:

{
  "access_token": "eyJ4NyRqV5xTbuwcwdi7...",
  "token_type": "Bearer",
  "expires_in": 3599
}

Tham Số Token

2. Khởi Tạo Yêu Cầu STK Push

Khi bạn đã có token, bạn có thể bắt đầu một yêu cầu STK Push.

Endpoint:

POST https://uat.buni.kcbgroup.com/mm/api/request/1.0.0/stkpush

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Ví dụ Yêu Cầu:

{
  "phoneNumber": "254708920430",
  "amount": "1",
  "invoiceNumber": "1123412831049",
  "sharedShortCode": true,
  "orgShortCode": "522522",
  "orgPassKey": "",
  "callbackUrl": "https://example.com/callback",
  "transactionDescription": "thanh toán học phí"
}

Tham Số Yêu Cầu

3. Phản Hồi Thành Công

Nếu yêu cầu hợp lệ, bạn sẽ nhận được phản hồi sau:

{
  "response": {
    "MerchantRequestID": "0c43-471f-b0cb-f80bcaee5e9e242149",
    "ResponseCode": "0",
    "CustomerMessage": "Thành công. Yêu cầu đã được chấp nhận để xử lý",
    "CheckoutRequestID": "ws_CO_17092025150413517708920430",
    "ResponseDescription": "Thành công. Yêu cầu đã được chấp nhận để xử lý"
  },
  "header": {
    "statusDescription": "Thành công. Yêu cầu đã được chấp nhận để xử lý",
    "statusCode": "0"
  }
}

Tham Số Phản Hồi

4. Callback Response

Khi khách hàng nhập PIN và hoàn tất giao dịch, API sẽ gửi callback đến callbackUrl mà bạn đã chỉ định.

Ví dụ Payload Callback:

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "0c43-471f-b0cb-f80bcaee5e9e242149",
      "CheckoutRequestID": "ws_CO_17092025150413517708920430",
      "ResultCode": 0,
      "ResultDesc": "Yêu cầu dịch vụ đã được xử lý thành công.",
      "CallbackMetadata": {
        "Item": [
          {"Name": "Amount", "Value": 1},
          {"Name": "MpesaReceiptNumber", "Value": "TIH8BED1K4"},
          {"Name": "Balance"},
          {"Name": "TransactionDate", "Value": 20250917150425},
          {"Name": "PhoneNumber", "Value": 254708920430}
        ]
      }
    }
  }
}

Tham Số Callback

5. Các Phản Hồi Lỗi Có Thể Xảy Ra

6. Điều Kiện Đi Live

Để đi live:

• Mẫu thư yêu cầu chính thức cần thiết để đi live
• Điền và nộp một thư yêu cầu đã ký tới buni@kcbgroup.com
• Đối với bất kỳ câu hỏi và hỗ trợ nào khác, hãy liên hệ với buni@kcbgroup.com

7. Thực Hành Tốt Nhất

• Kiểm Tra Lỗi: Luôn kiểm tra phản hồi từ API và xử lý lỗi một cách thích hợp.
• Bảo Mật: Giữ bí mật các thông tin xác thực và không công khai chúng.
• Thời Gian Xử Lý: Đảm bảo rằng bạn có một cơ chế cho phép xử lý thời gian trễ trong giao dịch.

8. Câu Hỏi Thường Gặp

1. API KCB M-PESA STK Push là gì?

KCB M-PESA STK Push là một API cho phép bạn gửi yêu cầu thanh toán đến điện thoại của khách hàng thông qua dịch vụ M-PESA.

2. Tôi cần thông tin gì để sử dụng API?

Bạn cần Consumer Key và Consumer Secret từ KCB để xác thực.

3. Làm thế nào để xử lý callback từ API?

Bạn cần thiết lập một endpoint mà API có thể gửi thông tin callback đến, và xử lý dữ liệu trong payload callback.

4. Những lỗi phổ biến khi tích hợp API là gì?

Một số lỗi phổ biến bao gồm thông tin xác thực không hợp lệ, thiếu tham số, và thời gian phản hồi quá lâu.

Nếu bạn cần bất kỳ sự trợ giúp nào liên quan đến tích hợp thanh toán, hãy liên hệ với chúng tôi!

Chúc bạn lập trình vui vẻ!