> For the complete documentation index, see [llms.txt](https://docs.xplorpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplorpay.com/quick-starts/payment-ui.md).

# Payment UI

Integrate the **Payment UI** wrapper to add a built-in interface for accepting card payments using the VP3300 reader.

### **Prerequisites** <a href="#prerequisites" id="prerequisites"></a>

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 <project-root-path>
```

{% 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: "<YOUR_BASE_URL>",
        apiKey: "<YOUR_API_KEY>",
        publicKey: "<YOUR_PUBLIC_KEY>",
        softwareType: "<YOUR_APP_NAME>",
        softwareTypeVersion: "<YOUR_APP_VERSION>"
    )
)
```

{% endcode %}

#### Configuration values

Use the following values when configuring the SDK:

<table><thead><tr><th width="199.666748046875" valign="top">Field name</th><th width="117.666748046875" valign="top">Data type</th><th width="118.6666259765625" valign="top">Required?</th><th>Description</th></tr></thead><tbody><tr><td valign="top"><code>baseURL</code></td><td valign="top">String</td><td valign="top">Required</td><td><p>The API endpoint for the selected environment. </p><p>Use the sandbox URL (<code>https://gateway-int.clearent.net)</code> for testing.</p><p>Use the production URL (<code>https://gateway.clearent.net)</code> for live transactions.</p></td></tr><tr><td valign="top"><code>apiKey</code></td><td valign="top">String</td><td valign="top">Required</td><td>The API key associated with your account and environment. Provided to you during onboarding with Xplor Pay.</td></tr><tr><td valign="top"><code>publicKey</code></td><td valign="top">String</td><td valign="top">Required</td><td>The public key associated with your account and environment. Provided to you during onboarding with Xplor Pay.</td></tr><tr><td valign="top"><code>softwareType</code></td><td valign="top">String</td><td valign="top">Required</td><td>The name of your application used for support purposes. Maximum length is 255 characters.</td></tr><tr><td valign="top"><code>softwareTypeVersion</code></td><td valign="top">String</td><td valign="top">Required</td><td>The version of your application used for support purposes. Maximum length is 255 characters.</td></tr></tbody></table>

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: "<YOUR_CUSTOMER_ID>",
    invoice: "<YOUR_INVOICE_NUMBER>",
    orderID: "<YOUR_ORDER_ID>",
    billing: ClearentIdtechIOSFramework.ClientInformation,
    shipping: ClearentIdtechIOSFramework.ClientInformation,
    softwareType: "<YOUR_APP_NAME>"
)
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xplorpay.com/quick-starts/payment-ui.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.