Direct API Guide

The Cycle REST API is a robust platform that empowers you to seamlessly integrate and customize paywall and billing support tools tailored to your specific needs. These methods are for payment verification, charge/credit processing, and retrieving charge/credit history.

Authentication Required

All Direct API requests require HMAC signature authentication. Please refer to the API Authentication guide for detailed instructions.

Charges & Credits

Search Charges/Credits

This method retrieves a list of charges or credits based on the filter criteria.

GET /api/v3/charges

Query Parameters

Field	Description
`id`	The id of a specific charge / credit. <= 255 characters
`customerId`	The merchant provided ID of the customer this charge / credit belong to. <= 255 characters
`customerEmail`	The Customer Email of charge / credit. <= 255 characters
`lgId`	The lgId is the internal system generated long integer id of the charge / credit entity. <= 255 characters
`numberOfInstallments`	Returns charges that have installments included. 'all' indicates any number of installments. Examples include "3", "3,4". <= 255 characters
`orderStates`	Return only with one of the specified order states. Enum: "SUBMITTED" "CHARGED" "AUTHORIZED" "FUNDS_AUTHORIZED" "REFUNDED" "CHARGED_BACK" "CHARGEBACK_REVERSED" "CREDITED" "CREATED"
`createdAfter`	Return only created after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`createdBefore`	Return only created before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedAfter`	Return only modified after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedBefore`	Return only modified before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`paymentMethod`	Return only for the specified payment method. Enum: "VISA" "MASTERCARD" "AMERICAN_EXPRESS" "DISCOVER" "BOLETTO" "IDEAL"
`paymentType`	Return only for the specified payment type. Enum: "CREDIT_CARD" "DEBIT_CARD" "PREPAID_CARD" "BANK_TRANSFER" "VIRTUAL_ACCOUNT" "DIRECT_DEBIT" "CASH" "CHECK" "OFFER" "WALLET" "CARRIER_BILLING"
`currency`	Search by the currency. Must be a 3-character ISO 4217 currency code e.g. USD.
`gatewayProvidedId`	Search by gateway provided ID.
`properties`	Properties of the charges / credits to filter. A comma separated list of name/value pairs in the form of "name1=value1,name2=value2".
`sort`	Sort result by parameters. A comma separated parameter name and sort direction e.g. lastModified,desc or status,asc
`page`	Starting index of results to fetch. Default: 0
`size`	Size of the block to fetch. Default: 10
`includeCount`	Return total result set count. Default: false

Example Response

{
  "charges": [],
  "total": 0,
  "size": 10,
  "page": 0,
  "includeCount": true
}

Submit a Charge

This method attempts to charge a customer the specified amount. If the customer does not already exist, a new customer will be created.

POST /api/v3/charges

Request Parameters

Field	Required	Description
`command`	Yes	“CHARGE”, “AUTHORIZE”, or “VERIFY”
`id`	No	Unique transaction ID specified by the merchant (<= 63 chars). If not provided, one will be generated.
`memo`	No	Merchant-specific metadata for reporting and notifications (<= 255 chars).
`properties`	No	JSON object of custom name/value pairs.
`lineItemProperties`	No	Array of JSON objects for line-specific properties.
`recurrence`	No	Object with recurrence details for recurring transactions.
`idempotencyId`	No	Unique key to prevent duplicate processing on retries (<= 63 chars).
`lineItem`	Yes	Object containing details of the item being purchased.
`customer`	Yes	Object containing customer details. A new customer is created if the ID doesn’t exist.
`payment`	Yes	Object containing payment method details.
`metadata`	No	Object for optional merchant and processor-specific information.

Example Request

