Webhook Notification Examples

Example webhook notifications for various transaction events.

Payment Successful (PAY)

When a transaction is successfully processed, Cycle sends a PAY webhook to the merchant's configured URL. Below is a sample payload:

{
  "Operation": "Payment",
  "Id": "43419AE9-B22B-4B44-B50B-DD5EDC63157A",
  "Amount": "100.00",
  "Status": "Completed",
  "CreatedAt": "2024-09-24T12:09:47.114+02:00",
  "PaidAt": "2024-09-24T12:10:04.113+02:00",
  "AcquiredAt": "2024-09-24T12:10:04.113+02:00",
  "Description": "My Test Order",
  "EventType": "PAY",
  "ReceiptEmail": "customer@example.com",
  "ApprovalCode": "SIMULATION",
  "Inputtype": 3,
  "AcquirerCode": "CASH",
  "PaymentService": "credit card",
  "CardType": "mastercard",
  "TIME": "POS-South-Africa-1",
  "MID": "agent@cycle.demo",
  "MIDName": "agent@cycle.demo",
  "Card": "541333******3105",
  "CardIssuerName": "CYCLE BANK",
  "Device": {
    "Id": "e49feef379191687",
    "Name": "Pixel 8a",
    "Model": "Pixel"
  },
  "ResultCode": 0,
  "RRN": "5F293EFF2316",
  "ExtID": "14363817453",
  "DvcAppBuild": "2.9.967962",
  "Invoice": "INV12345",
  "ClientID": 17986,
  "ClientName": "Merchant Pty Ltd",
  "BranchID": 17986,
  "BranchName": "Sandton Branch",
  "ExtTranData": "external_ref_123",
  "Purchases": {
    "Purchases": [
      {
        "AddedQuantity": 0.0,
        "Title": "valid mark",
        "Quantity": 1,
        "TaxCode": [
          "VAT2000"
        ],
        "Price": 100,
        "1171": "+27821234567",
        "1212": 4,
        "1214": 4,
        "1222": 64,
        "1225": "Item Supplier Name",
        "1226": "430601071197",
        "2000": "Base64EncodedMarkDataHere==",
        "2108": 0,
        "_OriginalTags": [
          "Title",
          "Quantity",
          "TaxCode",
          "Price",
          "1171",
          "1212",
          "1214",
          "1222",
          "1225",
          "1226",
          "2000",
          "2108"
        ],
        "OnlineMarkCheckResult": "[MC+]",
        "GTIN": "08907734115982",
        "1262": "030",
        "1263": "2023-11-21",
        "1264": "1944",
        "1265": "UUID=4c1c4334-c0aa-417a-969f-e91077bb4f3c&Time=1726731144757",
        "Serial": "5CxrEKnkpr1j!",
        "MarkType": "GS1.M"
      }
    ],
    "Tags": {
      "1021": "Cashier John Doe",
      "1187": "Store Branch – Sandton",
      "_OriginalTags": [
        "1021",
        "1187"
      ]
    }
  },
  "OfflineMode": false
}

Notes:

Fiscal section may be omitted or minimal for non-fiscal devices or regions.
Phone numbers have been updated to South African format (+27).
ResultCode of 0 means success.
EventType: PAY is your confirmation of a successful transaction.
Invoice, ClientID, and ExtID are useful for reconciling to your internal system.

Payment with Fiscalisation (FISCAL)

This webhook is sent when a payment is successfully processed and fiscalised. For South African merchants, fiscalisation does not apply and this message will only be present for fiscal-enabled merchants in other regions.

