Create a Payment

Initiate a payment in the Cycle system using the REST API.

Endpoint

POST /api/v1/payment/submit

The request body must be a valid JSON object containing all required parameters for the payment transaction.

Note on Card Readers

The Cycle REST API does not support specifying a card reader for input. If your integration requires card-present transactions, you must read the card data yourself and include the raw card data (e.g., PAN, expiry, track data) in the Card object of the request.

Request Body Definitions

Field Name	Type	Description
`BasicTran`	JsonObject	Base Transaction Object
`InputType`	Integer	Input type
`CurrencyID`	String	Currency ID
`ServiceID`	String	Identifier of the executing service
`Description`	String	Transaction Description
`Amount`	Decimal	Transaction amount
`ExtID`	String	Transaction ID in the external system
`AmountCashGot`	Integer	Amount received
`ClientDateTime`	String	Date and time on the client
`ExtTransData`	String	Additional payment data (JSON as string)
`AuxDataInput`	JsonObject	Object of formation of commodity items
`AuxData`	JsonObject	Product Item Object
`Purchases`	Object Array	Array of product items
`Title`	String	Name
`Price`	String	Price
`Quantity`	String	Quantity
`TaxCode`	Array	Array of taxes
`Tags`	Array	Array of fiscal tags
`ID`	String	Transaction ID in the Cycle system
`CPFData`	JsonObject	Custom product object
`ProductsCustomFields`	Array of Objects	Array of custom fields
`ProductDescID`	Integer	The product identifier
`ProductCode`	String	Product code
`Fields`	Array of Objects	Product Field Array
`FieldDescID`	Integer	Product Field ID
`FieldCode`	String	Product field code
`TextSelect`	String	Product field value
`OfflineTran`	JsonObject	Offline transaction object
`OfflineMode`	boolean	Sign of an offline transaction
`Invoice`	String	Check number
`Paid`	String	Date and time of payment
`OfflineLocation`	JsonObject	Location object
`Latitude`	Integer	Latitude
`Longitude`	Integer	Longitude
`TerminalGroupID`	Integer	ID of the terminal group
`TerminalGroupCode`	String	Name of the terminal group
`SkipFiscalization`	Boolean	True to skip fiscalization
`FiscalRouteProfileCode`	String	Name of the fiscalization route
`AcqTran`	JsonObject	Acquiring transaction object
`AcquirerCode`	String	Acquirer code
`SingleStepAuthMode`	Boolean	One-step transaction sign
`ExternalTerminalID`	String	External terminal ID
`AllowSwipeOverChip`	boolean	Allow Swipe for chip cards
`ForceSignatureRequirement`	boolean	Sign of unambiguous signature requirement
`AdditionalAcquiringFields`	String	Additional acquiring fields
`TaxesModel`	JsonObject	Tax Model Object
`Taxes`	Array of Strings	Array of tax codes
`Code`	String	Account code
`Receipt`	JsonObject	Check sending object
`Email`	String	email for the check
`Emails`	Array	Array of emails
`Phone`	String	Phone number
`Phones`	Array	Array of numbers
`RetryNum`	Integer	Number of sending attempts
`Card`	JsonObject	Card object
`CardInputMode`	Integer	Card entry method
`CardDataInput`	JsonObject	Card data object
`EXP`	String	Card validity period
`CVV2`	String	CVV2
`PAN`	String	Card number
`ReaderType`	String	The type of reader
`ReaderData`	String	Reader data package
`LinkedCardId`	Integer	Linked card ID
`Files`	Array
`FileType`	Signature
`FileCode`	string
`ClientProductCode`	String	Client application code
`DeviceInfo`	JsonObject	Device object
`PhoneManufacturer`	String	Manufacturer
`PhoneModel`	String	Model
`DeviceID`	String	Device ID
`DeviceType`	String	Device type
`AppFramework`	String	Framework applications
`OS`	String	Operating system
`OSVersion`	String	System version
`AppID`	String	Application ID
`BuildNumber`	String	Build number
`Location`	JsonObject	Location object
`Latitude`	Integer	Latitude
`Longitude`	Integer	Longitude
`GMT`	Integer	Time zone
`AppFramework`	String	Framework applications
`ServerBuildNumber`	String
`UserAgent`	String
`CurrentAccountID`	Integer	Agent ID
`IP`	String	IP address
`Lang`	String	Language
`Country`	String	Country
`CountryCode`	String	Country code

