{"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 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. 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":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mount"]},": Render the payment interface to your page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle callbacks"]},": Respond to payment success, errors, and other events."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in automatically detects available payment methods, renders the UI, and handles all payment flows."]},{"$$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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/activation"},"children":["activated the Checkout Drop-in service"]}," in the Unity Portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-install-the-web-sdk-library","__idx":3},"children":["Step 1: Install the Web SDK library"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the latest version of the Web SDK from the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.npmjs.com/package/@pxpio/web-components-sdk","target":"_blank"},"children":["npm public registry"]},". You'll need to have Node.js 22.x or higher."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"npm i @pxpio/web-components-sdk\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Drop-in is part of the main SDK package. Import it directly from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn"]},"."]}]},{"$$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":["1754701373"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request ID"]},": A unique GUID 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, Apple Pay, or Google 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-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":"Heading","attributes":{"level":3,"id":"prepare-and-send-your-request","__idx":9},"children":["Prepare and send your request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The HMAC signature requires combining your token ID, timestamp, request ID, request path, and request body. Here's the format:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["String to hash"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{tokenId}:{timestamp}:{requestId}:{requestPath}:{requestBody}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:ce244054-b372-42c2-9102-f0d976db69f6:api/v1/sessions:{\"merchant\":\"MERCHANT-1\",\"site\":\"SITE-1\",\"sessionTimeout\":120,\"merchantTransactionId\":\"0ce72cfd-014d-4256-a006-a56601b2ffc4\",\"transactionMethod\":{\"intent\":{\"card\":\"Authorisation\",\"paypal\":\"Purchase\"}},\"amounts\":{\"currencyCode\":\"USD\",\"transactionValue\":25.00},\"allowTransaction\":true,\"serviceType\":\"CheckoutDropIn\"}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["token value"]}," (not token ID) as the secret key to create an HMAC SHA256 hash of this string. The result will be a base64-encoded signature like:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can now put together your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header. It follows this format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{tokenId}:{timestamp}:{requestId}:{signature}"]},". For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:ce244054-b372-42c2-9102-f0d976db69f6:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lastly, send your request to the Sessions API. You'll need to add a request ID of your choice and include your client ID, which you can find in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a full example of what your request might look like:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n 'https://api-services.pxp.io/api/v1/sessions' \\\n -H 'Authorization: 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:ce244054-b372-42c2-9102-f0d976db69f6:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6' \\\n -H 'X-Request-Id: ce244054-b372-42c2-9102-f0d976db69f6' \\\n -H 'X-Client-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \\\n -H 'Content-Type: application/json' \\\n -d '{\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":"curl"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-response","__idx":10},"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 \"venmo\", \n \"paylater\", \n \"paypal\"\n ],\n \"merchantId\": \"paypal-merchant-123\"\n },\n \"googlePay\": {\n \"merchantId\": \"BCR2DN4TWWPKJ45P\",\n \"merchantName\": \"Your Store Name\",\n \"gatewayMerchantId\": \"gateway-merchant-id\"\n },\n \"applePay\": {\n \"merchantId\": \"merchant.com.yourstore\"\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-on-your-frontend","__idx":11},"children":["Step 4: Initialise Drop-in on your frontend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropIn"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IntentType"]}," from the SDK and initialise with your configuration."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import CheckoutDropIn from '@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn';\nimport IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\nimport PaymentMethod from '@pxpio/web-components-sdk/src/components/checkoutDropInComponents/types/PaymentMethod';\nimport { BaseSubmitResult } from '@pxpio/web-components-sdk/src/checkoutDropIn/types/BaseSubmitResult';\nimport BaseSdkException from '@pxpio/web-components-sdk/src/types/sdkExceptions/BaseSdkException';\n\n// Get session data from your backend\nconst sessionData = await fetch('/api/create-session', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' }\n}).then(response => response.json());\n\n// Initialise Checkout Drop-in\nconst checkoutDropIn = CheckoutDropIn.initialize({\n environment: 'test',\n session: sessionData,\n ownerId: 'MERCHANT-1',\n ownerType: 'MerchantGroup',\n transactionData: {\n currency: 'USD',\n amount: 25.00,\n entryType: 'Ecom',\n intent: {\n card: IntentType.Authorisation,\n paypal: IntentType.Authorisation\n },\n merchantTransactionId: crypto.randomUUID(),\n merchantTransactionDate: () => new Date().toISOString()\n },\n onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n onBeforeSubmit: async (paymentMethod: PaymentMethod) => {\n console.log('Payment method selected:', paymentMethod);\n return true; // Return true to proceed, false to cancel\n },\n onSubmit: (paymentMethod: PaymentMethod) => {\n console.log('Payment being processed:', paymentMethod);\n },\n onSuccess: async (result: BaseSubmitResult) => {\n // CRITICAL: Verify on backend before fulfilling order\n await verifyPaymentOnBackend(result);\n },\n onError: (error: BaseSdkException) => {\n console.error('Payment failed:', error);\n alert(`Payment failed: ${error.message}`);\n }\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-parameters","__idx":12},"children":["Configuration parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]}," method 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":["string"]},{"$$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":["production"]},": 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"]},", 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":["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":["ownerType"]},{"$$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":["Always set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'MerchantGroup'"]}," for Drop-in."]}]},{"$$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":["object"]},{"$$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":["transactionData.currency"]},{"$$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-currencies"},"children":["Supported payment currencies"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.amount"]},{"$$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. Must match the currency's expected decimal places."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.entryType"]},{"$$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 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 transactions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Moto"]},": Mail order/telephone order transactions."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.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 intents for each payment method. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/how-it-works#supported-transaction-intents"},"children":["supported transaction intents"]}," for details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.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, Google Pay, or 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":["EstimatedAuthorisation"]}]},{"$$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":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.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":["transactionData.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 for this transaction. Use a UUID or order ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.merchantTransactionDate"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A function that returns the current date and time in ISO 8601 format."]}]},{"$$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":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Function to retrieve shopper information. Required for Card-on-File functionality. Returns a Promise with shopper 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":["onBeforeSubmit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Callback fired when a payment method is selected and the user is about to submit payment. Receives payment method. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to proceed or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to cancel."]}]},{"$$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":["function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Callback fired when payment processing begins. Use this to show loading indicators."]}]},{"$$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":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Callback fired when payment succeeds."]}]},{"$$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":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Callback fired when payment fails. Receives error details including code and message."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-mount-drop-in-to-your-page","__idx":13},"children":["Step 5: Mount Drop-in to your page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a container element to your page where Drop-in will be rendered:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"
\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," method to render Drop-in:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"checkoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At this point, Drop-in will:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Detect available payment methods from your session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Render a vertical accordion with all available payment methods."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply branding from the Unity Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show a \"Secured by PXP\" branded footer."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-handle-callbacks","__idx":14},"children":["Step 6: Handle callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in requires three callbacks to handle payment lifecycle events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ongetshopper-callback","__idx":15},"children":["onGetShopper callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns shopper information for Card-on-File functionality."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onGetShopper: () => Promise.resolve({ id: 'shopper-123' })\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsuccess-callback","__idx":16},"children":["onSuccess callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when payment succeeds. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CRITICAL: Always verify on your backend before fulfilling orders."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onSuccess: async (result: BaseSubmitResult) => {\n // Verify payment on backend\n const verified = await fetch('/api/verify-payment', {\n method: 'POST',\n body: JSON.stringify({\n systemTransactionId: result.systemTransactionId,\n merchantTransactionId: result.merchantTransactionId\n })\n }).then(r => r.json());\n \n if (verified.success) {\n window.location.href = `/success?orderId=${verified.orderId}`;\n }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onerror-callback","__idx":17},"children":["onError callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when payment fails. Display appropriate error messages."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error: BaseSdkException) => {\n console.error('Payment failed:', error.code, error.message);\n alert(error.message || 'Payment failed. Please try again.');\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never trust frontend callbacks for order fulfillment. Always verify payments on your backend using webhooks or the Query Transaction API before fulfilling orders."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Want to add validation before payment or show loading states? See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/events"},"children":["Events guide"]}," for optional callbacks like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-7-backend-verification-critical","__idx":18},"children":["Step 7: Backend verification (CRITICAL)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Frontend callbacks can be manipulated by malicious users. You must verify all payments on your backend before fulfilling orders."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"primary-method-webhooks","__idx":19},"children":["Primary method: Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unity sends real-time webhook notifications to your backend when transactions complete:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Your webhook endpoint (configured in the Unity Portal)\napp.post('/webhooks/pxp', async (req, res) => {\n const events = req.body;\n \n // Verify webhook authenticity using HMAC\n if (!verifyWebhookSignature(req)) {\n return res.status(401).json({ error: 'Unauthorised' });\n }\n \n for (const event of events) {\n if (event.eventCategory === 'Transaction') {\n const txn = event.eventData;\n \n // Verify transaction details\n if (txn.state === 'Authorised' || txn.state === 'Captured') {\n // Check idempotency (prevent duplicate processing)\n if (!await hasProcessedTransaction(txn.systemTransactionId)) {\n // Verify amount and merchant transaction ID\n const transactionAmount = txn.amounts?.transactionValue || txn.amount;\n if (transactionAmount === expectedAmount &&\n txn.merchantTransactionId === expectedMerchantTxnId) {\n // Payment verified - fulfill order\n await fulfillOrder(txn.merchantTransactionId);\n await markTransactionProcessed(txn.systemTransactionId);\n }\n }\n }\n }\n }\n \n // Always return success response\n res.json({ state: 'Success' });\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"optional-fallback-query-the-transactions-api","__idx":20},"children":["Optional fallback: Query the Transactions API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need instant feedback before the webhook arrives, you can query PXP's Transactions API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Your verification endpoint\napp.post('/api/verify-payment', async (req, res) => {\n const { systemTransactionId, amount, merchantTransactionId } = req.body;\n \n // Check if webhook already processed this\n const existingTxn = await getTransactionFromDB(systemTransactionId);\n if (existingTxn) {\n return res.json({ success: true, orderId: existingTxn.orderId });\n }\n \n // Query PXP API as fallback (requires HMAC authentication)\n const response = await fetch(\n `https://api-services.pxp.io/api/v1/transactions?systemTransactionId=${systemTransactionId}&fundingType=Card`,\n {\n headers: {\n 'X-Client-Id': process.env.PXP_CLIENT_ID,\n 'X-Request-Id': crypto.randomUUID(),\n 'Authorization': createAuthHeader('/api/v1/transactions', '', process.env.PXP_TOKEN_ID, process.env.PXP_TOKEN_VALUE),\n 'Content-Type': 'application/json'\n }\n }\n );\n \n const transaction = await response.json();\n \n // Verify transaction details\n const transactionAmount = transaction.amounts?.transactionValue || transaction.amount;\n if (transaction.state === 'Authorised' &&\n Math.abs(transactionAmount - amount) < 0.01 &&\n transaction.merchantTransactionId === merchantTransactionId) {\n // Payment verified - fulfill order\n const order = await fulfillOrder(merchantTransactionId);\n return res.json({ success: true, orderId: order.id });\n }\n \n res.json({ success: false, error: 'Payment verification failed' });\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":21},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All errors return a consistent structure with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," properties. Common scenarios include card declined, insufficient funds, expired card, CVV failure, and 3DS authentication failure. Display the error message to users and allow them to retry or use a different payment method."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example","__idx":22},"children":["Complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a complete example showing Drop-in integration in a React component:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { useEffect, useState } from 'react';\nimport CheckoutDropIn from '@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn';\nimport IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\nimport PaymentMethod from '@pxpio/web-components-sdk/src/components/checkoutDropInComponents/types/PaymentMethod';\nimport { BaseSubmitResult } from '@pxpio/web-components-sdk/src/checkoutDropIn/types/BaseSubmitResult';\nimport BaseSdkException from '@pxpio/web-components-sdk/src/types/sdkExceptions/BaseSdkException';\n\nexport default function CheckoutPage() {\n const [isLoading, setIsLoading] = useState(false);\n const [error, setError] = useState(null);\n\n useEffect(() => {\n initializeCheckout();\n }, []);\n\n async function initializeCheckout() {\n try {\n // 1. Get session from backend\n const sessionData = await fetch('/api/create-session', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n merchant: \"MERCHANT-1\",\n site: \"SITE-1\",\n sessionTimeout: 120,\n merchantTransactionId: crypto.randomUUID(),\n transactionMethod: {\n intent: {\n card: \"Authorisation\",\n paypal: \"Authorisation\"\n }\n },\n amounts: {\n currencyCode: \"USD\",\n transactionValue: 25.00\n },\n allowTransaction: true,\n serviceType: \"CheckoutDropIn\"\n })\n }).then(r => r.json());\n\n // 2. Initialise Drop-in\n const checkoutDropIn = CheckoutDropIn.initialize({\n environment: 'production',\n session: sessionData,\n ownerId: 'MERCHANT-1',\n ownerType: 'MerchantGroup',\n transactionData: {\n currency: 'USD',\n amount: 25.00,\n entryType: 'Ecom',\n intent: {\n card: IntentType.Authorisation,\n paypal: IntentType.Authorisation\n },\n merchantTransactionId: crypto.randomUUID(),\n merchantTransactionDate: () => new Date().toISOString()\n },\n onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n onBeforeSubmit: async (paymentMethod: PaymentMethod) => {\n console.log('Payment method selected:', paymentMethod);\n setError(null);\n return true;\n },\n onSubmit: (paymentMethod: PaymentMethod) => {\n console.log('Processing payment...');\n setIsLoading(true);\n },\n onSuccess: async (result: BaseSubmitResult) => {\n console.log('Payment successful:', result.systemTransactionId);\n \n // Verify on backend\n try {\n const verified = await fetch('/api/verify-payment', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n systemTransactionId: result.systemTransactionId,\n merchantTransactionId: result.merchantTransactionId\n })\n }).then(r => r.json());\n \n if (verified.success) {\n window.location.href = `/success?orderId=${verified.orderId}`;\n } else {\n setError('Payment verification failed. Please contact support.');\n setIsLoading(false);\n }\n } catch (err) {\n setError('Failed to verify payment. Please contact support.');\n setIsLoading(false);\n }\n },\n onError: (error: BaseSdkException) => {\n console.error('Payment failed:', error);\n \n // Handle errors based on message content\n let userMessage = error.message || 'Payment failed. Please try again.';\n \n if (error.message.includes('declined')) {\n userMessage = 'Your card was declined. Please try a different card.';\n } else if (error.message.includes('insufficient')) {\n userMessage = 'Insufficient funds. Please use a different payment method.';\n } else if (error.message.includes('expired')) {\n userMessage = 'This card has expired. Please use a different card.';\n } else if (error.message.includes('CVV') || error.message.includes('security')) {\n userMessage = 'Invalid security code. Please check your CVV.';\n } else if (error.code === 'SDK1114' || error.message.includes('authentication')) {\n userMessage = '3D Secure authentication failed. Please try again.';\n }\n \n setError(userMessage);\n setIsLoading(false);\n }\n });\n\n // 3. Mount Drop-in\n checkoutDropIn.create('checkout-drop-in-container');\n \n } catch (err) {\n console.error('Failed to initialise checkout:', err);\n setError('Failed to load payment form. Please refresh the page.');\n }\n }\n\n return (\n
\n

Complete Your Purchase

\n \n
\n

Order Summary

\n

Product: Premium Subscription

\n

Amount: $25.00 USD

\n
\n \n {error && (\n
\n {error}\n
\n )}\n \n {isLoading && (\n
\n Processing payment...\n
\n )}\n \n
\n \n

\n Your payment information is securely processed by PXP. \n We never store your full card details.\n

\n
\n );\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":23},"children":["What's next?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that you've integrated Checkout Drop-in, here are some recommended next steps:"]},{"$$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/web/configuration"},"children":["Configuration"]}]},": Customise branding, colours, and styling in the Unity Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/events"},"children":["Events"]}]},": Learn about all available callbacks and event handling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/testing"},"children":["Testing"]}]},": Use test cards and sandbox environment to test your integration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/get-started/about-webhooks"},"children":["Configure webhooks"]}]},": Set up server-side webhook handling for reliable payment verification."]}]}]},"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: Install the Web SDK library","id":"step-1-install-the-web-sdk-library","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":"Prepare and send your request","id":"prepare-and-send-your-request","depth":3},{"value":"Session response","id":"session-response","depth":3},{"value":"Step 4: Initialise Drop-in on your frontend","id":"step-4-initialise-drop-in-on-your-frontend","depth":2},{"value":"Configuration parameters","id":"configuration-parameters","depth":3},{"value":"Step 5: Mount Drop-in to your page","id":"step-5-mount-drop-in-to-your-page","depth":2},{"value":"Step 6: Handle callbacks","id":"step-6-handle-callbacks","depth":2},{"value":"onGetShopper callback","id":"ongetshopper-callback","depth":3},{"value":"onSuccess callback","id":"onsuccess-callback","depth":3},{"value":"onError callback","id":"onerror-callback","depth":3},{"value":"Step 7: Backend verification (CRITICAL)","id":"step-7-backend-verification-critical","depth":2},{"value":"Primary method: Webhooks","id":"primary-method-webhooks","depth":3},{"value":"Optional fallback: Query the Transactions API","id":"optional-fallback-query-the-transactions-api","depth":3},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Complete example","id":"complete-example","depth":2},{"value":"What's next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Implementation"}},"lastModified":"2026-05-06T11:36:25.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/web/implementation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}