{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","admonition","br","details","required"]},"type":"markdown"},"seo":{"title":"Implementation","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":"implementation","__idx":0},"children":["Implementation"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete guide to integrating Checkout Drop-in into your iOS application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Drop-in provides a complete, pre-built payment interface that automatically handles multiple payment methods — cards, PayPal, Apple Pay, and Paze (when enabled in your session)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It follows a simple three-step lifecycle:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initialise:"]}," Configure Drop-in with your session and transaction data (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropIn(config:)"]}," validates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create:"]}," Await ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," to fetch site configuration, resolve the shopper via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},", and prepare payment components."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Render:"]}," Display the UI using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," within a SwiftUI view."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in automatically detects available payment methods, applies server-driven branding, and signs PXP API requests using your session's HMAC key."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Backend verification is mandatory. Always verify payments on your backend before fulfilling orders. Frontend callbacks can be manipulated by malicious users."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":2},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you've activated the Checkout Drop-in service in the Unity Portal. Contact your account manager if you need access."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-add-the-sdk-dependency","__idx":3},"children":["Step 1: Add the SDK dependency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the iOS SDK to your project using Swift Package Manager."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In Xcode, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["File > Add Package Dependencies"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the package URL: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://github.com/PXP-IO/ios-components-sdk"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the latest version and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add Package"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, add it to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Package.swift"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"dependencies: [\n    .package(url: \"https://github.com/PXP-IO/ios-components-sdk\", from: \"1.0.0\")\n]\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-get-your-api-credentials","__idx":4},"children":["Step 2: Get your API credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order to initialise Checkout Drop-in, you'll need to send authenticated requests to the PXP API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get your credentials:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},", go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Merchant groups"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select a merchant group."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inbound calls"]}," tab."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Client ID"]}," in the top-right corner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New token"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Choose a number of days before token expiry. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]}," to confirm. Your token is now created."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the token ID and token value. Make sure to keep these confidential to protect the integrity of your authentication process."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As best practice, we recommend regularly generating and implementing new tokens."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-create-a-session-on-your-backend","__idx":5},"children":["Step 3: Create a session on your backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Drop-in requires a session from the PXP Sessions API. This must be done on your backend using HMAC authentication to keep your credentials secure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"understanding-hmac-authentication","__idx":6},"children":["Understanding HMAC authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our platform uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity. This method involves creating a signature by hashing your request data with a secret key, which must then be included in the HTTP headers of your API request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-an-hmac-signature","__idx":7},"children":["Create an HMAC signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create the HMAC signature, you need to prepare a string that includes five parts separated by colons:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token ID:"]}," your API token identifier (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["9aac6071-38d0-4545-9d2f-15b936af6d7f"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Timestamp:"]}," the current time in ",{"$$mdtype":"Tag","name":"a","attributes":{"target":"_blank","href":"https://en.wikipedia.org/wiki/Unix_time"},"children":["Unix milliseconds"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1754701373845"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request ID:"]}," a unique UUID for this request (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ce244054-b372-42c2-9102-f0d976db69f6"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request path:"]}," the API endpoint path: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v1/sessions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}," the complete JSON request body as a minified string"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example request body to minify:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"merchant\": \"MERCHANT-1\",\n  \"site\": \"SITE-1\",\n  \"sessionTimeout\": 120,\n  \"merchantTransactionId\": \"0ce72cfd-014d-4256-a006-a56601b2ffc4\",\n  \"transactionMethod\": {\n    \"intent\": {\n      \"card\": \"Authorisation\",\n      \"paypal\": \"Purchase\"\n    }\n  },\n  \"amounts\": {\n    \"currencyCode\": \"USD\",\n    \"transactionValue\": 25.00\n  },\n  \"allowTransaction\": true,\n  \"serviceType\": \"CheckoutDropIn\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating the HMAC signature, the request body must be minified (no whitespace or formatting). The formatted JSON above is for readability only."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-request-parameters","__idx":8},"children":["Session request parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The session request accepts the following parameters:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 20 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your unique merchant identifier, as assigned by PXP. You can find it in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},", by going to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Merchants"]}," and checking the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Merchant ID"]}," column."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["site"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 20 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your unique site identifier, as assigned by PXP. You can find it in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},", by going to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Sites"]}," and checking the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Site ID"]}," column."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 50 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique identifier of your choice that represents this transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTimeout"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The duration of the session, in minutes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Details about the transaction method, including the intent for each payment type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction intent for each payment method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.card"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The intent for card and Apple Pay transactions.",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorisation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Purchase"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Verification"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EstimatedAuthorisation"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.paypal"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The intent for PayPal transactions.",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorisation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Purchase"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Details about the transaction amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.currencyCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (3 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The currency code associated with the transaction, in ISO 4217 format. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/how-it-works#supported-payment-currencies"},"children":["Supported payment currencies"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.transactionValue"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currencyCode"]}," exponent. For example, GBP 1.1 = GBP 1.10, USD 1 = USD 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currencyCode"]}," exponent (e.g., GBP 1.234), or if a decimal is supplied when the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currencyCode"]}," of the exponent does not require it (e.g., JPY 1.0)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowTransaction"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether or not to proceed with the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceType"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The service type. This must be set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CheckoutDropIn\""]}," for Drop-in integrations."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-response","__idx":9},"children":["Session response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your request is successful, you'll receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," response containing the session data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sessionId\": \"c5f0799b-0839-43ce-abc5-5b462a98f250\",\n  \"hmacKey\": \"904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb\",\n  \"encryptionKey\": \"20d175a669ad3f8c195c9c283fc86155\",\n  \"sessionExpiry\": \"2025-05-19T13:39:20.3843454Z\",\n  \"allowedFundingTypes\": {\n    \"cardSchemes\": [\n      \"Visa\",\n      \"Diners\",\n      \"Mastercard\",\n      \"AmericanExpress\"\n    ],\n    \"cards\": [],\n    \"wallets\": {\n      \"paypal\": {\n        \"allowedFundingOptions\": [\n          \"paylater\", \n          \"paypal\"\n        ],\n        \"merchantId\": \"paypal-merchant-123\"\n      },\n      \"applePay\": {\n        \"merchantId\": \"merchant.com.example.store\",\n        \"merchantName\": \"Your Store Name\"\n      }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Drop-in automatically detects available payment methods from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]}," in your session data. You don't need to manually configure which payment methods to show."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-initialise-drop-in-in-your-app","__idx":10},"children":["Step 4: Initialise Drop-in in your app"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import the necessary types and initialise Drop-in with your configuration."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\n@MainActor\nfinal class CheckoutViewModel: ObservableObject {\n    @Published var dropIn: CheckoutDropIn?\n    @Published var errorMessage: String?\n    \n    func loadDropIn() async {\n        do {\n            // Fetch session data from your backend\n            let session = try await fetchSessionFromBackend()\n            \n            // Build transaction data\n            let transactionData = DropInTransactionData(\n                amount: Decimal(string: \"49.99\") ?? 0,\n                currency: \"USD\",\n                entryType: .ecom,\n                intent: DropInTransactionIntentData(\n                    card: .authorisation,\n                    paypal: .authorisation\n                ),\n                merchantTransactionId: UUID().uuidString,\n                merchantTransactionDate: { Date() }\n            )\n            \n            // Create Drop-in configuration\n            let config = CheckoutDropInConfig(\n                environment: .test,\n                session: session,\n                transactionData: transactionData,\n                merchantShopperId: \"shopper-123\",\n                ownerId: \"merchant-group-id\",\n                kountDisabled: false,\n                onGetShopper: { async in\n                    TransactionShopper(id: \"shopper-123\")\n                },\n                onBeforeSubmit: { paymentMethod in\n                    // Validate your checkout state\n                    return true\n                },\n                onSubmit: { paymentMethod in\n                    print(\"Payment started: \\(paymentMethod.rawValue)\")\n                },\n                onSuccess: { result in\n                    // CRITICAL: Verify on backend before fulfilling order\n                    print(\"Payment successful: \\(result.systemTransactionId)\")\n                },\n                onError: { paymentMethod, error in\n                    print(\"Payment failed: \\(error.errorMessage)\")\n                }\n            )\n            \n            // Initialise and create Drop-in\n            let instance = try CheckoutDropIn(config: config)\n            await instance.create()\n            dropIn = instance\n            \n        } catch {\n            errorMessage = error.localizedDescription\n        }\n    }\n    \n    private func fetchSessionFromBackend() async throws -> SessionData {\n        // Implement your backend API call here\n        let url = URL(string: \"https://your-backend.com/api/create-session\")!\n        let (data, _) = try await URLSession.shared.data(from: url)\n        \n        // Decode directly to SessionData to preserve all fields including sessionExpiry and restrictions\n        return try JSONDecoder().decode(SessionData.self, from: data)\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-parameters","__idx":11},"children":["Configuration parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInConfig"]}," struct accepts the following configuration parameters:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["Environment"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The environment type.",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".test"]},": For development and testing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".live"]},": For live transactions."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["SessionData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Details about the checkout session returned from the Unity Sessions API. Includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptionKey"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["DropInTransactionData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Details about the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantShopperId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your unique identifier for this shopper. Required at initialisation. Used for Card-on-File and other shopper-scoped flows."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownerId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String (≤ 20 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your unique merchant or merchant group identifier, as assigned by PXP. You can find it in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localisation"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["Localisation?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional custom labels and messages for the drop-in interface. Use this to override default text."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Locale for built-in SDK strings (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"en-US\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"es-ES\""]},"). When omitted, Drop-in defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"en-US\""]},". It does not automatically follow the device language. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/configuration#locale"},"children":["Configuration"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paypalConfig"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PayPalConfig?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional PayPal configuration used by SDK-level PayPal flows."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["restrictions"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["Restrictions?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional card restrictions supplied at SDK level. Can filter by card owner type (consumer/corporate) and funding source (credit/debit/prepaid)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kountDisabled"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["Bool?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to disable Kount fraud detection. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["DropInMethodConfig?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional payment-method-specific configuration for global, card, PayPal, and Apple Pay behaviour. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/configuration"},"children":["Configuration reference"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShippingAddress"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(() async -> ShippingAddress?)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Async function to supply shipping address when Drop-in needs it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(() async -> TransactionShopper?)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Async function to retrieve shopper information. Required for Card-on-File functionality. Returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionShopper"]}," object containing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analyticsEvent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["((BaseAnalyticsEvent) -> Void)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receives SDK analytics events so merchants can forward them to their analytics platform. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/analytics"},"children":["Analytics"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["((DropInPaymentMethod) async -> Bool)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Async validation function called before payment submission. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to proceed or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to block submission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["((DropInPaymentMethod) -> Void)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when payment processing starts for card and Apple Pay. Not called for PayPal — show loading after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," or when Drop-in enters processing during PayPal order creation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["((DropInSubmitResult) -> Void)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when payment succeeds. Strongly recommended in production. Always verify the payment on your backend using the provided transaction identifiers before fulfilling the order."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["((DropInPaymentMethod?, BaseSdkException) -> Void)?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when initialisation or payment fails. Strongly recommended in production. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," parameter can be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]}," for initialisation or configuration errors that occur before a payment method is selected. Handle errors appropriately and show user-friendly messages."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-data-parameters","__idx":12},"children":["Transaction data parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DropInTransactionData"]}," struct describes the payment transaction:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["Decimal"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The three-letter currency code in ISO 4217 format (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"USD\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"GBP\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"EUR\""]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entryType"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["EntryType"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction entry type.",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".ecom"]},": E-commerce transaction (required for PayPal)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".moto"]},": Mail order / telephone order"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["DropInTransactionIntentData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction intent for each payment method. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DropInTransactionIntentData"]},", not the generic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionIntentData"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique identifier for this transaction. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UUID().uuidString"]}," to generate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionDate"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["() -> Date"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A closure that returns the current date. Typically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ Date() }"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardAcceptorName"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional card acceptor name when required by your flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["RecurringType?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional recurring payment data for subscription or installment use cases."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linkId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional link ID when linking transactions together."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-render-the-drop-in-ui","__idx":13},"children":["Step 5: Render the drop-in UI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the drop-in interface within a SwiftUI view:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import SwiftUI\nimport PXPCheckoutSDK\n\nstruct CheckoutView: View {\n    @StateObject private var viewModel = CheckoutViewModel()\n    \n    var body: some View {\n        Group {\n            if let dropIn = viewModel.dropIn {\n                dropIn.buildContent()\n            } else if let error = viewModel.errorMessage {\n                VStack(spacing: 16) {\n                    Text(\"Unable to load checkout\")\n                        .font(.headline)\n                    Text(error)\n                        .font(.body)\n                        .foregroundColor(.secondary)\n                    Button(\"Retry\") {\n                        Task {\n                            await viewModel.loadDropIn()\n                        }\n                    }\n                }\n                .padding()\n            } else {\n                ProgressView(\"Loading checkout...\")\n            }\n        }\n        .task {\n            await viewModel.loadDropIn()\n        }\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," method returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AnyView"]}," containing the Drop-in UI. Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["await create()"]}," before rendering — if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," has not completed, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," returns an empty view. The SDK handles payment method selection and branding inside the hosted component."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-handle-payment-callbacks","__idx":14},"children":["Step 6: Handle payment callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in provides four key callbacks to manage the payment flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onbeforesubmit","__idx":15},"children":["onBeforeSubmit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Called before payment processing starts. Use this to validate your checkout state."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onBeforeSubmit: { paymentMethod in\n    // Validate terms accepted, shipping address, etc.\n    guard hasAcceptedTerms else {\n        showError(\"Please accept terms and conditions\")\n        return false\n    }\n    return true\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsubmit","__idx":16},"children":["onSubmit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Called when payment processing starts for card and Apple Pay. PayPal doesn't invoke ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},". Show loading after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," or when Drop-in enters processing during PayPal order creation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onSubmit: { paymentMethod in\n    showLoadingIndicator()\n    print(\"Processing \\(paymentMethod.rawValue) payment...\")\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsuccess","__idx":17},"children":["onSuccess"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Called when payment succeeds. Always verify on your backend:"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Drop-in, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result.paymentData"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]}," for card, PayPal, and Apple Pay."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onSuccess: { result in\n    // result is DropInSubmitResult\n    let systemTransactionId = result.systemTransactionId\n    let merchantTransactionId = result.merchantTransactionId\n    // Verify these identifiers on your backend.\n    // paymentData is nil except for Paze (.paze(PazeCheckoutDecoded) when present)\n    \n    hideLoadingIndicator()\n    \n    // Send to backend for verification\n    Task {\n        do {\n            try await verifyPaymentOnBackend(\n                systemTransactionId: systemTransactionId,\n                merchantTransactionId: merchantTransactionId\n            )\n            showSuccessScreen()\n        } catch {\n            showError(\"Payment verification failed\")\n        }\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onerror","__idx":18},"children":["onError"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Called when initialisation or payment fails:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onError: { paymentMethod, error in\n    // paymentMethod is DropInPaymentMethod?\n    // error is BaseSdkException\n    let method = paymentMethod?.rawValue ?? \"unknown\"\n    let code = error.errorCode\n    let message = error.errorMessage\n    \n    hideLoadingIndicator()\n    \n    switch code {\n    case \"CARD_DECLINED\":\n        showError(\"Your card was declined. Please try another payment method.\")\n    case \"INSUFFICIENT_FUNDS\":\n        showError(\"Insufficient funds. Please use a different card.\")\n    case \"SDK1122\":\n        showError(\"Paze is unavailable. Please choose another payment method.\")\n    case \"SDK1123\":\n        showError(\"Paze payment failed. Please try again.\")\n    case \"SDK1124\":\n        showError(\"Paze is only available for e-commerce checkout.\")\n    case \"SDK0118\":\n        showError(\"Paze client ID is missing from the session.\")\n    case \"SDK1202A\":\n        showError(\"Paze merchant category code is missing from the session.\")\n    case \"SDK1203\", \"SDK1204\", \"SDK1205\":\n        showError(\"Paze merchant display configuration is too long.\")\n    case \"SDK1209\", \"SDK1210\", \"SDK1211\", \"SDK1212\":\n        showError(\"Invalid shopper details for Paze.\")\n    case \"SDK1213\":\n        showError(\"Paze only supports USD transactions.\")\n    default:\n        showError(\"Payment failed. Please try again.\")\n    }\n    \n    // Log for debugging\n    print(\"Error for \\(method): \\(message)\")\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-timeline","__idx":19},"children":["Callback timeline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback sequence varies by payment method:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card","__idx":20},"children":["Card"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit(.card)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit(.card)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["AVS session update (if required)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["3DS authentication (if required)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authorization evaluation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess(...)"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError(.card, ...)"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apple-pay","__idx":21},"children":["Apple Pay"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit(.applePay)"]}," — when the customer taps the Apple Pay button, before the payment sheet opens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer authorises in the Apple Pay sheet"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit(.applePay)"]}," — when pre-authorisation starts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session update with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowTransaction: true"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess(...)"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError(.applePay, ...)"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal","__idx":22},"children":["PayPal"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit(.paypal)"]}," — when the customer taps the PayPal button"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Drop-in enters processing and creates the PayPal order (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Buyer approval on PayPal.com"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess(...)"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError(.paypal, ...)"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal does not invoke ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," fires after the customer approves on PayPal.com, not when the button is first tapped. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/events#onsubmit"},"children":["Events"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cleanup","__idx":23},"children":["Cleanup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destroy()"]}," to explicitly release the hosted drop-in UI when you're done:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"dropIn.destroy()\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK automatically cleans up when the drop-in instance is deallocated, so calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destroy()"]}," is optional in most cases."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-recommendations","__idx":24},"children":["Security recommendations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create checkout sessions on your backend only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Never log HMAC keys, raw payment payloads, or full wallet/token payloads."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the payment result server-side before shipment or fulfilment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use HTTPS for all backend traffic."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat transaction identifiers as references, not as final proof of settlement."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":25},"children":["What's next?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/configuration"},"children":["Configuration reference"]},":"]}," explore all configuration options in detail."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/cards"},"children":["Payment methods"]},":"]}," configure cards, PayPal, and Apple Pay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/events"},"children":["Events and callbacks"]},":"]}," learn about all available callbacks."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/error-handling"},"children":["Error handling"]},":"]}," implement robust error handling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/testing"},"children":["Testing"]},":"]}," test your integration with test cards and credentials."]}]}]},"headings":[{"value":"Implementation","id":"implementation","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Add the SDK dependency","id":"step-1-add-the-sdk-dependency","depth":2},{"value":"Step 2: Get your API credentials","id":"step-2-get-your-api-credentials","depth":2},{"value":"Step 3: Create a session on your backend","id":"step-3-create-a-session-on-your-backend","depth":2},{"value":"Understanding HMAC authentication","id":"understanding-hmac-authentication","depth":3},{"value":"Create an HMAC signature","id":"create-an-hmac-signature","depth":3},{"value":"Session request parameters","id":"session-request-parameters","depth":3},{"value":"Session response","id":"session-response","depth":3},{"value":"Step 4: Initialise Drop-in in your app","id":"step-4-initialise-drop-in-in-your-app","depth":2},{"value":"Configuration parameters","id":"configuration-parameters","depth":3},{"value":"Transaction data parameters","id":"transaction-data-parameters","depth":3},{"value":"Step 5: Render the drop-in UI","id":"step-5-render-the-drop-in-ui","depth":2},{"value":"Step 6: Handle payment callbacks","id":"step-6-handle-payment-callbacks","depth":2},{"value":"onBeforeSubmit","id":"onbeforesubmit","depth":3},{"value":"onSubmit","id":"onsubmit","depth":3},{"value":"onSuccess","id":"onsuccess","depth":3},{"value":"onError","id":"onerror","depth":3},{"value":"Callback timeline","id":"callback-timeline","depth":2},{"value":"Card","id":"card","depth":3},{"value":"Apple Pay","id":"apple-pay","depth":3},{"value":"PayPal","id":"paypal","depth":3},{"value":"Cleanup","id":"cleanup","depth":2},{"value":"Security recommendations","id":"security-recommendations","depth":2},{"value":"What's next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Implementation"}},"lastModified":"2026-07-14T09:12:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/ios/implementation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}