Example: Create Payment with Linked Card

{
  "Receipt": {
    "Email": "customer@email.com",
    "Phone": "+27 82 123 4567",
    "RetryNum": 1
  },
  "Location": {
    "Latitude": -29.8587,
    "Longitude": 31.0218
  },
  "Country": "South Africa",
  "CountryCode": "ZA",
  "DeviceInfo": {
    "PhoneManufacturer": "Samsung",
    "PhoneModel": "Galaxy A32",
    "DeviceID": "ZA-DEVICE-123456",
    "DeviceType": "1",
    "AppFramework": "java",
    "OS": "Android",
    "OSVersion": "12.0.0",
    "AppID": "za.cyclepay.client.android",
    "BuildNumber": "2.4.390248"
  },
  "GMT": 2,
  "AppFramework": "java",
  "IP": "102.165.44.112",
  "Lang": "en",
  "AcqTran": {
    "AcquirerCode": "ABSA",
    "SingleStepAuthMode": true
  },
  "BasicTran": {
    "InputType": 5,
    "CurrencyID": "ZAR",
    "ServiceID": "CYCLE-SA.ACCEPT-PAYMENT",
    "Description": "POS transaction with linked card",
    "Amount": 5,
    "ID": "123e4567-e89b-12d3-a456-426614174000",
    "AuxDataInput": {
      "AuxData": {
        "Purchases": [
          {
            "Title": "Item A",
            "Price": "10.00",
            "Quantity": "2",
            "TaxCode": ["VAT1500"]
          },
          {
            "Title": "Item B",
            "Price": "15.00",
            "Quantity": "1",
            "TaxCode": ["VAT1500"]
          }
        ]
      }
    }
  },
  "Card": {
    "CardInputMode": 2,
    "LinkedCardID": 7878
  }
}

Example: Create Cash Payment

{
  "Receipt": null,
  "Location": {
    "Latitude": -26.2041,
    "Longitude": 28.0473
  },
  "Country": "South Africa",
  "CountryCode": "ZA",
  "DeviceInfo": {
    "PhoneManufacturer": "Samsung",
    "PhoneModel": "Galaxy Tab A7",
    "DeviceID": "ZA-DEVICE-7890",
    "DeviceType": "1",
    "AppFramework": "java",
    "OS": "Android",
    "OSVersion": "12.0.0",
    "AppID": "za.cyclepay.client.android",
    "BuildNumber": "2.4.390248"
  },
  "GMT": 2,
  "AppFramework": "java",
  "IP": "102.250.11.33",
  "Lang": "en",
  "Card": null,
  "AcqTran": {
    "AcquirerCode": "CASH"
  },
  "BasicTran": {
    "InputType": 10,
    "ExtTranData": "{\"AgreementNumber\":\"SA987654\",\"ReferenceCode\":\"ABC123\"}",
    "CurrencyID": "ZAR",
    "ServiceID": "CYCLE-SA.ACCEPT-PAYMENT",
    "Description": "Cash transaction for retail POS",
    "Amount": 1,
    "CPFData": null,
    "OfflineTran": null,
    "ID": "ab77d014-1b22-4312-8af7-8c10cbbe9fa3"
  }
}

Response Body Definitions

The structure of the response to a payment creation request. The main object is `Transaction`.

The response contains a detailed `Transaction` object. See the example below for the full structure.

Note on Fiscal Data

If fiscalisation is performed server-side, fiscal receipt data will not be included in the immediate response. It can be retrieved later via a status request or a webhook.

Example Response

