API Reference

This reference maps internal Cycle platform values to human-readable types used in API payloads, enums, tax settings and internal routing.

Important Note

For POST requests, you may specify values using either aliases or numeric codes. The correct value must be provided at the root level of the request.
For GET requests, values must be specified strictly as numeric codes.

Input Types

Type	Description
`Unknown`	0
`Manual entry`	1
`Magnetic stripe`	2
`Chip`	3
`Non-contact`	4
`Linked card`	5
`External terminal`	7
`Prepayment`	8
`Postpaid`	9
`Cash`	10
`Recurring`	100

PayType

Type	Description
`Non-cash`	0
`Prepayment`	1
`Cash`	2
`Postpaid`	3

CardInputMode

Type	Description
`Card`	1
`Linked card`	2

AcquirerCodes

Type	Description
`Cash`	CASH
`Prepayment`	PREPAID
`Postpaid`	CREDIT
`External terminal`	OUTERCARD
`Manual input`	MANUAL

User States

Type	Description
`Active`	1
`Blocked`	0

Client Product Codes

Type	Description
`Cycle Pay Android`	CYCLE_PAY
`Cycle Pay iOS`	CYCLEPAY_IOS
`Cycle POS`	CYCLE_POS

ReaderTypes

Type	Description
`Cycle One`	DSPREAD_D60
`SoftPOS *soon`	TAP2GO

ReverseModes (Strings)

Type	Description
`Cancel`	Cancel
`Cancel without card`	CancelCNP
`Return`	Return
`Return without card`	ReturnCNP

ReverseModes (Integers)

Type	Description
`Cancel`	1
`Return`	2
`CancelCNP`	3
`Auto cancel`	4
`ReturnCNP`	5
`Credit Voucher`	500

TaxCode

TaxCode values are arrays.

Type	Description
`VAT 15%`	["VAT1500"]
`VAT 15/115`	["VAT1500_11500"]
`VAT 10%`	["VAT1000"]
`VAT 10/110`	["VAT1000_11000"]
`VAT 0%`	["VAT0000"]
`Excluding VAT`	["VATNA"]
`Without VAT`	[]

AccountTypeID

Type	Description
`User`	11
`Agent`	20

User Rights (Actions)

Type	Description
`SalesManager`	191
`Unit Administrator`	200
`View divisions`	201
`Assign terminal`	210
`Admin client`	220
`Reverse other payments`	301
`View recurrent`	700
`Product Management`	900

AppFramework

Type	Description
`csharp`	1
`swift`	2
`objc`	2
`java`	3
`javascript`	4
`qt`	5

Transaction Statuses and Substatuses

Status Name	Code / Substatus	Comment
Created	`100 / 101`	Creating an "empty" transaction
Check	`200`
Checked_Ok	`/ 201`	Payment verification successful
Checked_Failed	`/ 202`	Payment verification failed
Pay	`400`
Pay_AcquiredOk	`/ 401`	Acquiring successful (temporary state)
Pay_AcquiredFailure	`/ 402`	Acquiring failed
Pay_AcquireReverseNeeded	`/ 403`	Reverse is required – waiting for auto-cancel
Pay_AcquireReversedOk	`/ 404`	Cancellation successful
Pay_AcquireNotConfirmedByEMVKernel	`/ 406`	Not confirmed by EMV core. Auto-cancel required
Pay_AcquireNoResponseFromAcquiringHost	`/ 407`	No response from bank/acquirer. Auto reverse will be carried out
Pay_PaidOk	`/ 411`	Success. Final state
Pay_PaidFailure	`/ 412`	Error after successful acquiring
Reverse	`500`	Take into account ReverseMode (1–5 or 500)
Reverse_CanceledOk	`/ 502`	Successful cancellation. Final state
Reverse_CancelNeeded	`/ 503`	Cancellation attempt in progress
Reverse_CancelFailed	`/ 506`	Cancellation failed
Reverse_ReturnedOk	`/ 504`	Successful return. Final state
Reverse_ReturnNeeded	`/ 505`	Return attempt in progress
Reverse_ReturnFailed	`/ 507`	Refund failed

Success for payment: Substate 411

Success for cancellation/refund: Substates 502, 504

Failure: Determined by the absence of success codes plus checking the ErrorCode and ErrorMessage fields.

⚠️ Other substatuses do not unambiguously indicate success or failure.

Required Additional Fields for Transmission

The following fields must be included with every API call, regardless of whether the request originates from the server or a client device.

Field	Subfield	Description	Server Example	Device Example
Location	-	Object indicating the location of the current request. OfflineLocation is used for offline transactions, while Location is used in real-time requests.	`Server’s static location`	`Device’s extracted GPS location`
	Latitude	Latitude (Width)	`-33.9249`	`-33.9249`
	Longitude	Longitude (Length)	`18.4241`	`18.4241`
	Country	Country where the request originated	`South Africa`	`South Africa`
	CountryCode	ISO 2-letter country code	`ZA`	`ZA`
	GMT	Time zone offset from GMT	`2`	`2`
AppFramework	-	Framework in use by the app.	`Java`	`Java`
IP	-	External IP address of the requesting entity	`105.186.112.50`	`105.186.112.50`
Language	-	Language code (use EN for English)	`EN`	`EN`
DeviceInfo	PhoneManufacturer	Manufacturer of the requesting device	`Company name`	`HUAWEI`
	PhoneModel	Model of the device	`App_Windows_RestAPI`	`SM-A515F`
	DeviceID	Unique device identifier	`none`	`94C24A0BC4FB8D3`
	DeviceType	Device type ID	`1`	`1`
	AppFramework	Framework used on device	`java`	`java`
	OS	Operating system name	`Windows`	`Android`
	OSVersion	Version of the operating system	`10`	`10`
	AppID	Application type	`RestAPI`	`RestAPI`
	BuildNumber	App build version	`1.6.42`	`1.6.42`