
Getting Started	Discover our products and devices, learn how our integration process works, and explore the safeguards that protect your business.	Learn more
SDKs	Access SDKs to streamline how you integrate our products into your development flow.	Learn more
API References	Explore our APIs to integrate seamlessly with your platform.	Learn more


Partner Portal	Partner-facing portal workflows and navigation.	Learn more
Merchant Portal	Merchant-facing portal workflows and navigation.	Learn more
Token Portal	Token migration workflows and guidance.	Learn more

				Cover image
	Quick Starts	Start fast with focused guides for common integration flows.	Learn more


Onboard Merchants	Collect details, run checks, submit applications.	Learn more
Accept Payments	Card-present, card-not-present, recurring, and ACH.	Learn more
Manage Finance & Resolve Disputes	Keep margins clear and reduce chargeback impact.	Learn more
Report & Reconcile	Track transactions, funding, and operational performance.	Learn more
Operate With Portals	Give partners and merchants self-serve tools.	Learn more


Hosted Merchant Onboarding	Fastest launch. Hosted, configurable, and white-labelled.	Learn more
Merchant Onboarding via Partner Portal	No build. Submit applications in a portal workflow.	Learn more
Merchant Onboarding via API	Most control. Embed onboarding into your product.	Learn more


Cloud EMV	Card-present for POS and terminals (unified API).	Learn more
Mobile EMV SDK	In-app card-present for iOS/Android (Bluetooth reader).	Learn more
Tap to Pay on iPhone	In-app contactless payments on iPhone without a separate reader.	Learn more
JavaScript SDK	Web checkout with hosted iframe + wallets.	Learn more
Recurring Payments	Stored payment methods + scheduled billing.	Learn more
Paylink	Payment links using SMS or e-mail.	Learn more
ACH Transactions	Bank payments with tokenization.	Learn more
Payment UI	A ready-to-use interface for handling card payments.	Learn more

Solution	Channel	Best for	Integration type	Hardware required
Cloud EMV	In-person (card-present)	POS platforms supporting multiple terminals	REST API	Yes (supported terminals)
Mobile EMV SDK	In-person (card-present)	Mobile apps that want embedded payments	iOS/Android SDK + Mobile Payments API	Yes (VP3300 via Bluetooth)
Tap to Pay on iPhone	In-person (card-present)	iPhone apps that want contactless payments without external hardware	iOS SDK + Mobile Payments API	No
JavaScript SDK	Online (card-not-present)	Hosted checkout + wallet support with reduced PCI scope	JavaScript SDK + backend token submission	No (optional readers supported)
Recurring Payments	Scheduled billing	Subscriptions, installments, maintenance plans	API	No
Paylink	Online (card-not-present)	Link-based payments via SMS or e-mail.	API	No
ACH Transactions	Bank payments	Lower-cost payments and bank-based recurring	API (also supported via JavaScript SDK / PayLink)	No
Payment UI	In-person (card-present)	A ready-to-use interface for handling card payments.	iOS SDK + Mobile Payments API	Yes (VP3300 via Bluetooth)

Property	Type	Description
`isSupported`	Boolean	Indicates whether the current device supports Tap to Pay. If `true`, you can safely launch the Tap to Pay flow.
`errorMessage`	String	A localized message that explains why Tap to Pay is not supported. This value is `nil` when `isSupported` is `true`.

Property	Type	Required?	Description
`amount`	Double	Required	The total transaction amount to charge the customer. Use standard currency format, for example `25.99`.
`customerID`	String	Optional	A unique identifier for the customer in your system.
`invoice`	String	Optional	The invoice number associated with the transaction.
`orderID`	String	Optional	A unique identifier for the order.
`softwareType`	String	Optional	The name of the host application or integration.
`softwareTypeVersion`	String	Optional	The version of your application.

Screen	When shown	User action
Landing	First-time setup	Review the information, then tap Enable Tap to Pay on iPhone to continue.
Loading	During setup and card read	Hold the contactless card or device near the iPhone until the read completes.
Authorizing	After card read	Wait while the payment is processed.
Success	Payment approved	Review the transaction details, then tap Done.
Error	Payment fails or is interrupted	Review the error message, then choose Retry or Cancel.
Signature	After a successful payment, if enabled	Ask the customer to sign on the screen, then confirm.

Issue	What the user sees on the device	Cause
Unsupported device	A message indicating that Tap to Pay is not available on this device. The payment option may be disabled or hidden.	The device is a Simulator or an iPhone model that does not support Tap to Pay.
Passcode disabled	A prompt asking the user to enable a device passcode before continuing.	The device does not have a passcode set, which is required for security.
NFC disabled	A message asking the user to enable NFC or bring the device closer, but payment does not start.	NFC is turned off or not functioning in device settings.
Account linking cancelled	The Tap to Pay setup screen closes or shows a message indicating setup was not completed.	The user declined Apple Terms and Conditions during account linking.
Network error	A message indicating that the connection failed or the payment could not be processed.	The device has no internet connection or unstable network connectivity.
Payment declined	A message stating that the payment was declined, with an option to try again or use a different payment method.	The card issuer rejected the transaction (for example, insufficient funds or security checks).

API	Type	Description
`verifyTapToPayDeviceSupport()`	Method	Runs a device compatibility check.
`isTapToPaySupported`	Property	Returns a quick support check.
`tapToPayViewController`	Method	Launches the UIKit payment flow.
`TapToPayRootView`	View	Launches the SwiftUI payment flow.
`TapToPayDeviceSupportResult`	Struct	Contains support status and an optional error message.
`TapToPayFlowManager.state`	Enum	Represents the current payment state.


Merchant Pricing	Define your fee model and apply it across merchants.	Learn more
Merchant Billing & Funding	Fee calculation + payout schedules.	Learn more
Financial Reporting	Statements, tax forms, and reconciliation exports.	Learn more
Disputes Management	Chargebacks: track cases and submit evidence.	Learn more


Reporting API	Most automation. Pull report data into your systems.	Learn more
Partner Portal (view and export)	No build. View reports in the portal and export to CSV or Excel.	Learn more


Partner Portal	Portfolio ops: onboarding, merchants, reporting, support.	Learn more
Merchant Portal	Merchant self-serve: transactions, refunds, payouts, statements.	Learn more

Device Appearance	Model	Description
	Z6	Secure and compact PIN pad with advanced security, versatile connectivity, and a user-friendly design for seamless payments.
	Z8	Countertop terminal providing secure and efficient transactions, ideal for retail, restaurants, and service industries.
	Z9	Durable wireless terminal for mobile payments, suitable for retail, hospitality, and mobile services.
	Z11	Compact countertop terminal with a touchscreen interface.

Device Appearance	Model	Description
	QD2	Android-based mobile wireless PIN pad for flexible, on-the-go payments.
	QD4	Android-based countertop terminal for businesses needing a stationary POS solution.
	QD3	Standalone wireless Android POS terminal designed for secure and efficient payment processing
	QD3 Pin Pad	Compact Android-based mobile PIN pad that connects to the QD4 terminal via USB.

Device Appearance	Model	Description
	A35	High-performance Android Smart PIN pad for various retail scenarios.
	A80	Countertop device that also functions as a portable indoor terminal.
	A920Pro	Mobile touchscreen Android terminal combining an Android tablet with a powerful payment processor.

Device Appearance	Model	Description
	VP8300	Countertop payment reader supporting EMV chip, magnetic stripe, and NFC contactless payments.
	VP3300	Compact, versatile payment reader that accepts multiple payment methods, including Apple Pay and Google Pay.

Features	Integration Type	Communication Options
Accepts EMV chip cards, magnetic stripe cards, and contactless payments Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Ethernet USB

Features	Integration Type	Communication Options
Accepts EMV chip cards, magnetic stripe cards, and contactless payments Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Countertop Ethernet Wi-Fi

Features	Integration Type	Communication Options
Accepts EMV chip cards, magnetic stripe cards, and contactless payments Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Wireless Ethernet Wi-Fi GPR

Features	Integration Type	Communication Options
Accepts EMV chip cards, magnetic stripe cards, and contactless payments Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Countertop Ethernet Wi-Fi

Features	Integration Type	Communication Options
Supports EMV chip cards, magnetic stripe cards, and NFC contactless payments Internal PIN Pad and contactless Large touch screen Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Wireless GPRS Wi-Fi

Features	Integration Type	Communication Options
Supports EMV chip cards, magnetic stripe cards, and NFC contactless payments Large touch screen Supports external PIN Pad (QD3 PIN Pad) Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Ethernet Wi-Fi

