How it works

Card components allow you to easily integrate a highly secure and customisable payment solution into your iOS app. By offering full control over layout, styling, and field visibility, card components ensure a seamless and branded payment experience, while maintaining top-tier security with PXP's Token Vault service and 3DS service.

The iOS SDK is built for SwiftUI and uses Swift's modern async/await patterns. You configure your checkout once, create the components you need, and render them in your view hierarchy using buildContent().

A full integration involves the following steps:

1. Set up the Unity Portal: To use the SDK, you first need to activate the Components and Card services in the Unity Portal. You also need to whitelist any iOS bundle identifiers that you'll be sending requests from.
2. Install the SDK: Add PXPCheckoutSDK to your Xcode project using Swift Package Manager.
3. Initialise checkout: Create a CheckoutConfig with your session data, transaction details, and merchant identifiers, then call PxpCheckout.initialize(config:).
4. Create and configure components: Use pxpCheckout.create(_:componentConfig:) to create the components you need. Configure each component with labels, validation rules, and callbacks.
5. Embed components: Add the components to your SwiftUI views by calling component.buildContent() in your view hierarchy.
6. Handle results: Implement callbacks like onPostAuthorisation and onSubmitError to handle payment outcomes. Add analytics tracking to monitor your customers' payment journeys.
7. Submit and view transactions: Call the submitAsync() method on your CardSubmitComponent instance. The SDK then validates all form data, tokenises the card (if needed), runs 3DS authentication when required, and sends the transaction request to PXP.
   After PXP processes the payment, the SDK receives the response and triggers an onPostAuthorisation callback that receives a result object containing the transaction identifiers and state. You can use these identifiers to retrieve the full transaction details from your backend via Unity APIs.

There are two types of card components:

• Pre-built components: For convenience and speed. They offer ready-to-use user interfaces, pre-designed and responsive layouts, and a consistent experience.
• Standalone components: For maximum flexibility and control. They offer individual field control, custom layouts, and fine-grained validation.

You can think of pre-built components as containers that manage multiple standalone components internally, while standalone components are individual building blocks you assemble yourself.

Use pre-built components if:

• You want a complete payment form with minimal setup.
• You're happy with pre-designed, responsive payment forms.
• You want to get up and running quickly, with minimal custom styling.
• You want a proven user interface that follows payment best practices.

Use standalone components if:

• You want to position and style each payment field (card number, expiry, CVC, etc.) separately in your own custom user interface.
• You're building a completely custom payment form layout that doesn't fit standard patterns.
• You need to handle validation for each field independently.
• You're integrating with existing forms or complex UI frameworks.

import SwiftUI
import PXPCheckoutSDK

// Create checkout config with session and transaction data
let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

// Configure submit callbacks
var submitConfig = CardSubmitComponentConfig()
submitConfig.onPreAuthorisation = { _ async in TransactionInitiationData() }
submitConfig.onPostAuthorisation = { _ in /* handle success / decline */ }
submitConfig.onSubmitError = { _ in /* handle errors */ }

// Create new card component
let newCardConfig = NewCardComponentConfig(submit: submitConfig)
let newCard = try pxpCheckout.create(.newCard, componentConfig: newCardConfig) as! NewCardComponent

// In SwiftUI:
// newCard.buildContent()

When you initiate a transaction, you have to provide key information about the transaction method, as well as the amount and currency.

The transaction method is made up of three elements:

• The entry type, which describes the origin of the transaction and determines the supported payment methods and available features. For components, this is always ecom.
• The funding type, which describes the method used to fund the transaction. In this case, card.
• The intent, which describes the purpose of a transaction, indicating the intended money flow direction. Each intent dictates a specific transaction flow and affects how the transaction is handled by the system.

For card transactions, we support the following intents: