Webhooks

KyckGlobal now provides webhooks for monitoring payment status changes. An HMAC is included for message verification.

Setup#

Contact support with your URLs for Sandbox and/or Production environments, as well as a preference for JSON or XML. Support will provide you with matching HMAC secret keys.

Data Format#

We will POST the following data to a URL you provide. Both JSON and XML formats are available.

JSON

{
"payerId": "K080494P",
"payeeId": "Payee30507",
"refId": "RFQB9I5LQS21K7ATM",
"amount": 100,
"status": "Submitted",
"pendingReferenceId": "RF4NZSORO1COSEPEN",
"PayerPaymentReferenceNum": "79ed8dee-f2df-499a-bb9a-02b3620682da",
"cashPickupCode": "46455183",
"barCode": "799366970196050000019666875288",
"barCodeURL": "https://api.kyckglobal.com/apis/cash/799366970196050000019666875288",
"failedReason": "Card declined",
"updatedDate": "03/01/2022 03:04:33",
"payeePaymentMethod": "ach",
"cashLocation": "--JSONObject--",
"checkNumber": "1415",
"checkSendBy": "Mail",
"TrackingNumber": "0027090299065296377819038440405",
"trackingDate": "2024-11-06 18:28:54",
"deliveryStatus": "In Transit",
"checkStubLine1": "`{\"name\": \"Offers\", \"values\": [\"Bravecto $10\", \"Bravecto $25\",\"Totals\"]}`",
"checkStubLine2": "{\"name\": \"Counts\", \"values\": [\"120\",\"11\",\"131\"]}`",
"checkStubLine3": "`{\"name\": \"Totals\", \"values\": [\"$1200.00\", \"$275.00\", \"$1475.00\"]}`",
"checkStubLine4": "`{\"name\": \"Totals\", \"values\": [\"$1200.00\", \"$275.00\", \"$1475.00\"]}`",
"checkStubLine5": "`{\"name\": \"Totals\", \"values\": [\"$1200.00\", \"$275.00\", \"$1475.00\"]}`"
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<statusReport>
<payerId>K080494P</payerId>
<payeeId>Payee30507</payeeId>
<refId>R0TBBDAMCZCLWNATM</refId>
<amount>10000</amount>
<status>Submitted</status>
<pendingReferenceId>RF4NZSORO1COSEPEN</pendingReferenceId>
<PayerPaymentReferenceNum>79ed8dee-f2df-499a-bb9a-02b3620682da</PayerPaymentReferenceNum>
<cashPickupCode>46455183</cashPickupCode>
<barCode>799366970196050000019666875288</barCode>
<barCodeURL>https://api.kyckglobal.com/apis/cash/799366970196050000019666875288"</barCodeURL>
<failedReason>Card declined</failedReason>
<updatedDate>03/01/2022 03:22:16</updatedDate>
<payeePaymentMethod>ach</payeePaymentMethod>
<cashLocation>--JSONObject--</cashLocation>
<checkNumber>1415</checkNumber>
<checkSendBy>Mail</checkSendBy>
<TrackingNumber>0027090299065296377819038440405</TrackingNumber>
<trackingDate>2024-11-06 18:28:54</trackingDate>
<deliveryStatus>In Transit</deliveryStatus>
<checkStubLine1>`{"name": "Offers", "values": ["Bravecto $10", "Bravecto $25","Totals"]}`</checkStubLine1>
<checkStubLine2>{"name": "Counts", "values": ["120","11","131"]}`</checkStubLine2>
<checkStubLine3>`{"name": "Totals", "values": ["$1200.00", "$275.00", "$1475.00"]}`</checkStubLine3>
<checkStubLine4>`{"name": "Totals", "values": ["$1200.00", "$275.00", "$1475.00"]}`</checkStubLine4>
<checkStubLine5>`{"name": "Totals", "values": ["$1200.00", "$275.00", "$1475.00"]}`</checkStubLine5>
</statusReport>

Message Authentication#

All webhook HTTP requests include a SIGNATURE header containing an HMAC-SHA256 in base64 format. Messages should be validated with the secret key provided to you by support.

Node.js Example

require("crypto");
const signature = crypto.createHmac("SHA256", sharedSecretKey).update(requestBody).digest("base64");

Payment Types#

Webhooks are currently only available for the following payment types:

  • ACH
  • MoneyGram
  • NCRPay360
  • Iach
  • Wire
  • Push To Account
  • Push To Card
  • PayPal
  • Venmo
  • Check

More payment types will be made available soon.

Payer Status Data Format#

We will POST the following data to a URL you provide. Both JSON and XML formats are available.

JSON

{
"payerId": "K080494P",
"status": "Onboarded",
"updatedDate": "03/01/2022 03:04:33"
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<statusReport>
<payerId>K080494P</payerId>
<status>Onboarded</status>
<updatedDate>03/01/2022 03:22:16</updatedDate>
</statusReport>

Webhooks#

This section highlights the webhook payloads for the following Network Payment Providers

VENMO

Status: Submitted

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "R70LG3SFIPHHAQVEN",
"status": "Submitted",
"updatedDate": "02/09/2025 10:33:00",
"amount": 98,
"PayerPaymentReferenceNum": "UTRNSJ7251768
}

Status: Returned

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "R13IVTYWSC93TEVEN",
"status": "Returned",
"updatedDate": "12/31/2024 08:00:01",
"amount": 98,
"failedReason": "The recipient for this payout does not have an account. A link to sign up
for an account was sent to the recipient. However, if the recipient does not claim this payout
within 30 days, the funds will be returned to your account.",
"PayerPaymentReferenceNum": "Reference No - C420A4AFF"
}

Status: Rejected

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "R13IVTYWSC93TEVEN",
"status": "Rejected",
"updatedDate": "12/31/2024 08:00:01",
"amount": 98,
"failedReason": "The recipient for this payout does not have an account. A link to sign up
for an account was sent to the recipient. However, if the recipient does not claim this payout
within 30 days, the funds will be returned to your account.",
"PayerPaymentReferenceNum": "Reference No - C420A4AFF"
}

Status: Success

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "R1NKITH7HPZSHEVEN",
"status": "Success",
"updatedDate": "12/31/2024 12:45:01",
"amount": 29,
"PayerPaymentReferenceNum": "Reference No - A5D25E73"
}

PayPal

Status: Submitted

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RXTDZ06RLZ2EDGPAL",
"status": "Submitted",
"updatedDate": "12/31/2024 08:02:59",
"amount": 80,
"PayerPaymentReferenceNum": "Reference No 95B693B6"
}

Status: Returned

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RUYBKEQ05ZOENJWPAL",
"status": "Returned",
"updatedDate": "12/27/2024 01:30:01",
"amount": 50,
"PayerPaymentReferenceNum": "Reference No - 42DE15E7"
}

Status: Rejected

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RUYBKEQ05ZOENJWPAL",
"status": "Rejected",
"updatedDate": "12/27/2024 01:30:01",
"amount": 50,
"PayerPaymentReferenceNum": "Reference No - 42DE15E7"
}

Status: Success

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RSVOIMELTLPVEUPAL",
"status": "Success",
"updatedDate": "12/31/2024 03:15:01",
"amount": 240,
"PayerPaymentReferenceNum": "Reference No - 2D7491ED"
}

ACH

Status: Submitted

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RUABAMEPGEZPBAA",
"status": "Submitted",
"updatedDate": "12/31/2024 08:55:50",
"amount": 190,
"PayerPaymentReferenceNum": "Reference No - 122DB328"
}

Status: Returned

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RWMFREIEWXLIRCA",
"status": "Returned",
"updatedDate": "12/31/2024 03:08:04",
"amount": 129.98,
"failedReason": "No bank account/unable to locate account",
"PayerPaymentReferenceNum": "Reference No - A08BD54A"
}

Status: Rejected

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RWMFREIEWXLIRCA",
"status": "Rejected",
"updatedDate": "12/31/2024 03:08:04",
"amount": 129.98,
"failedReason": "No bank account/unable to locate account",
"PayerPaymentReferenceNum": "Reference No - A08BD54A"
}

Status: Success

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RVV9SEKRZ8EWZRA",
"amount": 25,
"status": "Success",
"updatedDate": "12/31/2024 07:00:11"
}

Push To Card

Status: Submitted

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "R3VIQVYEL9VAPCPTC",
"status": "Submitted",
"updatedDate": "12/31/2024 07:28:54",
"amount": 310,
"PayerPaymentReferenceNum": "Reference No - 39FE67B1"
}

Status: Returned

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RAP8ODE6IIQNTNPTC",
"status": "Returned",
"updatedDate": "12/30/2024 04:52:11",
"amount": 297,
"failedReason": "Country not supported for merchant",
"PayerPaymentReferenceNum": "Reference No - 3181070B"
}

Status: Rejected

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RAP8ODE6IIQNTNPTC",
"status": "Returned",
"updatedDate": "12/30/2024 04:52:11",
"amount": 297,
"failedReason": "Country not supported for merchant",
"PayerPaymentReferenceNum": "Reference No - 3181070B"
}

Status: Success

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RNUQALEOTFDLQKPTC",
"status": "Success",
"updatedDate": "12/31/2024 08:13:25",
"amount": 540,
"PayerPaymentReferenceNum": "Reference No - E476AC19"
}

Check

Status: Submitted

{
"payerId": "K121058P",
"payeeId": "Payee532a6a8e-d718-4bab-bc21-14b491cc1bce",
"refId": "RT5DTHJRHEBNRFCHECK",
"status": "Submitted",
"updatedDate": "12/16/2024 12:15:13",
"amount": 10,
"PayerPaymentReferenceNum": "TEST2031",
"checkSendBy": "Mail",
"checkStubLine1": "`{\"name\":\"Offers\",\"values\":[\"Bravecto $10\",\"Totals\"]}`",
"checkStubLine2": "`{\"name\":\"Counts\",\"values\":[\"1\",\"1\"]}`",
"checkStubLine3": "`{\"name\":\"Totals\",\"values\":[\"$10.00\",\"$10.00 \"]}`"
}

Status: Returned

{
"payerId": "K121058P",
"refId": "RMOQQ4I9FXLSWACHECK",
"status": "Returned",
"updatedDate": "12/10/2024 09:34:48",
"amount": 20,
"failedReason": "Access Denied.",
"checkNumber": "1000002",
"checkSendBy": "Mail",
"checkStubLine1": "`{\"name\":\"Offers\",\"values\":[\"Bravecto $10\",\"Totals\"]}`",
"checkStubLine2": "`{\"name\":\"Counts\",\"values\":[\"2\",\"2\"]}`",
"checkStubLine3": "`{\"name\":\"Totals\",\"values\":[\"$20.00\",\"$20.00 \"]}`"
}

Status: Rejected

{
"payerId": "K121058P",
"refId": "RMOQQ4I9FXLSWACHECK",
"status": "Returned",
"updatedDate": "12/10/2024 09:34:48",
"amount": 20,
"failedReason": "Access Denied.",
"checkNumber": "1000002",
"checkSendBy": "Mail",
"checkStubLine1": "`{\"name\":\"Offers\",\"values\":[\"Bravecto $10\",\"Totals\"]}`",
"checkStubLine2": "`{\"name\":\"Counts\",\"values\":[\"2\",\"2\"]}`",
"checkStubLine3": "`{\"name\":\"Totals\",\"values\":[\"$20.00\",\"$20.00 \"]}`"
}

Status: Success

{
"payerId": "K121058P",
"refId": "RMOQQ4I9FXLSWACHECK",
"status": "Success",
"updatedDate": "12/10/2024 09:34:48",
"amount": 20,
"checkNumber": "1000002",
"checkSendBy": "Mail",
"checkStubLine1": "`{\"name\":\"Offers\",\"values\":[\"Bravecto $10\",\"Totals\"]}`",
"checkStubLine2": "`{\"name\":\"Counts\",\"values\":[\"2\",\"2\"]}`",
"checkStubLine3": "`{\"name\":\"Totals\",\"values\":[\"$20.00\",\"$20.00 \"]}`"
}