Features	Integration Type	Communication Options
Supports EMV chip cards, magnetic stripe cards, and NFC contactless payments Large touch screen Supports external PIN Pad (QD3 PIN Pad) Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Wi-Fi

Features	Integration Type	Communication Options
Accepts EMV chip cards, magnetic stripe cards, and NFC contactless payments Internal PIN Pad and contactless Large touch screen Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with the QD4 terminal via a USB-to-USB (U-U) cable	Ethernet Wi-Fi Bluetooth 4.0

Features	Integration Type	Communication Options
Smart Android PIN Pad Designed for Multilane Implementations Accepts Contactless, Chip, Magstripe Power Over Ethernet (POE) Utilizes Quest™ PCI-Validated P2PE for secure transactions	Cloud EMV Semi-integration to Quest™ Gateway API	Ethernet WiFi

Features	Integration Type	Communication Options
Smart Android Terminal Accepts Contactless, Chip, Magstripe Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	Ethernet Wi-Fi

Features	Integration Type	Communication Options
Smart and Wireless Android Terminal Accepts Contactless, Chip, Magstripe Large HD screen Utilizes Quest™ PCI-Validated P2PE for secure transactions	Compatible with Cloud EMV	WiFi Wireless GPRS Bluetooth

Features	Integration Type	Communication Options
Accepts Contactless, Chip, Magstripe Utilizes Quest™ PCI-Validated P2PE for secure transactions	Javascript SDK Quest™ Mobile Payments API	Countertop USB

Features	Integration Type	Communication Options
Accepts EMV Chip, Magstripe, Contactless including Apple Pay and Google Pay Utilizes Quest™ PCI-Validated P2PE for secure transactions	Mobile SDK Quest™ Mobile Payments API	Audio jack Bluetooth

Name	Data type	Required?	Description
`pk`	String	Required	Your public API key issued by Xplor Pay to authenticate the SDK.
`enableApplePay`	Boolean	Required	Enables Apple Pay functionality when you set it to `true`.

Name	Data type	Required?	Description
`applePayRequest.total`	String	Required	Defines the total transaction amount and merchant label that appear in the Apple Pay sheet.
`total.label`	String	Required	The merchant’s name displayed to customers in the Apple Pay sheet. For example, Bob’s Canoes.
`total.amount`	String	Required	The total transaction amount to be charged. For example, 50.25
`total.type`	String	Required	Indicates the type of transaction amount. Use final for a fixed total.

Name	Data type	Required?	Description
`total`	Object	Optional	Contains the total payment information.
`total.label`	String	Optional	The name of the merchant shown to the customer.
`total.amount`	String	Required	The total amount to be charged. For example, 0.01
`total.type`	String	Required	Indicates the type of total. Use final for the final amount.

Name	Data type	Required?	Description
`buttonColor`	String	Optional	Defines the color of the Google Pay button. Common values are: `default` `black` `white`
`buttonType`	String	Required	Defines the purpose of the button. Common values are: `buy` `donate` `order` `pay` `subscribe`
`buttonLocale`	String	Required	Specifies the locale for the button text. For example, `en` for English.
`buttonSizeMode`	String	Required	Determines how the button scales. For example, `fill` makes the button expand to fit its container.

Name	Data type	Required?	Description
`baseUrl`	String	Optional	The base URL for the Mobile Payment Transactions API endpoint. Use the sandbox or production URL as appropriate.
`pk`	String	Required	The public key used to authenticate requests to the Mobile Payment Transactions API endpoint.
`enableGooglePay`	Boolean	Optional	Indicates Google Pay integration. Enabled when set to `true`.
`googlePayRequest`	Object	Optional	Contains the payment request configuration for Google Pay. It includes `request` object fields.
`googlePayButtonConfig`	Object	Optional	Defines the appearance and behavior of the Google Pay button. It includes `buttonConfig` object fields.

Using this member…	You can…	Type	Default Value	Remark
`accountNumberMasked`	Decide if the Account Number field should display masked information after the customer exits the field.	`Boolean`	`True`	To unmask the Account Number field when your customer exits this field, set the `accountNumberMasked` member to `False`.
`accountNumberPlaceholder`	Decide the text to display for the Account Number field before your customer provides input.	`String`	`Account Number`	None
`accountTypePlaceholder`	Decide the text to display for the Account Number field before your customer selects it.	`String`	`Account Type`	None
`allowAutoComplete`	Decide if the fields in the Payment Details form should autocomplete.	`Boolean`	`True`	To configure the cardholder-facing implementation, set the `allowAutoComplete` member to `True`. To configure the merchant-facing implementation, set the `allowAutoComplete` member to `False`.
`allowEmbedded`	Decide if JavaScript SDK's host page should be embedded in another page.	`Boolean`	`True`	None
`baseUrl`	Decide if the Xplor Pay Gateway base URL should be set to sandbox or production URL. Note: You must set the `baseUrl` to sandbox or production URL.	`String`	`Null`	None
`blockMetaKeys`	Decide if meta key combinations (alt or ctrl) should be blocked for the hosting page. Some card readers may generate keystrokes that include meta keys even after the card read is complete, causing unnecessary behavior in the browser window.	`Mode`	`False`	The `blockMetaKeys` member allows you to block meta key combinations on all pages containing the Xplor Pay script. This setting blocks certain meta key combinations, except for closing the window (Ctrl + W), opening a new window (Ctrl + N), or opening a new tab (Ctrl + T).
`cardFormatted`	Decide if the card field should be formatted as the customer enters information in the field. Note: To make this setting effective, set the `enableReader` member to `True`.	`Boolean`	`True`	The `cardFormatted` member allows you to display the text in the Card Payment fields in a format similar to how the information appears on the physical card as the customer enters information. To configure the cardholder-facing implementation, set the `cardFormatted` member to `True`.
`cardMasked`	Decide if the card field should display masked information after the customer exits the field.	`Boolean`	`True`	To unmask the Card Payment fields when your customer exits fields, set the `cardMasked` member to `False`. To configure the cardholder-facing implementation, set the `cardMasked` member to `True`.
`cardPlaceholder`	Decide the text to display for the card field before your customer provides input.	`String`	`Card Number`	None
`cardReadCompleteCallback`	Decide the name of the function to call to receive a message after completing the card read.	`String`	`ClearentCardReadComplete`	None
`cardReadStartCallback`	Decide the name of the function to call to receive a message when starting the card read.	`String`	`ClearentCardReadStart`	None
`clearFormOnSuccess`	Decide if the Payment Details form should be cleared on a successful call to `getPaymentToken()`.	`Boolean`	`False`	The `clearFormOnSuccess` member allows you to clear the form in a back-office implementation.
`cvcMasked`	Decide if the CSC field should display masked information after the customer exits the field.	`Boolean`	`True`	To unmask the Card Payment fields when your customer exits this field, set the `accountNumberMasked` member to `False`. To configure the cardholder-facing implementation, set the `cvcMasked` to `True`.
`cvcPlaceholder`	Decide the text to display for the CVC field before your customer provides input.	`String`	`CSC`	None
`cvcRequired`	Decide if the CVC field is mandatory for customer to enter a value.	`Boolean`	`True`	None
`deviceType`	Decide the device type of external keyboard-emulation card reader.	`String`	`Null`	The `deviceType` member allows you to add an external card reader. JavaScript SDK supports following Card Reader: IDTECH
`enableAch`	Decide if the customer should pay with an online check.	`Boolean`	`False`	None
`enableReader`	Decide if an external card reader should be supported for reading cards.	`Boolean`	`False`	You need to add the Card Reader button to start reading the card details using an external keyboard-emulation card reader. JavaScript SDK supports following card reader: IDTECH
`entryModeChangeCallback`	Decide the name of the function to call to receive a message when changing the card entry mode.	`String`	`ClearentEntryModeChange`	None
`errorCallback`	Decide the name of the function to call to receive the `getPaymentToken()` response.	`String`	`ClearentTokenError`	None
`expDateFormatted`	Decide if the Expiration Date field should be formatted on entry.	`Boolean`	`True`	The `expDateFormatted` member allows you to display the text in the Expiration Date field in a format similar to how the information appears on the physical card as the customer enters information. To configure the cardholder-facing implementation, set the `expDateFormatted` to `True`.
`expDateMasked`	Decide if the Expiration Date field should be masked when customer exits the field.	`Boolean`	`True`	To unmask the Expiration Date field when your customer exits this field, set the `expDateMasked` member to `False`. To configure the cardholder-facing implementation, set the `expDateMasked` to `True`.
`expDatePlaceholder`	Decide the text to display for the Expiration Date field before your customer provides input.	`String`	`MMYY`	None
`individualNamePlaceholder`	This member allows you to decide the text to display for the Expiration Date field before your customer selects the field.	`String`	`Name on account`	None
`initialMode`	Decide if the Payment Details form should open in manual card entry mode or keyboard reader mode.	`String`	`Manual`	You need to set the `enableReader` member to `True` before setting the `initialMode` member. When you set the `initialMode` member to `manual` or `reader` mode, the payment form will actively listen for keystrokes generated by the card reader. Your customers will see errors and retries if they enter keystrokes that are part of the card read. We recommend testing this use case before implementation.
`paymentFormId`	Decide the ID of `div` element that will hold the Payment Details form.	`String`	`payment-form`	To avoid conflicts with existing code and page element IDs, set the `paymentFormId` member to a value other than the default.
`paymentTypeCallback`	Decide the name of the function to call the `onPaymentTypeChange()`.	`String`	`ClearentOnPaymentTypeChange`	To call the function, set the `enableReader` member to `ACH`. This function is called when the payment type changes to `card` or `ACH`.
`pk`	Public Key Note: You must set the `pk` member.	`String`	`Null`	None
`routingNumberMasked`	Decide if the Routing Number field should be masked when customer exits the field.	`Boolean`	`True`	To unmask the Routing Number field when your customer exits this field, set the `routingNumberMasked` member to `False`.
`routingNumberPlaceholder`	Decide the text to display for the Routing Number field before your customer provides input.	`String`	`Routing Number`	None
`showValidationMessages`	Decide if validation messages should be displayed below the payment form.	`Boolean`	`True`	To configure the handling of validation messages elsewhere, set the `showValidationMessages` member to `False`.
`styles`	Decide the style for the framed contents.	`String`	`Null`	You can use the IDs and classes from your browser’s Developer tools to style the frame of the payment page.
`successCallback`	Decide the name of the function to call to receive the `getPaymentToken()` response.	`String`	`ClearentTokenSuccess`	This function is called when the `getPaymentToken` generate successful.
`validationCallback`	Decide the name of the function to call to receive the validation messages.	`String`	`ClearentValidation`	None