{
 "command": "CHARGE",
 "id": "txn_cycle_demo_001",
 "customer": {
   "id": "customer_123"
 },
 "lineItem": {
   "currency": "ZAR",
   "amount": 25.50,
   "description": "Demo Product"
 },
 "payment": {
   "paymentMethod": "VISA",
   "countryCode": "ZA",
   "accountHolder": "John Doe",
   "cardNumber": "4111111111111111",
   "expirationDate": "2025-12",
   "securityCode": "123",
   "emailAddress": "john.doe@example.com",
   "firstName": "John",
   "lastName": "Doe"
 },
 "metadata": {
     "callbackURL": "https://your-domain.com/notifications",
     "returnURL": "https://your-domain.com/success",
     "failureURL": "https://your-domain.com/failure"
 }
}

Example Response

A 201 status indicates the charge was successfully created; however, it might not have been successfully charged yet. Check the \`status\` field for final confirmation.

{
   "type": "v3_2",
   "id": "txn_cycle_demo_001",
   "LGID": 8722,
   "status": "CHARGED",
   "merchantAccount": "CycleDemo",
   "customer": {
     "id": "customer_123",
     "ipAddress": "103.220.40.188",
     "name": "customer_123",
     "country": "ZA"
   },
   "lineItem": {
     "amount": 25.50,
     "currency": "ZAR",
     "description": "Demo Product"
   },
   "payment": {
     "paymentType": "CREDIT_CARD",
     "paymentMethod": "VISA",
     "firstName": "John",
     "lastName": "Doe",
     "countryCode": "ZA",
     "emailAddress": "john.doe@example.com",
     "cardNumber": "XXXXXXXXXXXX1111",
     "expirationDate": "2025-12"
   },
   "transactions": [],
   "created": "2023-10-27T09:59:58Z",
   "lastModified": "2023-10-27T10:00:00Z"
}

Submit a Credit

This method attempts to credit a customer the specified amount. If the customer does not already exist, a new customer will be created.

POST /api/v3/credits

Request Parameters

Field	Required	Description
`command`	Yes	Fixed as “CREDIT”
`id`	No	Unique transaction ID specified by the merchant (<= 63 chars).
`memo`	No	Merchant-specific metadata (<= 255 chars).
`properties`	No	JSON object of custom name/value pairs.
`lineItemProperties`	No	Array of JSON objects for line-specific properties.
`lineItem`	Yes	Object containing details of the item being credited.
`customer`	Yes	Object containing customer details.
`payment`	Yes	Object containing payment method details for the credit.
`metadata`	No	Object for optional merchant and processor-specific information.

Get Charge Details

This API helps to retrieve a charge or credit transaction detail by its merchant-provided ID.

GET /api/v3/charges/{id}

Example Response

{
   "type": "v3_2",
   "id": "txn_cycle_demo_001",
   "LGID": 8722,
   "status": "CHARGED",
   "merchantAccount": "CycleDemo",
   "customer": {
     "id": "customer_123",
     "ipAddress": "103.220.40.188",
     "name": "customer_123",
     "country": "ZA"
   },
   "lineItem": {
     "amount": 25.50,
     "currency": "ZAR",
     "description": "Demo Product"
   },
   "payment": {
     "paymentType": "CREDIT_CARD",
     "paymentMethod": "VISA",
     "firstName": "John",
     "lastName": "Doe",
     "countryCode": "ZA",
     "emailAddress": "john.doe@example.com",
     "cardNumber": "XXXXXXXXXXXX1111",
     "expirationDate": "2025-12"
   },
   "transactions": [],
   "created": "2023-10-27T09:59:58Z",
   "lastModified": "2023-10-27T10:00:00Z"
}

Update a Charge

This method updates an existing Charge by issuing a new command to it, such as settling a previous authorization or issuing a refund.

POST /api/v3/charges/{id}

Request Parameters

Field	Required	Description
`command`	Yes	“SETTLE”, “AUTH_REVERSAL”, "CANCEL", "REFUND", "CHARGEBACK", "REVERSE_CHARGEBACK"
`memo`	No	Optionally overwrites the memo associated with the charge.
`amount`	No	Specify the amount to refund for partial refunds.
`taxIncludedInPrice`	No	Indicates if tax is included in the refund amount (default: true).
`status`	No	Force a specific status (requires special permissions).
`properties`	No	Add, edit, or remove custom properties.
`idempotencyId`	No	Unique key to prevent duplicate updates on retries (<= 63 chars).
`chargebackDetails`	No	Object with chargeback reason and code.

Example Response

{
   "type": "v3_2",
   "id": "txn_cycle_demo_001",
   "LGID": 8722,
   "status": "CHARGED",
   "merchantAccount": "CycleDemo",
   "customer": {
     "id": "customer_123",
     "ipAddress": "103.220.40.188",
     "name": "customer_123",
     "country": "ZA"
   },
   "lineItem": {
     "amount": 25.50,
     "currency": "ZAR",
     "description": "Demo Product"
   },
   "payment": {
     "paymentType": "CREDIT_CARD",
     "paymentMethod": "VISA",
     "firstName": "John",
     "lastName": "Doe",
     "countryCode": "ZA",
     "emailAddress": "john.doe@example.com",
     "cardNumber": "XXXXXXXXXXXX1111",
     "expirationDate": "2025-12"
   },
   "transactions": [],
   "created": "2023-10-27T09:59:58Z",
   "lastModified": "2023-10-27T10:00:00Z"
}

Search Tax Invoices

This method retrieves a list of tax invoices stored as part of a specific charge.

GET /api/v3/charges/{id}/taxinvoice

Get Tax Invoice

This method downloads a specific tax invoice for an existing transaction.

GET /api/v3/charges/{id}/taxinvoice/{taxInvoiceId}

Get Refundable Amount

This method retrieves the refundable amount, refundable base line item amount, and refundable tax for a charge.

GET /api/v3/charges/{chargeId}/refundAvailable

Example Response

{
  "chargeId": "cyc_af775a25-fc49-47b3-9287-27b83efff622",
  "refundableAmount": 13.57,
  "refuntableBasLineItemAmount": 12.34,
  "refundableTaxAmount": 1.23,
  "refundable": true
}

Bulk Payments

Get Bulk Payment Records

Returns all bulk payment records that match the specified search criteria.

GET /api/v3/bulkpayment

Query Parameters

Field	Description
`merchantAccountId`	Merchant's id.
`merchantAccountName`	Merchant's name.
`createdAfter`	Return only created after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`createdBefore`	Return only created before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedAfter`	Return only modified after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedBefore`	Return only modified before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`batchId`	Batch id.
`status`	Enum: "SUBMITTED" "ACCEPTED" "ERROR". A status represent the result of processing request file.
`page`	Starting index of results to fetch. Default: 0
`size`	Size of the block to fetch. Default: 10
`includeCount`	Return total result set count. Default: false

Example Response

{
  "bulkPaymentRecords": [],
  "size": 0,
  "page": 0,
  "includeCount": true,
  "total": 0
}

Get Bulk Payment Details

Returns all bulk payment details that match the specified search criteria.

GET /api/v3/bulkpayment/detail

Query Parameters

Field	Description
`merchantAccountId`	Merchant's id.
`merchantAccountName`	Merchant's name.
`createdAfter`	Return only created after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`createdBefore`	Return only created before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedAfter`	Return only modified after this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`modifiedBefore`	Return only modified before this date. ISO-8601 format YYYY-MM-DDThh:mm:ssZ
`batchId`	Batch id.
`requestId`	Request id.
`purchaseRecordId`	Purchase record Id
`status`	Enum: "ACCEPTED" "ERROR". A status represent the result of processing request file.
`page`	Starting index of results to fetch. Default: 0
`size`	Size of the block to fetch. Default: 10
`includeCount`	Return total result set count. Default: false

