Hosted Payment Page Reference

A detailed reference for all input parameters and postMessage events for the CYCLE Hosted Payment Page.

Input Parameters Reference

All available parameters for constructing the Hosted Payment Page JSON payload.

Parameter	Required	Description
`merchantAccount`	Yes	Your merchant account name provided by CYCLE.
`timestamp`	Yes	Unix timestamp. Valid for 30 minutes to avoid replay attacks.

Parameter	Required	Description
`chargeId`	No	Unique transaction ID (recommended). If not set, CYCLE will generate one.
`price`	Yes	Amount to charge the customer (e.g. 5.00).
`currency`	Yes	ISO 4217 currency code (e.g. ZAR, USD).
`description`	Yes	Description of the item purchased (displayed to customer).
`memo`	No	A string recorded with the charge, useful for internal reference or reconciliation.
`chargeProperties`	No	Optional JSON object of key-value pairs. No = or spaces in keys. Max size: 3500 characters.

Parameter	Required	Description
`customerId`	Yes	Your unique customer ID. Required for reporting and fraud checks.
`customerCountry`	No	ISO 2-letter country code (e.g. ZA). Used for tax/fraud. Defaults to IP geo or UI prompt if not provided.
`customerName`	No	Customer full name.
`customerEmail`	No	Email address (used for receipt if CYCLE sends confirmation).
`customerStateProvince`	No	State/province. Required for some tax regions.
`customerCity`	No	Customer city.
`customerPostalCode`	No	Postal/ZIP code. Required for tax in some countries.
`customerStreetAddress`	No	Street address for tax/shipping.
`customerStreetAddress2`	No	Additional address line.
`customerDOB`	No	Date of birth in YYYY-MM-DD format. Used for fraud checks and age restrictions.
`customerLocale`	No	Language override (e.g. en_US, fr_FR).

Parameter	Required	Description
`successUrl`	No	Redirect URL after successful purchase.
`failureUrl`	No	Redirect URL after failed purchase (decline, fraud, etc).
`cancelUrl`	No	Redirect URL if user cancels the payment.
`flowCompletionUrl`	No	Redirect URL for any result if success/failure/cancel are not defined.
`callbackUrl`	No	Webhook endpoint for real-time notifications (overrides global notification URL if set).
`savePaymentProfile`	No	true to auto-save card info for eligible payment methods.
`showPaymentProfiles`	No	true to show stored profiles to returning users.
`recurrence`	No	Used for recurring billing. Set as { "type": "INITIAL" } to create a token for future use.

Parameter	Required	Description
`mode`	Yes	Must be set to "DEEP_LINK" to use embedded or direct iframe launch.
`paymentMethod`	Yes	Must be set to "CREDIT_CARD" or other supported method.

Events sent from the Hosted Payment Page iframe to your parent page via window.postMessage.

Event	Example JSON	Description
Paywall Opened	`{ "name": "PURCHASE_STATUS", "initialized": true }`	Indicates the Hosted Payment Page is ready. Show iframe if previously hidden.
Order Submitted	`{ "name": "PURCHASE_STATUS", "submitted": true }`	Order submitted but not complete. Switch button from “Back” to “Cancel”.
Success	`{ "name": "PURCHASE_STATUS", "success": true, "pending": false }`	Payment completed successfully. If pending: true, funds not yet captured.
Failure	`{ "name": "PURCHASE_STATUS", "success": false }`	Payment failed (e.g. declined). Update UI accordingly.
Paywall Closed	`{ "name": "PURCHASE_STATUS", "close": true }`	Indicates user closed the Hosted Payment Page manually. Hide iframe.
Resize Event	`{ "message": { "name": "WINDOW_SIZE", "success": true, "payload": { "size": { "width": 666, "height": 1542 }}}}`	Resize your iframe to the provided dimensions.