KazePay
    KazePay
    • Introduction
    • Quick Guide
    • Virtual Card APIs
    • Physical Card APIs
    • Webhook APIs
    • Merchant APIs
    • Appendix

    Webhook APIs

    Webhook Get Started#

    Webhook is used to receive notifications from KazePay system.
    Retry Mechanism: When merchants get the callback ,they need to give a success response, otherwise we will call them 5 times in total. The intervals for webhook retries are: 1 minutes, 2 minutes, 4 minutes, 8 minutes, 16 minutes.

    Register a new webhook#

    Register a new webhook for receiving callback notifications from KazePay system.
    ApiCode: setWebhookUrl
    Request Parameter
    NoFieldTypeRequiredNotes
    1urlStringYAddress for notification
    Request Message
    Request Body Example:
    Request Body Example
     { 
 "url":"https://notify.receive/api"
 }
    Request Message Example:
    Request Message Example
     { 
 "head": { 
 "apiCode": "setWebhookUrl", 
 "sysId": "202402271432298822660001", 
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "sign": "29589585d30e6bfca3e2588f61d67cf7ff0567f4c5ccc79ef954da66326be51***", 
 "keyEnc": "7c819f5751420b267a32c6b1bb95735a327dcb20ca1c2abcafaa5125604a8***" 
 }, 
 "body":{ 
 "encrypt":"zcNZ5RFgBASAcOX5sRYiMSTaYN/3iNv3HA3/FXJmVkCnzkECPIpaw7daqowwv*******" 
 } 
 }
    Response Parameters
    NoFieldTypeRequiredNotes
    1encryptStringYReturn values: SUCCESS FAILED
    2urlStringYAddress for notification
    Response Message
    Response Body Example:
    Request Message Example
     { 
 "encrypt":"SUCCESS",
 "url":"https://notify.receive/api"
 }
    Response Message Example:
    Request Message Example
    { 
 "head": { 
 "apiCode": "setWebhookUrl", 
 "sysId": "202402271432298822660001",
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "code": "SUCCESS", 
 "detail": "SUCCESS", 
 "sign": "50a7aca6d7a65f848535aaf6cbfa674583e103afea9db4863b6b47953670cf8***", 
 "keyEnc": "b25973f85c9ff6092b6647a6ed5603384e14a853c3a06b6cfde5ae55eb165***" 
 }, 
 "body":{ 
 "encrypt":"aB3OMZSBlWyaDsPMtU4w/4lI87EWiR1hPzEdBlp9WVvOTjeeX4ZxPy2o+9x1a***"
 } 
 }

    Query webhook#

    ApiCode: getWebhookUrl
    Request Message
    Request Body Example:
    Request Body Example
     { 
 
 }
    Request Message Example:
    Request Message Example
     { 
 "head": { 
 "apiCode": "getWebhookUrl", 
 "sysId": "202402271432298822660001", 
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "sign": "29589585d30e6bfca3e2588f61d67cf7ff0567f4c5ccc79ef954da66326be51***", 
 "keyEnc": "7c819f5751420b267a32c6b1bb95735a327dcb20ca1c2abcafaa5125604a8***" 
 }, 
 "body":{ 
 "encrypt":"zcNZ5RFgBASAcOX5sRYiMSTaYN/3iNv3HA3/FXJmVkCnzkECPIpaw7daqowwv*******" 
 } 
 }
    Response Parameters
    NoFieldTypeRequiredNotes
    1encryptStringYReturn values: SUCCESS FAILED
    2urlStringYAddress for notification
    Response Message
    Response Body Example:
    Request Message Example
     { 
 "encrypt":"SUCCESS",
 "url":"https://notify.receive/api"
 }
    Response Message Example:
    Request Message Example
    { 
 "head": { 
 "apiCode": "getWebhookUrl", 
 "sysId": "202402271432298822660001",
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "code": "SUCCESS", 
 "detail": "SUCCESS", 
 "sign": "50a7aca6d7a65f848535aaf6cbfa674583e103afea9db4863b6b47953670cf8***", 
 "keyEnc": "b25973f85c9ff6092b6647a6ed5603384e14a853c3a06b6cfde5ae55eb165***" 
 }, 
 "body":{ 
 "encrypt":"aB3OMZSBlWyaDsPMtU4w/4lI87EWiR1hPzEdBlp9WVvOTjeeX4ZxPy2o+9x1a***"
 } 
 }

    Delete webhook#

    ApiCode: deleteWebhookUrl
    Request Message
    Request Body Example:
    Request Body Example
     { 

 }
    Request Message Example:
    Request Message Example
     { 
 "head": { 
 "apiCode": "deleteWebhookUrl", 
 "sysId": "202402271432298822660001", 
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "sign": "29589585d30e6bfca3e2588f61d67cf7ff0567f4c5ccc79ef954da66326be51***", 
 "keyEnc": "7c819f5751420b267a32c6b1bb95735a327dcb20ca1c2abcafaa5125604a8***" 
 }, 
 "body":{ 
 "encrypt":"zcNZ5RFgBASAcOX5sRYiMSTaYN/3iNv3HA3/FXJmVkCnzkECPIpaw7daqowwv*******" 
 } 
 }
    Response Parameters
    NoFieldTypeRequiredNotes
    1encryptStringYReturn values: SUCCESS FAILED
    Response Message
    Response Body Example:
    Request Message Example
     { 
 "encrypt":"SUCCESS"
 }
    Response Message Example:
    Request Message Example
    { 
 "head": { 
 "apiCode": "deleteWebhookUrl", 
 "sysId": "202402271432298822660001",
 "requestNo": "202412241536050554232157", 
 "version": "1.0", 
 "code": "SUCCESS", 
 "detail": "SUCCESS", 
 "sign": "50a7aca6d7a65f848535aaf6cbfa674583e103afea9db4863b6b47953670cf8***", 
 "keyEnc": "b25973f85c9ff6092b6647a6ed5603384e14a853c3a06b6cfde5ae55eb165***" 
 }, 
 "body":{ 
 "encrypt":"aB3OMZSBlWyaDsPMtU4w/4lI87EWiR1hPzEdBlp9WVvOTjeeX4ZxPy2o+9x1a***"
 } 
 }

    Notify Details#

    1.TRANSACTION_VERIFICATION_CODE#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2timeStringYyyyy-MM-dd HH:mm:ss
    3codeStringYTransaction verification code
    Result decrypted json string
     {
   "cardID":"19181",
   "time":"2024-11-29 02:42:12",
   "code":"549811"
 }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS"}
 }

    2.CARD_RECHARGE_RESULT#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2timeStringYyyyy-MM-dd HH:mm:ss
    3currencyStringYRecharge currency
    4amountDoubleYRecharge amount
    5statusStringYResult: SUCCESS / FAILED
    6transactionIdStringYTransaction ID
    7sendCurrencyStringYCard Currency
    8sendAmountDoubleYActual Amount to Card
    Result decrypted json string
     {
   "cardID":"19181",
   "time":"2024-11-29 02:42:12",
   "currency":"USD",
   "amount":275.60,
   "status":"SUCCESS",
   "transactionId":"20241128102008673655",
   "sendCurrency":"HKD",
   "sendAmount":2147.76
 }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    3.CARD_3DS_AUTH_RESULT#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2timeStringYyyyy-MM-dd HH:mm:ss
    3authIdStringYAuth Id
    4authResultStringYRefer to Appendix Part 7
    Result decrypted json string
     {
   "cardID":"19181",
   "time":"2024-11-29 02:42:12",
   "authId":"CT3DSA1508634777354273",
   "authResult":"AUTHORIZATION_CANCELED"
 }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    4.USER_KYC_STATUS_CHANGE#

    Result fields
    NoFieldTypeRequiredNotes
    1emailStringYuser submitted KYC email address
    2timeStringYyyyy-MM-dd HH:mm:ss
    3statusStringYRefer to Appendix Part 6
    4reasonStringYReasons for KYC rejection
    Result decrypted json string
     {
   "email":"1234@gmail.com",
   "time":"2024-11-24 17:57:41",
   "status":"PASSED",
   "reason":""
 }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    5.CARD_STATUS_CHANGE#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2statusStringYRefer to Appendix Part 2
    3reasonStringY
    Result decrypted json string
     {
   "cardID":"19181",
   "status":"ACTIVE",
   "reason":""
 }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    6.TRANSACTION_CREATED#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2transactionIdStringYTransaction ID
    3transactionTimeStringYyyyy-MM-dd HH:mm:ss
    4cardCurrencyStringYCard currency type
    5cardCurrencyAmtDoubleYCard currency trans Amount
    6transCurrencyStringYTransaction currency type
    7transCurrencyAmtDoubleYTransaction currency trans Amount
    8transStatusStringYTransaction status
    9transTypeStringYTransaction type
    10merchantNameStringYMerchant name
    11feeDoubleYFee Amount
    12feeCurrencyStringYFee currency
    13refundCurrencyStringCRefund currency
    14refundAmountDoubleCRefund amount
    15subListListCData collection
    subList[0].cardIDStringCCard ID
    subList[0].transactionIdStringCTransaction ID
    subList[0].transactionTimeStringCyyyy-MM-dd HH:mm:ss
    subList[0].cardCurrencyStringCCard currency type
    subList[0].cardCurrencyAmtDoubleCCard currency trans Amount
    subList[0].transCurrencyStringCTransaction currency type
    subList[0].transCurrencyAmtDoubleCTransaction currency trans Amount
    subList[0].feeCurrencyStringCCurrency of the transaction fee
    subList[0].feeDoubleCTransaction fee
    Result decrypted json string
    {
      "cardCurrencyAmt": 359.71,
      "fee": -9.74,
      "feeCurrency": "HKD",
      "transactionTime": "2025-03-24 21:37:12",
      "transCurrency": "MYR",
      "transactionId": "K202503123345",
      "merchantName": "Shell",
      "cardCurrency": "HKD",
      "transType": "AUTH",
      "cardID": "K-123456",
      "refundCurrency": "HKD",
      "transCurrencyAmt": 200,
      "transStatus": "APPROVED",
      "refundAmount": 185.86,
		  "subList": [
          {
            "transactionType": "AUTH",
            "cardCurrency": "HKD",
            "transactionCurrency": "MYR",
            "transactionStatus": "CONFIRM",
            "cardId": "K-123456",
            "transactionAmount": 200,
            "fee": 458,
            "feeCurrency": "HKD",
            "transactionDate": "2025-03-24 21:37:12",
            "cardTransactionAmount": 359.71,
            "transactionId": "K202503123345",
            "transactionIdSub": "2025032421314789"
          },
          {
            "transactionType": "CLEARING",
            "cardCurrency": "HKD",
            "transactionCurrency": "MYR",
            "transactionStatus": "APPROVED",
            "cardId": "K-123456",
            "transactionAmount": 97.09,
            "fee": 458,
            "feeCurrency": "HKD",
            "transactionDate": "2025-03-26 19:36:44",
            "cardTransactionAmount": 173.85,
            "transactionId": "K202503123345",
            "transactionIdSub": "2025032421314790"
          }
        ]
  }
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    7.CARD_ACTIVATION_CODE#

    Result fields
    NoFieldTypeRequiredNotes
    1cardNoStringYCard number
    2activationCodeStringYactivation code, can only be obtained once
    Result decrypted json string
    {
  "cardNo":"4937240800070604",
  "activationCode":"70795665"
}
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }

    8.CARD_CLOSE_RESULT#

    Result fields
    NoFieldTypeRequiredNotes
    1cardIDStringYCard ID
    2closeStatusStringYstatus(SUCCESS/FAILED)
    3transactionIdStringYTransaction ID
    4receiveAmountDoubleYAmount(default USD)
    Result decrypted json string
    {
  "cardNo":"4937240800070604",
  "closeStatus":"SUCCESS",
  "transactionId":"1233456",
  "receiveAmount":100
}
    Responses json string(No encryption needed)
     { 
   "head":"",
   "body":
     {"encrypt":"SUCCESS "}
 }
    Modified at 2025-06-13 08:45:22
    Previous
    Physical Card APIs
    Next
    Merchant APIs
    Built with