{
  "TransactionID": "3F57B184-F03D-4006-BBEE-62CA224E6C42",
  "EMVOnlineProcessingResult": "8A023030",
  "AdditionalAcquiringFields": null,
  "AdditionalAcquiringFieldsTitle": null,
  "TerminalName": "01021911",
  "EMVData": {
    "AID": "A0000000031010",
    "APN": "Visa",
    "TSI": "6800",
    "TVR": "8080208000"
  },
  "RequireSignature": false,
  "Transaction": {
    "ID": "3F57B184-F03D-4006-BBEE-62CA224E6C42",
    "Date": "2025-05-28T07:05:09",
    "Deadline": "2025-05-28T07:21:13.14",
    "Description": "correct chip transaction",
    "Invoice": "ZAFPAY001234",
    "MerchantTranID": null,
    "AcquirerID": "ABSA",
    "AcquirerTranID": "3F57B184",
    "AcquirerApprovalCode": "SIMULATION",
    "Status": "IN-TRANSFER",
    "RRN": "879089231166",
    "TerminalName": "01021911",
    "LinkedCard": null,
    "ClientProductCode": null,
    "AmountOrig": 105.00,
    "Amount": 105.00,
    "AmountCashGot": null,
    "FeeTotal": 1.50,
    "AmountNetto": 103.50,
    "Balance": 0.0,
    "AmountEff": 105.00,
    "AmountRvs": 0.00,
    "CountRvs": 0,
    "PartialReverse": false,
    "FeeTotalEff": 1.50,
    "FeeTotalRvs": 0.00,
    "Latitude": -29.8587,
    "Longitude": 31.0218,
    "HasPhoto": false,
    "PhotoUrl": null,
    "HasSignature": false,
    "SignatureUrl": null,
    "SignatureRequired": false,
    "SignatureRequiredEffective": false,
    "PINMode": 31,
    "CurrencySign": "R",
    "CurrencySignSafe": "ZAR",
    "AmountFormat": "#,##0.00 R",
    "AmountFormatWithoutCurrency": "#,##0.00",
    "Format": {
      "CurrencySign": "R",
      "CurrencySignSafe": "ZAR",
      "AmountFormat": "#,##0.00 R",
      "AmountFormatWithoutCurrency": "#,##0.00",
      "CurrencyE": 2
    },
    "CurrencyID": "ZAR",
    "PosID": 11712,
    "StateDisplay": "Successful",
    "Line1": "Payment",
    "Line2": "Successful",
    "DisplayMode": 1,
    "Operation": "Payment",
    "OperationID": 100,
    "State": 400,
    "Substate": 411,
    "SingleStepAuth": true,
    "InputType": 3,
    "Card": {
      "IIN": "quiz",
      "BIN": "417251",
      "EXP": "2806",
      "PANMasked": "*4207",
      "PANEnding": "4207",
      "BankName": "Standard Bank",
      "BankCountryID": "ZA"
    },
    "ExtTranData": "{\"AgreementRef\":\"123456\",\"LicenceNumber\":\"159489\"}",
    "CardholderName": "JOHANNES/MPHO",
    "ReceiptEmail": null,
    "ReceiptPhone": null,
    "CanCancelCNP": true,
    "CanCancelCNPpartial": true,
    "CanReturnCNP": true,
    "CanReturnCNPpartial": true,
    "CanCancel": false,
    "CanCancelPartial": false,
    "CanReturn": false,
    "CanReturnPartial": false,
    "ReverseCPInputTypes": [3, 4],
    "FiscalInfo": {
      "FiscalStatus": 0,
      "FiscalError": 0,
      "FiscalMessage": null
    },
    "IsNotFinished": false,
    "EMVData": {
      "AID": "A0000000031010",
      "APN": "Visa",
      "TSI": "6800",
      "TVR": "8080208000"
    },
    "ExternalPayment": null,
    "Attachments": null,
    "CanServerFiscalizeForCNPReverse": false,
    "CanFiscalRemoteCorrection": true,
    "ExtID": null,
    "Result": {
      "Code": 0,
      "Message": ""
    },
    "OfflineQueueId": null,
    "PANTags": null,
    "TransPos": {
      "ID": 21261,
      "Email": "agent1@cyclepay.africa",
      "Name": "CyclePay Test Agent",
      "Phone": "+27(11)111-1111"
    }
  },
  "ErrorCode": 0,
  "ErrorMessage": null,
  "Validations": null
}

Prepare Payment

Reverse a Payment