Using this method…	You can…	Sample Code	Remark
`addMetaKeyBlocker()`	Block meta key combinations (alt or ctrl) for the hosting page. Some card readers may generate keystrokes that include meta keys even after the card read is complete, causing unnecessary behavior in the browser window. Tip: To make this setting effective, set the `enableReader` member to `True`.	`<script> ClearentSDK.addMetaKeyBlocker(); </script>`	This setting blocks certain meta key combinations, except for closing the window (Ctrl + W), opening a new window (Ctrl + N), or opening a new tab (Ctrl + T).
`getPaymentToken()`	Receive a token for payment gateway transaction, calling `successCallback` on success or `errorCallback` on error.	`ClearentSDK.getPaymentToken();`	None
`init(obj)`	Initialize the JavaScript SDK integration and create the Payment Details form for entry.	`// Sandbox URL for testing` `// use Sandbox public key <script src="https://gateway-int.clearent.net/js-sdk/js/clearent-host.js"></script> <script> ClearentSDK.init({ "baseUrl": "https://gateway-int.clearent.net", "pk": "YOUR_SANDBOX_PUBLIC_KEY_HERE", }); </script>`	You can set the properties of the JSON-formatted object when you initialize the JavaScript SDK integration.
`removeMetaKeyBlocker()`	Remove a meta key combination blocker enabled using the `blockMetaKeys` member or the `addMetaKeyBlocker` method.	`<script> ClearentSDK.removeMetaKeyBlocker(); </script>`
`reset()`	Reset the JavaScript SDK integration. Warning: When you use the `reset()` method, the Xplor Pay Payment iFrame is completely removed.	`ClearentSDK.reset();`	You can call `Clearent.init` to initialise the JavaScript SDK integration.
`ClearentCardReadComplete()`	Call the function when the card read process is complete using the USB card reader.	`function ClearentCardReadComplete(){ console.log("Card Read is complete"); }`	You can call the function if it is defined on the host page. This function does not return card data or Europay, Mastercard and Visa (EMV) data to maintain the Payment Card Industry (PCI) compliances.
`ClearentCardReadStart()`	Call the function when the card read process starts using the USB card reader.	`function ClearentCardReadStart(){ console.log("Card Read has started"); }`	You can call the function if it is defined on the host page.
`ClearentEntryModeChange(mode)`	Call the function when the entry mode changes to manual or swipe.	`function ClearentEntryModeChange(mode){ console.log("User set SDK to mode: ", mode); }`	You can call the function if it is defined on the host page.
`ClearentOnPaymentTypeChange(paymentType)`	Call the function to receive a raw server response or a JSON-formatted response data object if `getPaymentToken` returns successfully.	`function ClearentOnPaymentTypeChange(paymentType) { console.log("Payment Type was changed to: " + paymentType); }`	You can call the function if it is defined on the host page.
`ClearentTokenError(responseRaw, responseJSON)`	Call the function to receive a raw server response or a JSON-formatted response data object if `getPaymentToken` returns an error.	`function ClearentTokenError(responseRaw, responseJSON){ console.log("ClearentTokenError"); console.log(responseRaw); console.log(responseJSON); }`	You can call the function if it is defined on the host page.
`ClearentTokenSuccess(responseRaw, responseJSON)`	Call the function to receive a raw server response or a JSON-formatted response data object if `getPaymentToken` is successful.	`function ClearentTokenSuccess(responseRaw,responseJSON){ console.log("ClearentTokenSuccess"); console.log(responseRaw); console.log(responseJSON); // now you can send the token to your server // to complete the transaction via mobile-gateway }`	You can call the function if it is defined on the host page.
`ClearentValidation(messages)`	Call the function to validate the payment form fields information that returns the validation message with a JavaScript array.	`function ClearentValidation(messages) { console.log("ClearentValidation"); console.log(messages); // you can handle these messages and display in your own form // empty messages array indicates no validation errors }`	When the payment fields have valid information, a JavaScript array in the validation message will be empty.

Call this method…	To…
`handleConfigurationErrors`	Receive alerts for configuration-related issues.
`handleCardProcessingResponse`	Monitor issues during the card payment processing.
`lcdDisplay`	Monitor the rest of the communication during the card payment processing.
`successfulTransactionToken`	Receive a JSON Web Token (JWT) after a successful card read to process the payment.

Indication	Status
When the bottom LED (closest to the bottom edge of the card reader, furthest from the ID TECH logo) flashes solid red	The battery is connected to power and charging
When the bottom LED (closest to the bottom edge of the card reader, furthest from the ID TECH logo) flashes amber	The battery is low and needs to be charged
When the bottom LED (closest to the bottom edge of the card reader, furthest from the ID TECH logo) stops flashing	The battery is full

Indication	Mode
The Bluetooth LED is off.	Sleep
The Bluetooth LED flashes a steady blue light.	Stand-by
The Bluetooth LED flashes a blue light every five seconds.	Paired and connected

Feedback type	Enum	Description
User Action	`the_FEEDBACK_USER_ACTION`	This feedback type allows displaying instructions to customers through the card reader during a transaction.
General Information	`the_FEEDBACK_INFO`	This feedback type allows displaying information to customers through the card reader during a transaction.
Bluetooth Information	`the_FEEDBACK_BLUETOOTH`	This feedback type allows displaying information related to Bluetooth connectivity.
Errors	`the_FEEDBACK_ERROR`	This feedback type allows displaying errors to customers through the card reader during a transaction. Errors may occur due to an incorrect card swipe, a damaged chip, failed interaction between the card and the reader, or contactless failures. This feedback type provides error messages to guide customers when they face unsuccessful attempts to enter card details manually.
Not classified	`the_FEEDBACK_TYPE_UNKNOWN`	This feedback type allows displaying information if the framework cannot classify unknown errors returned from the IDTech framework.