Example Response

{
  "bulkPaymentDetails": [],
  "size": 0,
  "page": 0,
  "includeCount": true,
  "total": 0
}

Configuration

Get Configuration

Returns the merchant's account configuration settings.

GET /api/v3/configuration

Example Response

{
  "value": {
    "defaultCountry": "US",
    "defaultLanguage": "en",
    "requireStateOrProvince": false,
    "requireCountry": false,
    "requireEmail": false,
    "requirePostalCode": false,
    "rapidCheckoutEnabled": true,
    "chargeNotificationURLs": [],
    "properties": {},
    "readOnly": {},
    "defaultTaxModel": "TAX_INCLUDED",
    "defaultTaxCode": "DG",
    "disableMailSending": true,
    "allowTransactionWithFailedTaxQuote": true
  }
}

Get Country List

Returns a list of all countries (in ISO-2 format) that have at least one active payment method.

GET /api/v3/countries

Example Response

{
  "countries": [{}, {}, {}]
}

Get Exchange Rates

This API finds the exchange rate between two currencies. Rates are cached for 8 hours.

GET /api/v3/exchangerates

Example Response

{
  "fromCurrency": "USD",
  "toCurrency": "EUR",
  "exchangeRate": 0.8047965168952942
}

Get Payment Methods

Retrieves data about all payment methods that meet the search criteria.

GET /api/v3/paymentmethods

Example Response

{
  "paymentMethods": [{}]
}

Get Payment Methods and Profiles

Retrieves payment methods and stored payment profiles matching the criteria.

GET /api/v3/paymentmethodsspp

Example Response

{
  "paymentMethods": [{}, {}, {}, {}],
  "paymentProfiles": [{}, {}]
}

Customer Management

Add Customer

Adds a new customer record in the database. The API returns HTTP Status 201 on success.

POST /api/v3/customers

Example Request

{
 "id": "customer_123456",
 "personalInfo": {
   "email": "foo@bar.com",
   "address": {}
 }
}

Example Response

{
 "id": "customer_123456",
 "status": "ENABLED",
 "createdTime": "2014-11-12T04:22:53Z",
 "lastActivityTime": "2014-11-12T04:22:53Z",
 "customerType": "B2B",
 "personalInfo": {
   "firstName": "Jane",
   "lastName": "Doe",
   "dob": "1991-10-29",
   "email": "foo@bar.com",
   "document": "XXXXXXXXXXX8912",
   "documentType": "GSTID",
   "address": {}
 },
 "fraud": {
   "blocked": false,
   "trustLevel": "NEW_CUSTOMER"
 },
 "properties": {
   "Name": "value",
   "Name2": "Value2"
 },
 "paymentProfiles": []
}

Search Customers

Finds all customers matching the specified search criteria.

GET /api/v3/customers

Query Parameters

Field	Description
`id`	Customer ID (3-64 characters).
`status`	Filter by customer status. Enum: "ENABLED", "DISABLED", "DELETED".
`name`	Filter by customer's full name (3-64 characters).
`firstName`	Filter by customer's first name (3-64 characters).
`lastName`	Filter by customer's last name (3-64 characters).
`email`	Filter by email address.
`city`	Filter by city.
`stateProvince`	Filter by state or province.
`postalCode`	Filter by postal code.
`country`	Filter by 2-letter ISO 3166 country code.
`properties`	Encoded, comma-separated list of name-value pairs (e.g., "name1=value1%2Cname2=value2").
`trustLevel`	Filter by trust level. Enum: "UNTRUSTED_CUSTOMER", "RESTRICTED_CUSTOMER", "NEW_CUSTOMER", "STANDARD_CUSTOMER", "TRUSTED_CUSTOMER", "UNRESTRICTED_CUSTOMER".
`block`	Filter by whether the customer has a fraud block or not.
`lgId`	Internal system generated long integer id of the customer entity (<= 255 characters).
`page`	Starting index of results to fetch. Default: 0.
`size`	Size of the block to fetch. Default: 10.
`includeCount`	Return total result set count. Default: false.

Example Response

