{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","tabs","tab","code-group","admonition"]},"type":"markdown"},"seo":{"title":"How it works","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-it-works","__idx":0},"children":["How it works"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn about how card components work on iOS."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-steps","__idx":1},"children":["Integration steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A full integration involves the following steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Install the SDK:"]}," Add PXPCheckoutSDK to your Xcode project using Swift Package Manager."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initialise checkout:"]}," Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig"]}," with your session data, transaction details, and merchant identifiers, then call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PxpCheckout.initialize(config:)"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create and configure components:"]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpCheckout.create(_:componentConfig:)"]}," to create the components you need. Configure each component with labels, validation rules, and callbacks."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Embed components:"]}," Add the components to your SwiftUI views by calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["component.buildContent()"]}," in your view hierarchy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle results:"]}," Implement callbacks like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostAuthorisation"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," to handle payment outcomes. Add analytics tracking to monitor your customers' payment journeys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Submit and view transactions:"]}," Call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submitAsync()"]}," method on your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"After PXP processes the payment, the SDK receives the response and triggers an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"component-types","__idx":2},"children":["Component types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two types of card components:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pre-built components:"]}," For convenience and speed. They offer ready-to-use user interfaces, pre-designed and responsive layouts, and a consistent experience."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standalone components:"]}," For maximum flexibility and control. They offer individual field control, custom layouts, and fine-grained validation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-cases","__idx":3},"children":["Use cases"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use pre-built components if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want a complete payment form with minimal setup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're happy with pre-designed, responsive payment forms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to get up and running quickly, with minimal custom styling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want a proven user interface that follows payment best practices."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use standalone components if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to position and style each payment field (card number, expiry, CVC, etc.) separately in your own custom user interface."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're building a completely custom payment form layout that doesn't fit standard patterns."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need to handle validation for each field independently."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're integrating with existing forms or complex UI frameworks."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"available-components","__idx":4},"children":["Available components"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Pre-built components","disable":false},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Component"},"children":["Component"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Billing address"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a customer's billing address to use for AVS checks during authorisation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card-on-file"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Allow customers to select previously tokenised cards for quick and easy payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Click-once"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Allow customers to pay with just one click, using a tokenised card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["New card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Securely capture full card details for first-time users."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Standalone components","disable":false},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Component"},"children":["Component"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Address"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect the first line of a customer's billing address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card brand selector"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Display all accepted card brands and highlight the card brand as the user types their card details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card CVC"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a card's CVC."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card consent"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a customer's consent. For example, to save their card for reuse."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card expiry date"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a card's expiry date."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Cardholder name"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a cardholder's name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a card's number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card submit"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Display a submit button to finalise the payment process."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Country selection"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Allow customers to select their billing country using a customisable drop-down."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Dynamic card image"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Display a live preview of a customer's card with dynamically updated information."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Postcode"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Collect a customer's postal or ZIP code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Pre-fill billing address checkbox"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Allow customers to pre-fill their billing address using their shipping address details."]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"swift-examples","__idx":5},"children":["Swift examples"]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","data-title":"Pre-built (new card)","header":{"title":"Pre-built (new card)","controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\n// Create checkout config with session and transaction data\nlet pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)\n\n// Configure submit callbacks\nvar submitConfig = CardSubmitComponentConfig()\nsubmitConfig.onPreAuthorisation = { _ async in TransactionInitiationData() }\nsubmitConfig.onPostAuthorisation = { _ in /* handle success / decline */ }\nsubmitConfig.onSubmitError = { _ in /* handle errors */ }\n\n// Create new card component\nlet newCardConfig = NewCardComponentConfig(submit: submitConfig)\nlet newCard = try pxpCheckout.create(.newCard, componentConfig: newCardConfig) as! NewCardComponent\n\n// In SwiftUI:\n// newCard.buildContent()\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","data-title":"Standalone fields","header":{"title":"Standalone fields","controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\nlet pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)\n\n// Create individual field components\nlet cardNumber = try pxpCheckout.create(\n    .cardNumber,\n    componentConfig: CardNumberComponentConfig(label: \"Card number\")\n) as! CardNumberComponent\n\nlet expiry = try pxpCheckout.create(\n    .cardExpiryDate,\n    componentConfig: CardExpiryDateComponentConfig(label: \"Expiry\")\n) as! CardExpiryDateComponent\n\nlet cvc = try pxpCheckout.create(\n    .cardCvc,\n    componentConfig: CardCvcComponentConfig(label: \"CVC\", isRequired: true)\n) as! CardCvcComponent\n\n// Create submit component and link fields\nvar submitConfig = CardSubmitComponentConfig()\nsubmitConfig.cardNumberComponent = cardNumber\nsubmitConfig.cardExpiryDateComponent = expiry\nsubmitConfig.cardCvcComponent = cvc\nsubmitConfig.onPreAuthorisation = { _ async in TransactionInitiationData() }\nsubmitConfig.onPostAuthorisation = { _ in /* handle success / decline */ }\nsubmitConfig.onSubmitError = { _ in /* handle errors */ }\n\nlet cardSubmit = try pxpCheckout.create(.cardSubmit, componentConfig: submitConfig) as! CardSubmitComponent\n\n// In SwiftUI, compose your own layout:\n// VStack {\n//   cardNumber.buildContent()\n//   HStack { expiry.buildContent(); cvc.buildContent() }\n//   cardSubmit.buildContent()\n// }\n","lang":"swift"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-transaction-intents","__idx":6},"children":["Supported transaction intents"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you initiate a transaction, you have to provide key information about the transaction method, as well as the amount and currency."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transaction method is made up of three elements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entry type"]},", which describes the origin of the transaction and determines the supported payment methods and available features. For components, this is always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ecom"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["funding type"]},", which describes the method used to fund the transaction. In this case, card."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For card transactions, we support the following intents:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Intent"},"children":["Intent"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".authorisation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Reserve funds on the customer's payment method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".estimatedAuthorisation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Reserve funds on the customer's payment method, based on an estimated amount. This method is particularly useful in environments such as hotels, car rental agencies, and fuel stations, where the final charge may vary based on additional services or usage."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".purchase"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Capture funds immediately after authorisation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".payout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Send funds to a recipient."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".verification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Verify that a card is legitimate and active, without reserving any funds or completing a purchase. This method is particularly useful in environments such as hotels, car rental agencies, and other scenarios where it's important to validate the card upfront, but the final transaction amount may not be known or processed immediately."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We support recurring payments for subscription-based services where payments are automatically made on a regular schedule (e.g. monthly memberships, subscription services)."]}]}]},"headings":[{"value":"How it works","id":"how-it-works","depth":1},{"value":"Integration steps","id":"integration-steps","depth":2},{"value":"Component types","id":"component-types","depth":2},{"value":"Use cases","id":"use-cases","depth":3},{"value":"Available components","id":"available-components","depth":2},{"value":"Swift examples","id":"swift-examples","depth":2},{"value":"Supported transaction intents","id":"supported-transaction-intents","depth":2}],"frontmatter":{"seo":{"title":"How it works"}},"lastModified":"2026-05-18T12:26:24.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/ios/card/how-it-works","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}