Message	Description
PRESS BUTTON ON READER	This message instructs customers to press the button on the card reader. This action connects the card reader via Bluetooth to start a new transaction.
PLEASE SWIPE, TAP, OR INSERT	This message instructs customers to provide the card data using any of the following actions: Swipe: Swipe the card using the card slot of the reader. Tap: Tap the card on the contactless side of the card reader. Tap action only works when the card has a contactless symbol on it. Insert: Insert the EMV chip side of the card into the card slot of the reader.
INSERT/SWIPE CARD	This message instructs customers to provide the card data using any of the following actions: Insert: Insert the EMV chip side of the card into the card slot of the reader. Swipe: Swipe the card using the card slot of the reader.
BLUETOOTH CONNECTED	This message informs customers that the card reader has successfully connected via Bluetooth.
USE MAGSTRIPE	This message instructs customers to use magstripe to swipe the card.
CARD INSERTED	This message informs customers that the card has been inserted into the reader.
CARD READ OK, REMOVE CARD	This message informs customers that the card has been successfully read and instructs customers to remove the card from the reader.
TRY MSR AGAIN	This message informs customers to swipe the card again if the framework fails to read the card.
TAP FAILED. INSERT/SWIPE	This message instructs customers to insert or swipe the card again if contactless interaction fails and informs to them that they cannot use the contactless feature for a new transaction.
RETRY TAP	This message instructs customers to tap the card again if contactless interaction fails due to incorrect tap on the card reader.
CARD HAS CHIP. TRY INSERT	This message instructs customers to insert the card with the EMV chip side first into the card slot of the reader.
USE CHIP READER	This message instructs customers to insert the card with the chip side into the card slot of the reader.
INSERT CARD	This message instructs customers to insert the card with the chip side into the card slot of the reader.
CARD READ ERROR	This message informs customers that something went wrong while the framework was reading the card and start a new transaction.
FAILED TO READ CARD. TRY INSERT/SWIPE	This message informs customers to swipe the card again if the framework fails to read the card and instructs customers to insert or swipe the card again.
FALLBACK_TO_SWIPE_REQUEST	This message informs customers to swipe the card again if the framework fails to read the card and instructs customers to swipe the card again.
BAD CHIP, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE	This message informs customers that the inserted card’s chip is in bad condition. It instructs customers to wait for the green LED to flash to start a new transaction. Additionally, it instructs customers to swipe the card again.
FAILED TO START SWIPE. TRY AGAIN BUT THIS TIME PULL CARD OUT WHEN INSTRUCTED	This message informs customers when the framework fails to process the card data after swiping the card into the reader. Additionally, it instructs customers to insert the card and not remove it until the next instruction.
TIMEOUT	This message informs customers that the transaction has timed out in the process and instructs customers to start a new transaction.

Message	Description
This type (MSD) of contactless is not supported. Insert card with chip first, then start transaction.	This message informs customers when the framework does not support the MSD contactless feature. It instructs customers to insert the card with the chip side first into the card slot of the reader. This action disables the contactless interface for a new transaction.
PRESENT ONE CARD ONLY	This message informs customers when they enter the contactless NFC field with two different contactless cards simultaneously, causing confusion for the framework. It instructs customers to enter the contactless NFC field with only one card.
TAP FAILED. INSERT CHIP CARD FIRST BEFORE TRYING AGAIN. IF PHONE TRY AGAIN OR ASK FOR CARD.	This message instructs customers to insert the card with the chip side first again if contactless interaction fails to read the card. Additionally, it instructs customers to try again if they use an iPhone to provide the card data and the framework fails to process. This message also informs customers to use another form of payment to process the transaction.
SEE PHONE	This message instructs customers to complete any security feature on their iPhone to use the contactless interface of the framework for the transaction.

Message	Description
PLUGIN AUDIO JACK	This message instructs customers to insert the audio jack into the device when the framework configures the connection for the audio jack.
DISCONNECTING BLUETOOTH. PLUG IN AUDIO JACK	This message instructs customers to insert the audio jack into the device when the framework configures the connection for the audio jack. It also informs customers that the Bluetooth is disconnecting in the card reader.
UNPLUG AUDIO JACK BEFORE CONNECTING TO BLUETOOTH	This message instructs customers to remove the audio jack from the device and connect the reader via Bluetooth.
AUDIO JACK CONNECTED	This message informs customers that the audio jack is connected.
AUDIO JACK LOW VOLUME. TURN UP VOLUME AND RECONNECT	This message instructs customers to turn up the volume to use the audio jack reader with the framework.

Message	Description
NEW BLUETOOTH CONNECTION REQUESTED. DISCONNECT CURRENT BLUETOOTH	This message instructs customers to disconnect Bluetooth from the current device and informs customers that a new Bluetooth connection has been discovered.
BLUETOOTH DISCONNECTED	This message informs customers that Bluetooth is disconnected.
DEVICE NOT CONNECTED	This message informs customers when the framework has an issue with the device.
PAYMENT REQUEST AND CONNECTION REQUIRED	This message informs customers when the framework encounters an issue with the connection of the payment request. It also instructs customers to cancel the transaction and start it again.

Message	Description
DEVICE NOT CONNECTED	This message informs customers when the framework has an issue with the device.
PAYMENT REQUEST AND CONNECTION REQUIRED	This message informs customers when the framework encounters an issue with the connection of the payment request. It also instructs customers to cancel the transaction and start it again.

Message	Description
SEARCHING FOR POWERED ON BLUETOOTH READERS	This message informs customers when the framework searches for the card reader to connect via Bluetooth search.
CARD READ OK	This message informs customers when the framework successfully read the card data.
CARD SECURED	This message informs customers when the framework receives the card data and sends the transaction token (JSON Web-based Token) to your app for processing the payment.
GOING ONLINE	This message informs customers when the framework calls to the to secure the card data.
DECLINED RECEIPT SENT, REMOVE CARD	This message informs customers when the transaction is declined and the email describing the transaction send to the user’s email address, provided during the transaction. It also instructs customers to remove the card from the card reader.
Device Firmware version not found	This message informs customers when the framework cannot communicate with the card reader to identify its firmware version. This message appears to customers when using the card reader firmware version 151 or earlier and contactless feature.
Device Kernel Version Unknown	This message informs customers when the framework cannot communicate with the card reader to identify its kernel version.
Reader configured and ready	This message informs customers when the card reader is ready to use.
TRANSACTION STARTED	This message informs customers when the framework starts the payment process.
TRANSACTION FAILED	This message informs customers when the framework failed to process the payment.
CHIP NOT RECOGNIZED, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE	This message informs customers when the framework cannot identify the chip of the card to read the card data. It also instructs customers to remove the card from the card reader and wait until the Green LED flashes before swiping again.
Device connected. Waiting for configuration to complete...	This message informs customers when the framework connects to the device and to wait to complete the configuration of the device.

Message	Description
AMOUNT IS OVER MAXIMUM LIMIT ALLOWED FOR TAP	This message informs customers when the framework identifies that an amount available over the maximum limit to use the contactless feature.

` tag to your code that hosts the payment form. {% code lineNumbers="true" %} ```javascript