{
  "Operation": "Payment",
  "Id": "43419AE9-B22B-4B44-B50B-DD5EDC63157A",
  "Amount": "100.00",
  "Status": "Completed",
  "CreatedAt": "2024-09-24T12:09:47.114+02:00",
  "PaidAt": "2024-09-24T12:10:04.113+02:00",
  "AcquiredAt": "2024-09-24T12:10:04.113+02:00",
  "Description": "My Test Order",
  "EventType": "FISCAL",
  "ReceiptEmail": "customer@example.com",
  "ApprovalCode": "SIMULATION",
  "Inputtype": 3,
  "AcquirerCode": "CASH",
  "PaymentService": "credit card",
  "CardType": "mastercard",
  "TIME": "POS-South-Africa-1",
  "MID": "agent@cycle.demo",
  "MIDName": "agent@cycle.demo",
  "Card": "541333******3105",
  "CardIssuerName": "CYCLE BANK",
  "Device": {
    "Id": "e49feef379191687",
    "Name": "Pixel 8a",
    "Model": "Pixel"
  },
  "Fiscal": {
    "PrinterSerialNumber": "FISCAL-PRINTER-SN-123",
    "PrinterRegNumber": "FISCAL-REG-456",
    "PrinterShift": "SHIFT-789",
    "PrinterDocSerialNumber": "DOC-SN-101112",
    "FiscalDocumentNumber": "FDN-131415",
    "FiscalDocumentMark": "FDM-161718",
    "FiscalStorageNumber": "FSN-192021",
    "FiscalDatetime": "2024-09-24T12:10:04.114+02:00",
    "FFDVersion": 105,
    "FiscalStatus": 1,
    "FiscalError": 0,
    "FiscalMessage": "OK",
    "PrinterUserName": "Merchant Pty Ltd",
    "PrinterTaxId": "1234567890",
    "PrinterPayAddress": "123 Main St, Sandton",
    "PrinterPayPlace": "POS-South-Africa-1",
    "PrinterTaxSystem": 1,
    "PrinterTaxSystemName": "VAT Standard",
    "PrinterInternetPaymentOnly": false,
    "PrinterOFDName": "Demo Fiscal Provider",
    "PrinterOFDTaxId": "9309999999"
  },
  "ResultCode": 0,
  "RRN": "5F293EFF2316",
  "ExtID": "14363817453",
  "DvcAppBuild": "2.9.967962",
  "Invoice": "INV12345",
  "ClientID": 17986,
  "ClientName": "Merchant Pty Ltd",
  "BranchID": 17986,
  "BranchName": "Sandton Branch",
  "ExtTranData": "external_ref_123",
  "Purchases": {
    "Purchases": [
      {
        "Title": "valid mark",
        "Quantity": 1,
        "Price": 100,
        "TaxCode": ["VAT2000"],
        "1171": "+27821234567",
        "1212": 4,
        "1214": 4,
        "1222": 64,
        "1225": "Supplier Name Pty Ltd",
        "1226": "430601071197",
        "2000": "EncodedMarkData==",
        "2108": 0,
        "_OriginalTags": ["Title", "Quantity", "TaxCode", "Price", "1171", "1212", "1214", "1222", "1225", "1226", "2000", "2108"],
        "OnlineMarkCheckResult": "[MC+]",
        "GTIN": "08907734115982",
        "1262": "030",
        "1263": "2023-11-21",
        "1264": "1944",
        "1265": "UUID=abc123...&Time=1726731144757",
        "2106": 15,
        "2110": 1,
        "2102": 0,
        "2004": 0,
        "2109": 1,
        "2005": 15,
        "2105": 0,
        "2100": 3,
        "Serial": "5CxrEKnkpr1j!",
        "MarkType": "GS1.M",
        "MarkCheckResult": "[M+]"
      }
    ],
    "Tags": {
      "1021": "Cashier John Doe",
      "1187": "Store Branch – Sandton",
      "_OriginalTags": ["1021", "1187"],
      "2107": "0"
    }
  },
  "OfflineMode": false
}

Notes:

This example demonstrates full fiscal tagging support and is only relevant for systems using virtual fiscal printers or environments with optional advanced tax compliance integrations.

Payment Reversal (PAY with ReversePayment)

This webhook is triggered when a payment is successfully refunded or voided. The Operation field will be ReversePayment, and the Status will be Voided.

{
  "Operation": "ReversePayment",
  "Id": "85BC67DC-1C15-4F7D-AADD-2970C1FD72CB",
  "Amount": "100.00",
  "Status": "Voided",
  "CreatedAt": "2024-09-24T12:20:01.314+02:00",
  "PaidAt": "2024-09-24T12:20:05.109+02:00",
  "AcquiredAt": "2024-09-24T12:20:05.109+02:00",
  "Description": "My Test Order",
  "EventType": "PAY",
  "ReceiptEmail": "customer@example.com",
  "ApprovalCode": "SIMULATION",
  "Inputtype": 3,
  "AcquirerCode": "CASH",
  "PaymentService": "credit card",
  "CardType": "mastercard",
  "TIME": "POS-South-Africa-1",
  "MID": "agent@cycle.demo",
  "MIDName": "agent@cycle.demo",
  "Card": "541333******3105",
  "CardIssuerName": "CYCLE BANK",
  "Device": {
    "Id": "e49feef379191687",
    "Name": "Pixel 8a",
    "Model": "Pixel"
  },
  "ResultCode": 0,
  "RRN": "85BC67DC1C15",
  "ExtID": "14363817453",
  "Invoice": "INV-R12345",
  "ClientID": 17986,
  "ClientName": "Merchant Pty Ltd",
  "BranchID": 17986,
  "BranchName": "Sandton Branch",
  "PaymentID": "85BC67DC-1C15-4F7D-AADD-2970C1FD72CB",
  "PaymentInvoice": "INV-Original123",
  "PartialReverse": "0",
  "ExtTranData": "external_ref_456",
  "Purchases": {
    "Purchases": [
      {
        "Title": "valid mark",
        "Quantity": 1,
        "Price": 100,
        "TaxCode": ["VAT2000"],
        "1171": "+27821234567",
        "1212": 4,
        "1214": 4,
        "1222": 64,
        "1225": "Supplier Name Pty Ltd",
        "1226": "430601071197",
        "1262": "030",
        "1263": "2023-11-21",
        "1264": "1944",
        "1265": "UUID=b5f6ae9b...&Time=1726731605099",
        "2000": "EncodedMarkData==",
        "2004": 0,
        "2005": 15,
        "2100": 3,
        "2102": 0,
        "2105": 0,
        "2106": 15,
        "2108": 0,
        "2109": 1,
        "2110": 1,
        "OnlineMarkCheckResult": "[MC+]",
        "MarkType": "GS1.M",
        "MarkCheckResult": "[M+]",
        "TitleAmount": 100,
        "GTIN": "08907734115982",
        "Serial": "5CxrEKnkpr1j!"
      }
    ],
    "Tags": {
      "1021": "Cashier John Doe",
      "1187": "Branch – Sandton",
      "2107": "0",
      "_OriginalTags": ["1021", "1187"]
    }
  },
  "OfflineMode": false
}

Notes:

Operation: ReversePayment clearly identifies this as a reversal or refund.
Status: Voided confirms the original payment was cancelled.
PaymentID and PaymentInvoice link this reversal to the original transaction.
PartialReverse: "0" means it was a full refund.
EventType: PAY still applies for successful reversal events.

Reversal with Fiscalisation (FISCAL)

This webhook is sent when a payment reversal (refund or void) has been completed and successfully fiscalised (in environments where fiscal data is required or enabled).

{
  "Operation": "ReversePayment",
  "Id": "85BC67DC-1C15-4F7D-AADD-2970C1FD72CB",
  "Amount": "100.00",
  "Status": "Voided",
  "CreatedAt": "2024-09-24T12:20:01.314+02:00",
  "PaidAt": "2024-09-24T12:20:05.109+02:00",
  "AcquiredAt": "2024-09-24T12:20:05.109+02:00",
  "Description": "My Test Order",
  "EventType": "FISCAL",
  "ReceiptEmail": "customer@example.com",
  "ApprovalCode": "SIMULATION",
  "Inputtype": 3,
  "AcquirerCode": "CASH",
  "PaymentService": "credit card",
  "CardType": "mastercard",
  "TIME": "POS-South-Africa-1",
  "MID": "agent@cycle.demo",
  "MIDName": "agent@cycle.demo",
  "Card": "541333******3105",
  "CardIssuerName": "CYCLE BANK",
  "Device": {
    "Id": "e49feef379191687",
    "Name": "Pixel 8a",
    "Model": "Pixel"
  },
  "Fiscal": {
    "PrinterSerialNumber": "FISCAL-PRINTER-SN-123",
    "PrinterRegNumber": "FISCAL-REG-456",
    "PrinterShift": "SHIFT-789",
    "PrinterDocSerialNumber": "DOC-SN-101112",
    "FiscalDocumentNumber": "FDN-131415",
    "FiscalDocumentMark": "FDM-161718",
    "FiscalStorageNumber": "FSN-192021",
    "FiscalDatetime": "2024-09-24T12:20:05.110+02:00",
    "FFDVersion": 105,
    "FiscalStatus": 1,
    "FiscalError": 0,
    "FiscalMessage": "OK",
    "PrinterUserName": "Merchant Pty Ltd",
    "PrinterTaxId": "1234567890",
    "PrinterPayAddress": "123 Main St, Sandton",
    "PrinterPayPlace": "POS-South-Africa-1",
    "PrinterTaxSystem": 1,
    "PrinterTaxSystemName": "VAT Standard",
    "PrinterInternetPaymentOnly": false,
    "PrinterOFDName": "Demo Fiscal Provider",
    "PrinterOFDTaxId": "9309999999"
  },
  "ResultCode": 0,
  "RRN": "85BC67DC1C15",
  "ExtID": "14363817453",
  "Invoice": "INV-R12345",
  "ClientID": 17986,
  "ClientName": "Merchant Pty Ltd",
  "BranchID": 17986,
  "BranchName": "Sandton Branch",
  "PaymentID": "85BC67DC-1C15-4F7D-AADD-2970C1FD72CB",
  "PaymentInvoice": "INV-Original123",
  "PartialReverse": "0",
  "ExtTranData": "external_ref_456",
  "Purchases": {
    "Purchases": [
      {
        "Title": "valid mark",
        "Quantity": 1,
        "Price": 100,
        "TaxCode": ["VAT2000"],
        "1171": "+27821234567",
        "1212": 4,
        "1214": 4,
        "1222": 64,
        "1225": "Supplier Name Pty Ltd",
        "1226": "430601071197",
        "1262": "030",
        "1263": "2023-11-21",
        "1264": "1944",
        "1265": "UUID=b5f6ae9b...&Time=1726731605099",
        "2000": "EncodedMarkData==",
        "2004": 0,
        "2005": 15,
        "2100": 3,
        "2102": 0,
        "2105": 0,
        "2106": 15,
        "2108": 0,
        "2109": 1,
        "2110": 3,
        "OnlineMarkCheckResult": "[MC+]",
        "MarkType": "GS1.M",
        "MarkCheckResult": "[M+]",
        "TitleAmount": 100,
        "GTIN": "08907734115982",
        "Serial": "5CxrEKnkpr1j!"
      }
    ],
    "Tags": {
      "1021": "Cashier John Doe",
      "1187": "Branch – Sandton",
      "2107": "0",
      "_OriginalTags": ["1021", "1187"]
    }
  }
}

Notes:

Operation: ReversePayment confirms this was a refund/void.
EventType: FISCAL shows fiscal data was successfully recorded for the reversal.
FiscalDocumentNumber, FiscalDocumentMark, and FiscalDatetime log the formal reversal receipt info.
The reversal remains linked to the original transaction using PaymentID and PaymentInvoice.

Failed Payment (FINALIZE)

This webhook is sent when a payment attempt fails due to issues such as acquirer decline, transaction duplication, or other processing errors. This notification is optional and must be enabled via Cycle support.

{
  "Operation": "Payment",
  "Id": "0DFA90BE-540A-4856-AE2A-C040F8D78A9E",
  "Amount": "25.00",
  "Status": "Completed",
  "CreatedAt": "2022-02-15T19:26:12.617+02:00",
  "Description": "Order",
  "EventType": "FINALIZE",
  "Inputtype": 4,
  "AcquirerCode": "FIMI",
  "PaymentService": "credit card",
  "CardType": "mastercard",
  "TIME": "POS1",
  "MID": "agent3@cycle.demo",
  "MIDName": "agent3@cycle.demo",
  "Card": "47958383*4298",
  "CardIssuerName": "CYCLE BANK",
  "Device": {
    "Id": "e49feef379191687",
    "Name": "STF-L09",
    "Model": "HUAWEI"
  },
  "Fiscal": {
    "FFDVersion": 0,
    "FiscalStatus": 0,
    "FiscalError": 0
  },
  "ResultCode": 5065,
  "ResultMessage": "Repeat payment! Check sales history (5065). tranId: 43419AE9-B22B-4B44-B50B-DD5EDC63157A",
  "PAN": "547127*1545",
  "ReaderType": "DSPREAD_D60",
  "ReaderId": "2035014901",
  "ReaderSN": "27000509120051501743",
  "DvcAppBuild": "2.8.894000",
  "Invoice": "INV-FAILED123",
  "ClientID": 17986,
  "ClientName": "Merchant Pty Ltd",
  "BranchID": 17986,
  "BranchName": "Sandton Branch",
  "OfflineMode": false
}

Key Fields for Error Handling:

EventType: FINALIZE indicates a failed transaction
ResultCode: Numeric error code (e.g. 5065 = duplicate payment attempt)
ResultMessage: Detailed message explaining the reason for failure
Status: Remains Completed to indicate the event was captured, but not successful
FiscalStatus: Will always be 0 for failed payments