{
 "customers": [
    {
 "id": "customer_123456",
 "status": "ENABLED",
 "createdTime": "2014-11-12T04:22:53Z",
 "lastActivityTime": "2014-11-12T04:22:53Z",
 "customerType": "B2B",
 "personalInfo": {
   "firstName": "Jane",
   "lastName": "Doe",
   "dob": "1991-10-29",
   "email": "foo@bar.com",
   "document": "XXXXXXXXXXX8912",
   "documentType": "GSTID",
   "address": {}
 },
 "fraud": {
   "blocked": false,
   "trustLevel": "NEW_CUSTOMER"
 },
 "properties": {
   "Name": "value",
   "Name2": "Value2"
 },
 "paymentProfiles": []
}
  ]
}

Update Customer

Updates an existing customer record. This is a partial update; only included fields will be modified.

POST /api/v3/customers/{id}

Customer Block

To block a customer, populate the \`fraud\` object. Set \`blocked\` to false to unblock.

{
  "fraud": {
    "blocked": "true",
    "blockExpireDate": "2024-12-31T23:59:59Z",
    "comments": "Suspicious activity"
  }
}

Example Request

{
 "personalInfo": {
   "email": "foo@bar.com",
   "address": {}
 }
}

Example Response

{
 "id": "customer_123456",
 "status": "ENABLED",
 "createdTime": "2014-11-12T04:22:53Z",
 "lastActivityTime": "2014-11-12T04:22:53Z",
 "customerType": "B2B",
 "personalInfo": {
   "firstName": "Jane",
   "lastName": "Doe",
   "dob": "1991-10-29",
   "email": "foo@bar.com",
   "document": "XXXXXXXXXXX8912",
   "documentType": "GSTID",
   "address": {}
 },
 "fraud": {
   "blocked": false,
   "trustLevel": "NEW_CUSTOMER"
 },
 "properties": {
   "Name": "value",
   "Name2": "Value2"
 },
 "paymentProfiles": []
}

Get Customer

Returns information about an individual customer by their ID.

GET /api/v3/customers/{id}

Example Response

{
 "id": "customer_123456",
 "status": "ENABLED",
 "createdTime": "2014-11-12T04:22:53Z",
 "lastActivityTime": "2014-11-12T04:22:53Z",
 "customerType": "B2B",
 "personalInfo": {
   "firstName": "Jane",
   "lastName": "Doe",
   "dob": "1991-10-29",
   "email": "foo@bar.com",
   "document": "XXXXXXXXXXX8912",
   "documentType": "GSTID",
   "address": {}
 },
 "fraud": {
   "blocked": false,
   "trustLevel": "NEW_CUSTOMER"
 },
 "properties": {
   "Name": "value",
   "Name2": "Value2"
 },
 "paymentProfiles": []
}

Payment Profiles

Add Payment Profile

Adds a new payment profile, or updates an existing one based on payment information.

POST /api/v3/paymentprofiles

Request Parameters

Field	Required	Description
`id`	No	Merchant provided id to uniquely identify the transaction (<= 63 chars).
`name`	No	The customer facing name of the payment profile.
`memo`	No	Non-customer facing merchant metadata about this payment profile.
`customerId`	Yes	Unique id to identify the customer of merchant (<= 63 chars). A customer record with this ID must already exist.
`supportsCashIn`	No	Indicates if the stored payment profile supports cash in.
`supportsCashOut`	No	Indicates if the stored payment profile supports cash out.
`defaultCurrency`	No	ISO 4217 three-letter currency code (e.g., USD).
`payment`	Yes	The payment object with details for the new profile.
`metadata`	No	Optional merchant and processor specific information.
`properties`	No	Custom name/value pairs.

Search Payment Profiles

Returns all payment profiles that match the specified search criteria.

GET /api/v3/paymentprofiles

Query Parameters

Field	Description
`name`	The exact name of payment profile. (<= 255 characters)
`customerId`	A single customer id. (<= 255 characters)
`expirationDate`	Expiration Date of credit card in MMYY, MMYYYY or YYYY-MM format. (4-6 characters)
`memo`	The merchant defined memo field. (<= 255 characters)
`methodType`	Enum: "CREDIT_CARD", "DEBIT_CARD", "PREPAID_CARD", "BANK_TRANSFER", etc.
`page`	Starting index of results to fetch. Default: 0.
`size`	Size of the block to fetch. Default: 10.
`includeCount`	Return total result set count. Default: false.

Get Payment Profile

Retrieves a payment profile by its ID.

GET /api/v3/paymentprofiles/{id}

Get Temporary Payment Profile

Retrieves a payment profile using a random, expiring ID assigned at creation.

GET /api/v3/paymentprofiles/temp/{id}

Update Payment Profile

Updates an existing payment profile. This is a partial update.

POST /api/v3/paymentprofiles/{id}

Request Parameters

Field	Required	Description
`name`	No	The customer facing name of the payment profile.
`memo`	No	Non-customer facing merchant metadata about this payment profile.
`properties`	No	JSON object of custom name/value pairs.
`payment`	Yes	The payment object with details to update.

Delete Payment Profile

Deletes a payment profile by its ID.

DELETE /api/v3/paymentprofiles/{id}

Request KYC Validation

Requests KYC validation for a payment profile.

POST /api/v3/paymentprofiles/{id}/kycverification

Complete KYC Validation

Completes the KYC validation process with the micro-deposit amounts.

POST /api/v3/paymentprofiles/{id}/kyccompletion

Request Body

Field	Required	Description
`kycAmount1`	Yes	This value is inputted by customer for kyc validation.
`kycAmount2`	Yes	This value is inputted by customer for kyc validation.

Installments

Search Installments

Looks up installment information for a BIN and returns `BinInfoDto`.

GET /bin/installmentinfo

Query Parameters

Field	Description
`binNumber`	Select BIN installment data matching the binNumber. (e.g. 411111)
`countryCode`	Select installment data matching the country. (e.g. BR)
`amount`	The transaction amount used to calculate installment amounts. (e.g. 123.45)

Example Response

{
  "bin": "411111",
  "country": "BR",
  "methods": [{}],
  "installmentPlans": [{}]
}

Validation History

Search KYC Validations

Fetches KYC validation details associated with stored payment profiles.

GET /kycverifications

Query Parameters

Field	Description
`storedPaymentProfileId`	The ID of payment profile.
`customerId`	A single customer id.
`status`	A status represent the result of handling kyc completion. (Enum: "APPROVED", "DECLINED")
`page`	Starting index of results to fetch. Default: 0
`size`	Size of the block to fetch. Default: 10
`includeCount`	Return total result set count. Default: false

Example Response

{
  "kycValidations": [],
  "total": 0,
  "size": 0,
  "page": 0,
  "includeCount": false
}

Monitoring

API Monitoring

You can monitor whether Cycle is running in a healthy state and whether notifications to your servers are succeeding using the monitoring APIs.

Get Health Check

Returns service health status information. Any return value other than a HTTP Status 200 OK should be investigated.

GET /healthcheck

Example 503 Response

{
  "code": "SERVICE_UNAVAILABLE"
}

Get Notification Queue

Returns the number of notifications that have failed within the last 10 minutes. Any value other than 0 can indicate a problem.

GET /healthcheck/notificationqueue

Example Response

{
  "abortedTransactions": 3
}

Price Points

Search Price Points

For fixed-priced payment methods like mobile payment providers, this API allows fetching the available price points. This method retrieves the available price points for the specified fixed-price payment method, country and currency.

GET /pricepoints

Query Parameters

Field	Required	Description
`method`	Yes	The fixed-price payment method (e.g., BOKU or ZONG)
`country`	Yes	The ISO country code
`currency`	Yes	The ISO currency code

Example Response

{
  "method": "BOKU",
  "country": "FR",
  "currency": "EUR",
  "pricePoints": [{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{}]
}

API Authentication

Recurring Payments