``` {% endcode %} 2. Add a ` ``` {% endcode %} 3. Call the `init` method with the base URL to host the payment form and add your public key. {% code overflow="wrap" lineNumbers="true" %} ```javascript ``` {% endcode %} The `baseURL` directs your customers to the hosted payment form where they can enter the payment information. {% hint style="info" %} You can style the payment form, see [Format payment page](/guides/javascript/format-payment-page) for more information. {% endhint %} {% endstep %} {% step %} ### Get JSON Web Token To get a JSON Web Token when a customer submits payment information to process: 1. Add the `ClearentSDK.getPaymentToken` method using promises to access the JWT service. {% code overflow="wrap" lineNumbers="true" %} ```javascript ClearentSDK.getPaymentToken().then( (result) => { console.log("ClearentTokenSuccess"); console.log(result); }, (error) => { console.log("ClearentTokenError"); console.log(error); } ); ``` {% endcode %} {% hint style="warning" %} To receive success or error messages from the SDK without using promises, add callback handlers to your web page when the SDK securely calls the JWT service. {% endhint %} 2. The `ClearentTokenSuccess` callback function securely receives the response from the JWT services, which includes an encrypted JSON Web Token in the `jwt` field. {% code lineNumbers="true" %} ```javascript { "code":"200", "status":"success", "exchange-id":"ID-clearent-mobile-jwt-1-c32bfe39-d454-4e34-8b4f-94d850643e48", "payload":{ "mobile-jwt":{ "jwt":"eyJhbGciOi23UzIh4iJ9.eyJsYXN0LWZvdXIiOiIxMrkP8iwidHlwZSI6Ik1BTlVBTCIsImV4cCI6MTU0NzY0NjU2MSwidG9rZW4iOiIxMTAwMDAwMDAwMDEzNTkyIn0.eT8c_5yUzxCxL2MEtmbG444eTFRW7OxzRF7x4uRIo-U", "last-four":"1111" }, "payloadType":"mobile-jwt" } } ``` {% endcode %} A JSON Web Token (`mobile-jwt`) is *required to* process payments through the [Mobile Transactions](/api-reference/api/payments/mobile/mobile-payment-transactions/mobile-transactions) endpoints. {% endstep %} {% step %} ### Create card token To create a card token when processing the card payments: 1. Add the `create-token` property to your JSON request body of the [Mobile Transactions](/api-reference/api/payments/mobile/mobile-payment-transactions/mobile-transactions) endpoint and set its value to `true`. {% code overflow="wrap" lineNumbers="true" %} ```javascript { "type": "sale", "amount": "15.55", "service-fee": "0.46", "software-type": "Sally's Seashell Shore Software", "software-type-version": "1.0", "software-version": "1.0", "create-token": true, "billing": { "zip": "85284" } } ``` {% endcode %} {% hint style="warning" %} To process **card-not-present** transactions, you must include the `zip` field in the JSON request body. {% endhint %} {% hint style="success" %} Set the `Create-token` property to `false` to process the card payment without generating a token. {% endhint %} The successful response includes a randomly generated Card Token in the `id` field. {% code lineNumbers="true" %} ```javascript { "rel": "token", "href": "/rest/v2/tokens/1100003582050381111", "id": "1100003582050381111" } ``` {% endcode %} A Card Token allows you to process future card transactions using the [Transactions](/api-reference/api/payments/cards-card-not-present/transactions) endpoints. You *must* include the Card Token in the `card` field of the JSON request body. {% endstep %} {% endstepper %} # iOS Framework The **Mobile EMV** SDK enables iOS apps to accept EMV chip card payments via Bluetooth or audio jack using the [IDTech VP3300](/getting-started/devices/id-tech#id-tech-vp3300-reader) card reader. ### **Prerequisites** To enable the Mobile EMV SDK into your iOS app, ensure you have following: ✅ API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} {% stepper %} {% step %} ### Set up mobile card reader To set up the mobile card reader: 1. Turn on the reader. {% hint style="warning" %} The reader must be fully charged before you turn it on. {% endhint %} 2. Enable **Bluetooth** on your iOS device. {% hint style="success" %} The reader automatically pairs with your iOS device when Bluetooth is on. {% endhint %} 3. Insert the chip side of the card into the reader’s slot and wait until the green LED flashes. {% hint style="success" %} This confirms a successful card read. {% endhint %} {% endstep %} {% step %} ### Connect iOS app To connect your iOS app to the card reader: 1. Install SDK dependencies, such as `IDTech.xcframework` , `IDTech.bundle` (v4.0.142 or later) and `CocoaLumberjack.xcframework` . 2. Add the iOS Framework to your project using Carthage. {% code overflow="wrap" lineNumbers="true" %} ```javascript github "Clearent/iOS-framework" carthage update ``` {% endcode %} 3. Import the iOS framework header in your code. {% code overflow="wrap" lineNumbers="true" %} ```ruby #import ``` {% endcode %} 4. Initialize the SDK and connect to the card reader. {% code lineNumbers="true" %} ```objective-c ClearentConnection *connection = [[ClearentConnection alloc] initBluetoothSearch]; [clearentVP3300 startConnection:connection]; ``` {% endcode %} The iOS Framework connects automatically to the card reader using Apple’s Bluetooth implementation through the IDTech library. {% hint style="success" %} The reader’s middle LED flashes *green* when successfully paired. {% endhint %} {% endstep %} {% step %} ### Process payment To process the payment in your iOS app: 1. Configure the SDK to initiate an EMV card transaction that sends the encrypted token to Xplor Pay. {% code lineNumbers="true" %} ```swift ClearentVP3300Config *config = [[ClearentVP3300Config alloc] init]; [config setPublicKey:publicKey]; [config setClearentBaseUrl:baseURL]; config.contactAutoConfiguration = false; config.contactlessAutoConfiguration = false; config.contactless = true; clearentVP3300 = [[Clearent_VP3300 alloc] initWithConnectionHandling:self clearentVP3300Configuration:config]; clearentManualEntry = [[ClearentManualEntry alloc] init]; [clearentManualEntry setClearentBaseUrl:baseURL]; [clearentManualEntry setPublicKey:publicKey]; ``` {% endcode %} 2. Set up a payment request. {% code lineNumbers="true" %} ```swift ClearentPayment *payment = [[ClearentPayment alloc] init]; [payment setAmount:theAmount]; payment.amtOther = 0; payment.type = 0; // Sale payment.timeout = 10; payment.tags = nil; payment.fallback = true; payment.forceOnline = false; ``` {% endcode %} 3. Initiate a card transaction. {% code lineNumbers="true" %} ```javascript ClearentResponse *response = [clearentVP3300 startTransaction:payment clearentConnection:connection]; if (response.responseType != RESPONSE_SUCCESS) { // Notify user transaction could not be started } ``` {% endcode %} The Mobile EMV SDK reads the card and encrypts the card data. 4. Add the callback handlers to receive the successful message from the Mobile EMV SDK. {% code lineNumbers="true" %} ```objective-c - (void)successTransactionToken:(ClearentTransactionToken *)token { // Send the encrypted JWT to the Mobile Payments API // POST /rest/v2/mobile/transactions/sale } ``` {% endcode %} The Mobile EMV SDK returns an encrypted JSON Web Token (JWT) that contains the transaction data. 5. Use the POST method to send the transaction request to the [Mobile Payment Transactions](/api-reference/api/payments/mobile/mobile-payment-transactions) endpoint to process the payment. {% endstep %} {% endstepper %} # Payment UI Integrate the **Payment UI** wrapper to add a built-in interface for accepting card payments using the VP3300 reader. ### **Prerequisites** To integrate and launch the payment UI flow, ensure you have following: :white\_check\_mark: An API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} :white\_check\_mark: A public key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} :white\_check\_mark: A sandbox URL for testing the integration. {% hint style="info" %} Contact [Xplor Pay Getting Started](https://xplorpay.com/getting-started/) to get Sandbox URL. {% endhint %} {% stepper %} {% step %} ### **Add Podfile to the project** To add and configure a Podfile in your project: 1. Create or open your Xcode project. 2. Navigate to the project root directory. Open Terminal and run: {% code title="" overflow="wrap" lineNumbers="true" %} ```shellscript cd ``` {% endcode %} 3. Initialize CocoaPods. Run: {% code title="" overflow="wrap" lineNumbers="true" %} ```shellscript pod init ``` {% endcode %} {% hint style="info" %} If CocoaPods is not installed, install it by running: {% endhint %} {% code title="" overflow="wrap" lineNumbers="true" %} ```shellscript sudo gem install cocoapods ``` {% endcode %} 4. Open and edit the Podfile. Replace the contents with the following: {% code title="pod file" overflow="wrap" lineNumbers="true" %} ```ruby source 'https://github.com/xplor-pay/CocoaPods.git' source 'https://github.com/CocoaPods/Specs.git' # Uncomment the next line to define a global platform for your project # platform :ios, '13.0' target 'PROJECTNAME' do # Comment the next line if you don't want to use dynamic frameworks use_frameworks! pod 'ClearentIdtechIOSFrameworkPod', '4.0.158' # Pods for ExampleSwift end ``` {% endcode %} 5. Update the target name and pod version. * Replace `PROJECTNAME` with your Xcode target name. * Verify that you are using the latest pod version. 6. Install the dependencies. Run: {% code title="" overflow="wrap" lineNumbers="true" %} ```shellscript pod install ``` {% endcode %} 7. Open the `.xcworkspace` file generated by CocoaPods. The Podfile is added and configured. CocoaPods installs the dependencies and updates your project with the required settings and build configurations. {% endstep %} {% step %} ### Import the framework In the file where you trigger the payment flow, import the framework: {% code title="" overflow="wrap" lineNumbers="true" %} ```swift import ClearentIdtechIOSFramework ``` {% endcode %} The framework is available in your code file, enabling you to access APIs required to initiate the payment flow. {% endstep %} {% step %} ### Initialize the SDK Before presenting the payment UI, initialize the SDK with your API credentials: {% code title="" overflow="wrap" lineNumbers="true" %} ```swift ClearentUIManager.shared.initialize( with: ClearentUIManagerConfiguration( baseURL: "", apiKey: "", publicKey: "", softwareType: "", softwareTypeVersion: "" ) ) ``` {% endcode %} #### Configuration values Use the following values when configuring the SDK:

