Webhooks Reference

An explanation of the key fields and values found in webhook notifications sent by Cycle.

Webhook Payload Structure

Fields included in Cycle Webhook notifications.

Top-Level Fields

Field	Format	Description
`Operation`	String	Type of operation (Payment, ReversePayment)
`Id`	String	Unique ID of the transaction
`Amount`	String	Total transaction amount
`Status`	String	Current status (Completed, Voided)
`CreatedAt`	UTC, yyyy-MM-ddTHH:mm:ss.SSSZ	Timestamp when the operation was created
`PaidAt`	Same as above	Timestamp when payment was captured
`AcquiredAt`	Same as above	Timestamp when bank confirmation was received
`Description`	String	Custom description of the transaction
`EventType`	String	Notification type (PAY, FISCAL, FINALIZE)
`ReceiptEmail`	String	Customer email for the receipt (if provided)
`ReceiptPhone`	String	Customer phone number (optional)
`ApprovalCode`	String	Code from payment authorisation
`Inputtype`	Integer	Method used for payment input
`AcquirerCode`	String	Acquiring platform code (CASH, FIMI, etc.)
`PaymentService`	String	Payment service name (e.g. cash, credit card)
`CardType`	String	Card type (Visa, Mastercard, etc.)
`TIME`	String	Terminal identifier
`MID`	String	Cycle Agent login / Merchant Identifier
`MIDName`	String	Agent display name or company name
`Card`	String	Masked card number (e.g. 4111********1111)
`CardIssuerName`	String	Name of issuing bank

Device Information (Device)

Field	Format	Description
`Id`	String	Device ID
`Name`	String	Device name or label
`Model`	String	Device model (e.g. Pixel 8a)

Fiscal Information (Fiscal)

Applicable only if fiscalisation is required/enabled. Not required in South Africa.

Field	Format	Description
`PrinterSerialNumber`	String	Serial number of the fiscal device (if used)
`PrinterRegNumber`	String	Device registration number
`PrinterShift`	String	Cash register shift number
`PrinterDocSerialNumber`	String	Receipt serial number
`FiscalDocumentNumber`	String	Fiscal document number
`FiscalDocumentMark`	String	Fiscal signature
`FiscalStorageNumber`	String	Fiscal module serial number
`FiscalDatetime`	DateTime	Time of fiscalisation or receipt closure
`FFDVersion`	Integer	Fiscal firmware version
`FiscalStatus`	Integer	Fiscalisation result status
`FiscalError`	Integer	Fiscal error code (if any)
`FiscalMessage`	String	Fiscal message text (e.g. "OK. [0]")
`PrinterUserName`	String	Legal name of merchant or entity
`PrinterTaxId`	String	Tax ID (e.g. South African SARS VAT number)
`PrinterPayAddress`	String	Merchant settlement address
`PrinterPayPlace`	String	Point of sale location
`PrinterTaxSystem`	Integer	Tax regime code
`PrinterTaxSystemName`	String	Description of tax regime (e.g. "VAT Standard")
`PrinterInternetPaymentOnly`	Boolean	True if internet-only payments are allowed
`PrinterOFDName`	String	Name of the fiscal data operator (if any)
`PrinterOFDTaxId`	String	Tax ID of fiscal data operator

Product Line Items (Products, Purchases)

Field	Format	Description
`Title`	String	Product name or label
`Code`	String	Internal or external product code
`Price`	Decimal	Price per unit
`Quantity`	Integer	Quantity sold
`TaxCode`	Array	Applicable tax codes
`GTIN`	String	Global Trade Item Number (barcode)
`Serial`	String	Serial number (if marked product)
`MarkType`	String	Mark type for traceable goods
`MarkCheckResult`	String	Result of mark check (e.g. [M+])
`OnlineMarkCheckResult`	String	Brand check result in online mode

Additional Fields

Field	Format	Description
`ResultCode`	Integer	Internal result/error code
`ResultMessage`	String	Explanation of the result code (if any)
`RRN`	String	Retrieval Reference Number
`ExtID`	String	External transaction ID (if provided)
`PAN`	String	Masked card number
`ReaderType`	String	Type of card reader (e.g. D60, TTK)
`ReaderId`	String	Reader unique ID
`ReaderSN`	String	Reader serial number
`DvcAppBuild`	String	Device app version
`Invoice`	String	Cycle-issued invoice/check reference
`ClientID`	Integer	Cycle internal client ID
`ClientName`	String	Client legal name
`BranchID`	Integer	ID of branch (if used)
`BranchName`	String	Branch name
`ExtTransData`	String	External metadata or reference info
`PaymentID`	String	(For refunds) Original payment ID
`PaymentInvoice`	String	(For refunds) Original transaction invoice
`PartialReverse`	String	"1" = Partial refund, "0" = Full refund
`OfflineMode`	Boolean	True if transaction was done offline
`OfflineDateTimeClient`	DateTime	Timestamp on device during offline payment

Operation Types

Type	Description
`Payment`	Standard payment transaction
`ReversePayment`	Cancellation or refund of a transaction

Transaction Status

Type	Description
`Completed`	Payment or refund completed successfully
`Voided`	Payment was reversed or cancelled

Event Types

Type	Description
`PAY`	Successful transaction notification
`FISCAL`	Fiscal data notification (if applicable)
`FINALIZE`	Notification of unsuccessful payment attempt

Input Type (Payment Source)

Type	Description
`0`	Unknown
`1`	Manual card entry
`2`	Magnetic stripe
`3`	Chip card (EMV)
`4`	Contactless / Tap
`5`	Linked card
`7`	External terminal
`8`	Prepaid account
`9`	Postpaid account
`10`	Cash payment
`30`	Pay-by-link
`100`	Recurring payment

Acquirer Codes

Type	Description
`ISO8583`	ISO8583 protocol + acquirer bank routing
`CASH`	Cash transaction
`PREPAID`	Prepaid transaction
`CREDIT`	Postpaid (credit facility)
`OUTERCARD`	External card terminal
`MANUAL`	Manual card input

Refund Type (PartialReverse)

Type	Description
`0`	Full refund
`1`	Partial refund

Refund References

Type	Description
`PaymentID`	The original Cycle transaction ID for the payment being refunded/cancelled
`PaymentInvoice`	The original Cycle invoice number for the refunded/cancelled transaction

Fiscal Tags and Alias Fields

If fiscalisation is enabled, webhook payloads may include fiscal tags for marked goods. Otherwise, product items are returned using alias fields:

Title – Name of the item
Price – Unit price
Quantity – Quantity purchased
TaxCode, GTIN, etc. – Optional tax or traceability metadata

These fields reflect what was originally submitted when initiating the transaction. If fiscal tags were used, they will appear in the notification. If alias fields were used instead, the notification will include those.