Field name	Data type	Required?	Description
`baseURL`	String	Required	The API endpoint for the selected environment. Use the sandbox URL (`https://gateway-int.clearent.net)` for testing. Use the production URL (`https://gateway.clearent.net)` for live transactions.
`apiKey`	String	Required	The API key associated with your account and environment. Provided to you during onboarding with Xplor Pay.
`publicKey`	String	Required	The public key associated with your account and environment. Provided to you during onboarding with Xplor Pay.
`softwareType`	String	Required	The name of your application used for support purposes. Maximum length is 255 characters.
`softwareTypeVersion`	String	Required	The version of your application used for support purposes. Maximum length is 255 characters.

The SDK is initialized with your credentials and environment. Your app is ready to present the payment UI. {% endstep %} {% step %} ### Launch the payment UI From your view controller, create a `PaymentInfo` object and present the payment UI: {% code title="" overflow="wrap" lineNumbers="true" %} ```swift let paymentInfo = PaymentInfo( amount: 20.00, customerID: "", invoice: "", orderID: "", billing: ClearentIdtechIOSFramework.ClientInformation, shipping: ClearentIdtechIOSFramework.ClientInformation, softwareType: "" ) ClearentUIManager.shared.paymentViewController( paymentInfo: paymentInfo, completion: completion ) ``` {% endcode %} This call presents the full payment flow, including card reader pairing, transaction input, and receipt handling. No additional configuration is required for a basic integration. {% endstep %} {% step %} ### Select the payment method {% hint style="info" %} Call this method when the user switches between payment options. {% endhint %} 1. Use the `cardReaderPaymentIsPreferred` property to control which payment method is shown: * `true` → Uses the card reader flow. * `false` → Displays the manual card entry form. 2. Set this property before presenting the payment UI. The `PaymentViewController` reads this value to determine which flow to display. {% code title="" overflow="wrap" lineNumbers="true" %} ```swift func updatePaymentMethod(useCardReader: Bool) { ClearentUIManager.shared.cardReaderPaymentIsPreferred = useCardReader } ``` {% endcode %} {% endstep %} {% endstepper %} The payment UI is displayed, allowing users to complete transactions using either a card reader or manual entry. # Android Framework The **Mobile EMV** SDK enables Android apps to accept EMV chip card payments via Bluetooth or audio jack using the [IDTech VP3300](/getting-started/devices/id-tech#id-tech-vp3300-reader) card reader. ### **Prerequisites** To enable the Mobile EMV SDK into your iOS app, ensure you have following: ✅ API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} {% stepper %} {% step %} ### Set up mobile card reader To set up the mobile card reader: 1. Turn on the reader. {% hint style="warning" %} The reader must be fully charged before you turn it on. {% endhint %} 2. Enable **Bluetooth** on your Android device. {% hint style="success" %} The reader automatically pairs with your Android device when Bluetooth is on. {% endhint %} 3. Insert the chip side of the card into the reader’s slot and wait until the green LED flashes. {% hint style="success" %} This confirms a successful card read. {% endhint %} {% endstep %} {% step %} ### Connect Android app To connect your Android app to the card reader: 1. Add the required .jar files from `android-idtech-sdk/sdk/lib` in your Android project. 2. Add the `PublicOnReceiverListener` object to receive messages from the card reader. 3. Add the `ApplicationContext` or `ApplicationContext3In1` object to enable the card reader modes (DIP/SWIPE/CONTACTLESS). 4. Add the `DeviceFactory` object to connect your app with the VP3300 reader. 5. Configure the card reader. {% code lineNumbers="true" %} ```javascript device_configurePeripheralAndConnect(); registerListen(); ``` {% endcode %} 6. Ensure the card reader is ready. {% code lineNumbers="true" %} ```javascript isReady(); // Wait for readiness before starting a transaction ``` {% endcode %} {% endstep %} {% step %} ### Process payment To process the payment in your Android app: 1. Initiate a card transaction. {% code lineNumbers="true" %} ```javascript device_startTransaction(); ``` {% endcode %} 2. Generate a JSON Web Token (JWT) for manual card entry. {% code lineNumbers="true" %} ```javascript manualCardTokenizer.createTransactionToken(manualEntry); ``` {% endcode %} 3. Use the POST method to send the transaction request to the [Mobile Payment Transactions](/api-reference/api/payments/mobile/mobile-payment-transactions) endpoint to process the payment. {% endstep %} {% endstepper %} # Recurring Payments The **Recurring Payments** engine securely stores customer information, including e-mail address, billing address, first name, and last name. The [Recurring Payments Service](/api-reference/api/payments/recurring-payments-service) allows you to: * Create customers and customer tokens for future payment process. * Schedule payment plans at various frequencies. * Automatically process payments according to the defined schedule. ### Prerequisites To process recurring payments, ensure you have following: ✅ An active Xplor Pay account. {% hint style="info" %} Contact to [Xplor Pay](https://xplorpay.com/contact/) to create an active account. {% endhint %} ✅ API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} {% stepper %} {% step %} ### Create customer To create a customer: 1. Use the POST method. 2. Send the customer request to the [Customer](/api-reference/api/payments/recurring-payments-service/customer) endpoint with required fields. The success response returns the customer key in the `customer-key` field. {% endstep %} {% step %} ### Create customer token To create a customer token: 1. Use the POST method. 2. Include the `customer-key` in the request header for authentication. See the `customer-key` field in the successful response from the create customer endpoint. 3. Send the request to the [Customer Token](/api-reference/api/payments/recurring-payments-service/customer-token) URL with required fields. The success response returns the customer payment token and card details. {% endstep %} {% step %} ### Create payment plan To create a payment plan: 1. Use the POST method. 2. Send the request to the [Payment Plans](/api-reference/api/payments/recurring-payments-service/payment-plans) endpoint URL with required fields. The success response returns the `plan-key` for specified date range payment frequency that confirm the payment plan is created and activated for the customer. {% hint style="info" %} See [Recurring Payments Service](/api-reference/api/payments/recurring-payments-service) for more information. {% endhint %} {% endstep %} {% endstepper %} # ACH Transactions The **ACH Transactions** solution lets you accept direct debit and credit payments securely through the Automated Clearing House (ACH) network. {% hint style="info" %} Third-party providers such as Paya and DCS supports to process ACH payments and manage reporting. {% endhint %} ### **Prerequisites** To process ACH transactions, ensure you have following: ✅ Integrated JavaScript SDK. {% hint style="info" %} See [JavaScript](/guides/javascript) to integrate. {% endhint %} ✅ API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} :white\_check\_mark: A sandbox URL for testing the integration. {% hint style="info" %} Contact [Xplor Pay Getting Started](https://xplorpay.com/getting-started/) to get Sandbox URL. {% endhint %} {% stepper %} {% step %} ### Set up ACH payment form To set up the the ACH payment form using the [Add payment form](/guides/javascript/add-payment-form): 1. Add a `

` tag to host the ACH payment form. {% code lineNumbers="true" %} ```javascript

``` {% endcode %} 2. Include the JavaScript SDK library. {% code lineNumbers="true" %} ```javascript ``` {% endcode %} 3. Initialize the SDK with your sandbox base URL and public key. {% code lineNumbers="true" %} ```javascript ``` {% endcode %} The ACH payment form appears on your webpage with fields for bank account number, routing number, and account type. {% endstep %} {% step %} ### Get JSON Web Token To get a JSON Web Token: 1. Add the `getPaymentToken()` method to your site to receive a success response. {% code lineNumbers="true" %} ```javascript ClearentSDK.getPaymentToken().then( (result) => { console.log("ACH Token Success"); console.log(result); }, (error) => { console.log("ACH Token Error"); console.log(error); } ); ``` {% endcode %} The response includes a `jwt` field with the tokenized ACH payment authorization. {% code lineNumbers="true" %} ```javascript { "code": "200", "status": "success", "exchange-id": "ID-clearent-mobile-jwt-1-c32bfe39-d454-4e34-8b4f-94d850643e48", "payload": { "mobile-jwt": { "jwt": "eyJhbGciOi23UzIh4iJ9...", "last-four": "6789" }, "payloadType": "mobile-jwt" } } ``` {% endcode %} {% endstep %} {% step %} ### Process ACH payment To process the ACH payment: 1. Use the POST method. 2. Include the `mobile-jwt` token in the request headers for authentication. {% hint style="info" %} See the `jwt` field in the successful response from the JavaScript SDK. {% endhint %} 3. Send a transaction request to the [ACH Transaction](/api-reference/api/payments/ach/ach-transaction) endpoint with required fields. The success response returns the ACH transaction status as `Pending`, `Approved`, or `Failed` in the `status` field. {% endstep %} {% endstepper %} # Disputes Management The **Disputes** section in the Merchant Portal displays dispute case activities and related details. It also allows you to respond when applicable. You can manage disputes based on the following case types: * **Retrieval Request**: Requires you to provide additional information related to the original sale transaction. * **Chargeback**: Requires you to reverse the disputed credit card sale to the cardholder or issuing bank. * **Pre-Arbitration**: You cannot respond directly. You may receive an e-mail with instructions to pursue the dispute. {% hint style="warning" %} Pre-Arbitration cases may incur significant fees for the losing party. {% endhint %} * **Arbitration**: You cannot respond directly. You may receive an e-mail with instructions to pursue the dispute. {% hint style="info" %} For more information, contact the **Chargeback & Disputes Department**. Make sure to have the case number available when pursuing or accepting a dispute. {% endhint %} #### Prerequisites To manage disputes, ensure you have following: ✅ An active Xplore Pay account. {% hint style="info" %} Contact to [Xplor Pay](https://xplorpay.com/contact/) to create an active account. {% endhint %} ✅ An API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get API access key. {% endhint %} {% stepper %} {% step %} ### Manage disputes via Merchant Portal To manage disputes via Merchant Portal: 1. Go to the [Merchant Portal](https://auth.clearent.net/oauth2/aus4ulyubshD7M0yf697/v1/authorize?client_id=0oa6ggt30dFSxSVxX697\&redirect_uri=https%3A%2F%2Fmy.clearent.net%2Fui%2Fauth%2Fpost-login\&response_type=code\&scope=openid+profile\&state=09ec3d9fa9f14639a90fce520e368774\&code_challenge=FG5jrxz1jKmuxhZlJmeIuIRC0Cqf2GkDimo2TeVShu0\&code_challenge_method=S256). 2. **Sign in** with your Xplor Pay credentials. The **Home** page appears. 1. In the left menu, select **Disputes**. The Disputes page shows a list of disputes under the **New Activity** tab. The New Activity tab shows the number of new cases that need a response. {% hint style="warning" %} You *must* have the **MerchantHomeUser** role to access the Disputes page. Data on the Disputes page is available for **13** months. {% endhint %} {% endstep %} {% step %} ### Manage disputes via Disputes API The following table describes endpoints and HTTPS methods to manage disputes via Disputes API.

Endpoint	Method	Description
`/v1.0/reporting/merlincaseaction/``MerchantDisputes`	GET	This endpoint retrieves a list of disputes for a specific merchant.
`/v1.0/reporting/merlincaseaction/``MerchantDisputesHistory``/``{caseNumber}`	GET	This endpoint retrieves the history of a specific dispute.
`/v1.0/reporting/merlincaseaction/``MerchantDisputesCaseActivity``/``{caseNumber}`	GET	This endpoint retrieves the activity and responses for a specific dispute. If the dispute has no response record, the endpoint returns an empty success response.
`/v1.0/``responses`	POST	This endpoint uploads transaction evidence for a specific dispute.

{% endstep %} {% endstepper %} # Reporting The **Reporting** solution lets you manage standard and enhanced reports related to merchants, transactions, pricing, disputes, and more. #### **Prerequisites** To manage reports, ensure you have following: :white\_check\_mark: An active Xplor Pay account. {% hint style="info" %} Contact to [Xplor Pay](https://xplorpay.com/contact/) to create an active account. {% endhint %} ✅ A sandbox URL for testing the integration. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get a sandbox URL {% endhint %} ✅ API access key issued to you by Xplor Pay. {% hint style="info" %} Visit [Let's Get Started - Xplor Pay](https://xplorpay.com/getting-started/) to get an API access key. {% endhint %} {% stepper %} {% step %} ### **Retrieve report via Reporting API** To retrieve the Standard and Enhanced report: 1. Use the GET method. 2. Send the request to the [Standard Reporting](/api-reference/api/reporting/standard-reporting) or [Enhanced Reporting](/api-reference/api/reporting/enhanced-reporting) endpoint URL. The following table describes the query parameters to include in the endpoint URL.

Name	Data type	Required?	Description
`categoryName`	String	Required	The category name of the report. Use `standard` for standard reports and `reporting` for enhanced reports.
`reportName`	String	Required	The name of the report. For a list of available standard and enhanced reports, see /spaces/yN9CLsR8tlS8G8avRMB5/pages/iv6Rfs96O6NQMrethdwK.

This endpoint returns a successful response, including merchant, transaction, dispute, or merchant and portfolio activity details in JSON format according to the report type. {% endstep %} {% step %} ### Download enhanced report via Partner Portal To download the enhanced report: 1. Go to the [Partner Portal](https://auth.clearent.net/oauth2/aus4ulyubshD7M0yf697/v1/authorize?client_id=0oa6ggt30dFSxSVxX697\&redirect_uri=https%3A%2F%2Fmy.clearent.net%2Fui%2Fauth%2Fpost-login\&response_type=code\&scope=openid+profile\&state=99cec299c624421c9aa81130c0f2d512\&code_challenge=5fMIzA_gkDBkCRpjufsK54nrOfbNfL_UEicUMtEOvmc\&code_challenge_method=S256). 2. **Sign in** with your Xplor Pay credentials. 3. On the dashboard, select **Reports**. 4. On the **Reports** page, find the report you want. 5. Select **Generate Report** next to the report. The report downloads in Excel or CSV format. {% endstep %} {% endstepper %} {% hint style="info" %} Subscribe to the Xplor Pay Reporting to manage specific reports. See [Broken mention](broken://spaces/yN9CLsR8tlS8G8avRMB5/pages/iAQC3j4wFuFOOYWHdNwW) for more information. {% endhint %} # Overview Our RESTful APIs provide a standardized interface for merchant onboarding and payment processing. These endpoints support consistent, scalable, and easy integration across multiple systems. The APIs also help you retrieve reports and manage disputes programmatically. The following sections help you integrate with our APIs.


API Core Standards	Learn the core standards of the APIs, including data formats, HTTP methods, and authentication requirements.	Learn More
Webhooks	Explore webhooks to receive the real-time event notifications.	Learn More
Resources	Access test data, result codes, and reference materials to support your integration.	Learn More

Dive into product-specific APIs that power your integrations.


Merchant Onboarding API	Automate merchant onboarding setup or use a UI‑driven, hosted onboarding experience.	Learn More
Payments API	Process payments through multiple methods, including card, mobile, and ACH.	Learn More
Disputes API	Retrieve and manage dispute cases, including dispute reporting and merchant responses.	Learn More
Reporting API	Access a suite of financial and operational reports providing visibility across multiple merchants.	Learn More

# API Core Standards This page describes the core standards that support the integration with our APIs. It covers supported data formats, HTTP methods, and security requirements for making secure and consistent API requests. ### Supported data format Each endpoint supports JavaScript Object Notation ([JSON](https://en.wikipedia.org/wiki/JSON)) for both request and response data. ### HTTP methods Each endpoint supports the standard [HTTP](https://en.wikipedia.org/wiki/HTTP) methods based on its purpose. * **GET**: Retrieves data. * **POST**: Creates a new resource or submit data for processing. * **PUT**: Updates an existing resource. * **DELETE**: Removes a resource. ### Security requirements Our APIs use [Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) to protect the payment and merchant data. {% hint style="warning" %} Requests that use TLS versions earlier than 1.2 are blocked by the firewall. {% endhint %} ### Authentication Our APIs require an `Access Key` and `API Key` for authentication. {% hint style="info" %} Contact [Xplor Pay](https://docs.xplorpay.com/getting-started) to get an Access Key and API Key. {% endhint %} An `Access Key` is required for: * [Merchant Onboarding API](/api-reference/api/merchant-onboarding) * [Disputes API](https://docs.xplorpay.com/api-reference/api/disputes) * [Reporting API](https://docs.xplorpay.com/api-reference/api/reporting) {% hint style="success" %} You must include the required Access Key in the authentication headers of every request. {% endhint %} An `API Key` is required for [Payments API](/api-reference/api/payments). {% hint style="success" %} You must include the required API Key in the authentication headers of every request. {% endhint %} # Webhooks Webhook allows you to receive notifications when specific events occur, such as changes to a merchant account or application submission. Instead of repeatedly polling the API for updates, your endpoint receives HTTP requests instantly making your integration more efficient, scalable, and responsive. For more information on webhooks, refer to the following articles: * [Prerequisites](/api-reference/webhooks/prerequisites) * [Register Endpoint](/api-reference/webhooks/register-url) * [Webhook Subscriptions](/api-reference/webhooks/webhook-subscriptions) * [Working with Webhooks](/api-reference/webhooks/working-with-webhooks) * [Transaction Webhook](/api-reference/webhooks/working-with-webhooks/transaction-webhooks) * [Onboarding Webhooks](/api-reference/webhooks/working-with-webhooks/merchant-onboarding-webhooks) * [Equipment Tracking & Activation Webhooks](/api-reference/webhooks/working-with-webhooks/equipment-tracking-and-activation-webhooks) # Prerequisites Before you start using webhooks, ensure you meet the following prerequisites: ### Technical requirements * Create a publicly accessible HTTPS endpoint that can receive and process webhook payloads. * Implement proper security measures to validate webhook signatures. (Applicable to Transaction Webhooks only) * Set up an appropriate error handling and retry logic. ### Webhook configuration Register your Webhook URL with our integration team for configuration. Webhook URLs will be configured on the merchant account to receive POST events. The accessible HTTPs POST endpoint is prepared to: * Accept incoming HTTP POST requests. * Respond with an HTTP `200`` ``OK` status code to acknowledge successful receipt. ### **Webhook configuration by user type** You can manage registered webhooks according to your need. #### **Software Partners** The webhook configuration applies during the account setup. {% hint style="info" %} The setup process differs depending on the webhook type. {% endhint %} #### **Virtual Terminal Users** {% hint style="warning" %} Users with an **Account Administrator** role can only configure webhooks in the **Virtual Terminal**. {% endhint %} To add a webhook URL in the Merchant Portal: 1. Go to **VT Settings** > **Terminal**. 2. Select the **Enable Transaction Alert**. 3. Add your URL to the **Transaction Alert Callback URL** field. 4. Click **Save Terminal** Settings. {% hint style="info" %} For more information about Virtual Terminal, see [Virtual Terminal](https://docs.xplorpay.com/merchant-portal/guides/virtual-terminal). {% endhint %} # Register URL To register your URL, send the endpoint details to our Integrations team. The Integrations team will complete the registration on your behalf and confirm once your endpoint is successfully configured. {% hint style="warning" %} Ensure that your endpoint supports HTTPS and can handle requests sent from the Integration team. {% endhint %} ### **Secure endpoint** To secure the endpoint: * Use HTTPS endpoint. * Restrict IP addresses if applicable. ### **Verify your signature** Each webhook request includes a secure signature header to confirm its authenticity. Verifying this signature helps ensure the payload was sent by Xplor Pay. {% hint style="info" %} Signature verification is applicable for Transaction Webhooks only. Other webhooks do not include signature validation. {% endhint %} ### **Webhook notifications** Once your endpoint is registered and webhooks are configured, you will begin receiving event notifications relevant to your merchant account. The code sample of webhook notification as below: {% code lineNumbers="true" %} ```json { "event": "Manual Review", "merchantId": "6588949900000011", "payload": null } ``` {% endcode %} {% hint style="warning" %} The `payload` value varies by event type. Some events return `null`, while others include additional JSON data relevant to the event. {% endhint %} ### **Retry logic** If your endpoint does not acknowledge receipt of a webhook (i.e., returns a `non-2xx` status), the system will automatically retry the callback. A `2xx` status code (e.g., `200 OK`) indicates successful receipt of the webhook, and no retry will be attempted. `Non-2xx` status codes (e.g., `400 Bad Request`, `500 Internal Server Error`) indicate failure. The system will retry the request based on the retry policy. * **Total Attempts:** Up to 3 delivery attempts * **Retry Strategy:** Exponential backoff is applied between each attempt This ensures reliable delivery of webhook events, even if your endpoint is temporarily unavailable. {% hint style="warning" %} Ensure your server responds with a `2xx` status code upon successful receipt to avoid missed events. {% endhint %} ### **Test webhook** To test your webhook integration, make sure your endpoint returns a proper HTTP status code to indicate the result of processing the request. To help you test different webhook response scenarios in the INT (integration) environment, the system recognizes special keywords in the merchant’s **DBA (Doing Business As)** name field. Use the following naming conventions to simulate specific onboarding outcomes: * **\[DECL]** – The application will be marked as **Declined** after signing. A webhook will be triggered with the "Declined" status. * **\[PEND]** – The application will move to **Pended** status after signing. You will receive a webhook indicating this status change. * **\[APPR]** – The application will be marked as **Approved** after signing, and a corresponding webhook will be sent. {% hint style="warning" %} Ensure that the DBA name includes the exact keyword in brackets (e.g., `MyStore [DECL]`) to trigger the appropriate behavior in the INT environment. {% endhint %} # Webhook Subscriptions Multiple webhook subscription types are available to help you stay informed about key events related to merchant onboarding, transaction activity, and equipment handling. These webhooks deliver real-time notifications to your configured endpoints, allowing for more responsive and automated workflows. #### **1. Transaction Webhook** Delivers real-time notifications for transaction events, including successful payments, declines, and refunds. Ideal for updating dashboards, triggering email receipts, or managing reconciliation. #### **2. Onboarding Webhooks** Provides updates on the merchant onboarding process. Notifications include application status changes, required corrections, and terminal shipping progress. #### **3. Equipment Tracking and Activation Webhooks** Sends alerts when payment terminals are shipped and enables merchants to activate their terminals upon delivery. {% hint style="warning" %} Onboarding and equipment webhooks aren't triggered by transactions but are essential for setting up and enabling payment processing events. {% endhint %} --- [Next Page](/llms-full.txt/1)

Message	Description
AUDIO JACK ATTACHED	This message informs customers when the framework identifies that an audio jack has been attached to the device.
CONNECTING AUDIO JACK	This message informs customers when the framework identifies that an audio jack is connecting to the device.
AUDIO JACK REMOVED	This message informs customers when the framework identifies that an audio jack has been removed from the device.
AUDIO JACK DISCONNECTED	This message informs customers when the framework identifies that an audio jack has been disconnected from the device.
Powering up reader...	This message informs customers when the framework identifies that an audio jack is powering up to the device.

Message	Description
Card read error	This message informs customers when the framework has encountered an error during the card read.
CVM Unsupported. Insert card with chip first, then start transaction. Or try swipe.	This message informs customers when the framework cannot support the Cardholder Verification Method. It also instructs customers to insert the card with chip side first or swipe the card and start the transaction process.
Card declined	This message informs customers when the framework declines the card offline.
TIMEOUT	This message informs customers when the framework has timed out the request during the payment process.
Create Transaction Token Failed	This message informs customers when the framework cannot secure the card data and cannot send the transaction token (JSON Web-based Token) to your app for processing the payment.
Sending Declined Receipt Failed	This message informs customers when the framework has declined the payment process and failed to connect to the servers to send an e-mail to the customer. The email request process is separate from the payment process and can also fail due to slow or no internet connection.
Failed to read card	This message informs customers when the framework has failed to read the card.
DISABLE CONFIGURATION REQUEST TO RUN TRANSACTION	This message instructs customers to stop configuration request when the framework is starting the transaction process during the configuration.
READER NOT CONFIGURED	This message informs customers when the framework has determined that the card reader is not configured.
TRANSACTION FAILED	This message informs customers when the framework failed to process the payment.
UNABLE TO GO ONLINE	This message informs customers when the framework cannot connect the servers due to slow or no internet connection.
PAYMENT REQUEST NOT FOUND	This message informs customers when the framework cannot determine the payment request.
TERMINATED	This message informs customers when transaction cannot succeed and has been terminated from the IDTech framework perspective. It also instructs customers to disable the contactless interface as the IDTech framework has indicated that the contactless interface cannot work. The framework will restart the transaction.
CARD UNSUPPORTED	This message informs customers when the IDTech framework has determined the card is unsupported.
UNABLE TO GO ONLINE, FAILED TO SEND DECLINED RECEIPT	This message informs customers when the framework has failed to connect the servers to send an email to the customer. The email request process is separate from the payment process and can also fail due to slow or no internet connection.

Message	Description
Contactless not supported. Insert card with chip first, then start transaction	This message informs customers when the the framework has identified that the contactless interface has been disabled. It also instructs customers to insert the card with the chip side into the card reader to start the transaction.
TAP FAILED	This message instructs customers to insert or swipe the card again if contactless interaction fails and informs customers that they cannot use the contactless feature for a new transaction.
CARD BLOCKED	This message informs customers when the the framework cannot read the card data for some unknown reason when they use the contactless interface feature during the payment process.
CARD EXPIRED	This message informs customers when the the framework cannot read the card data for some unknown reason when they use the contactless interface feature during the payment process.

Field name	Sample value
Federal Tax ID	99-9000004
Routing Number (ABA)	083000137
Checking Account number	123542352343

Welcome to the Xplor Pay Documentation Center

Build powerful, seamless integrations with confidence.