{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-portal/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Nexi Checkout Adapter","description":"Home of the Norce Commerce documentation"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"nexi-checkout-adapter"},"children":["Nexi Checkout Adapter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Overview Document:"]}," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/payment-adapters"},"children":["Payment Adapters Overview"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview-and-unique-capabilities"},"children":["Overview and Unique Capabilities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Nexi Checkout Adapter integrates Nexi Group's payment platform (Nexi Paygate v2) with Norce Checkout. This page focuses on the unique technical details and configuration for Nexi."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter uses Nexi's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Forms"]}," integration (Nexi's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integrationType=HOSTED"]},"): your storefront renders its own payment-method selector, and once the customer picks a method you create a Nexi payment for that specific method. The adapter returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," to Nexi's hosted form, where the customer enters their sensitive payment details. The customer is then redirected back to your storefront, and Nexi confirms the final payment state to the adapter asynchronously via a server-to-server webhook."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Hosted Forms, not Hosted Payment Page"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This adapter implements Nexi's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Forms"]}," flow, where your storefront controls the payment-method selection UI and Nexi hosts only the form that collects sensitive details. This is different from Nexi's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Payment Page"]},", where the customer selects the payment method ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["and"]}," enters details entirely on a Nexi-hosted page. The Hosted Payment Page flow is not used by this adapter."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported payment methods and other features: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["Features Overview"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"limitations"},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redirect flow only."]}," Building a frontend on top of the Nexi adapter uses the hosted redirect flow (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#building-a-frontend-redirect-flow"},"children":["Building a Frontend"]},"). Unlike the Adyen adapter, there is no embedded drop-in component or client-side SDK."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full capture, refund, and cancel only."]}," Partial capture and partial refund are not supported. Each post-purchase operation always applies to the full payment amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No webhook signature verification."]}," The webhook endpoint is anonymous; merchant and channel identity travel as query parameters (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#webhook-configuration"},"children":["Webhook Configuration"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-in-norce-admin"},"children":["Configuration in Norce Admin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter configuration is stored per merchant and channel. It is grouped into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings"]}," (Nexi credentials), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter"]}," (adapter URLs), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentSettings"]}," (optional behavior), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls"]}," (customer redirect targets)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-settings"},"children":["API Settings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings"]}," section holds the credentials you obtain from Nexi. These are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["secrets"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example Value"},"children":["Example Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Nexi Paygate base URL (test or production). The adapter appends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://test.paygate.nexigroup.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Client ID provided by Nexi. This is your Nexi merchant ID."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100xxxxxx"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Client secret provided by Nexi. This is your API key."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["••••••••"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter authenticates every call to Nexi using HTTP Basic authentication with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"adapter-urls"},"children":["Adapter URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter"]}," section defines the base URLs the adapter uses when registering callback URLs with Nexi."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example Value"},"children":["Example Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Internal base URL used for the server-to-server webhook and internal order hooks."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{slug}.api-se.{env}.norce.tech/checkout/nexi-adapter"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Public base URL used for the browser-facing return and cancel URLs."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{slug}.api-se.{env}.norce.tech/checkout/nexi-adapter"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-settings-optional"},"children":["Payment Settings (Optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentSettings"]}," section is optional and controls payment behavior."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Default Value"},"children":["Default Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sales channel: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MOTO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYBYLINK"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POS"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ECOM"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captureMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Capture behavior: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTOMATIC"]}," (capture immediately), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MANUAL"]}," (capture on request), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELAYED"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTOMATIC"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delayedHours"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Hours to delay automatic capture. Required when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captureMethod"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELAYED"]}," (1–696)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dccEnabled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Enable Dynamic Currency Conversion for card payments."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["simulationMode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Nexi test-outcome simulation string (test environment only)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardTemplateName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Name of the hosted card-form template."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardTemplateFontSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Font size for the hosted card form."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardTemplateTextColor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Text color (hex) for the hosted card form."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#FFFFFF"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statementDescriptor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Text shown on the customer's bank statement."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalIntegrationId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["External integration ID passed through to Nexi."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["—"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-urls"},"children":["Redirect URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls"]}," section defines where the customer is sent after leaving the Nexi hosted form. Both fields support the placeholders ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.merchant}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.channel}"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.id}"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutPage"]}," additionally supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{errorCode}"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmationPage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["URL the customer is redirected to after a successful payment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutPage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["URL the customer is redirected to on failure, cancellation, or error."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"nexi-api-environments"},"children":["Nexi API Environments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the generic Norce Adapter URLs (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/payment-adapters"},"children":["Payment Adapters Overview"]},"), Nexi uses the following external API environments. The adapter appends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2"]}," to the configured ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiUrl"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Nexi Paygate Base URL"},"children":["Nexi Paygate Base URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://paygate.nexigroup.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://test.paygate.nexigroup.com"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-payment"},"children":["Create Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To start a Nexi payment, create a payment on an existing Norce Checkout order:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/checkout/v1/orders/{order_id}/payments\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\nContent-Type: application/json\n\n{\n  \"paymentMethods\": {\n    \"integrationType\": \"Hosted\",\n    \"type\": \"Card\"\n  },\n  \"simulationMode\": \"0000\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods.type"]}," selects the Nexi payment method (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ideal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paypal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Swish"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Vippsmobilepay"]},"). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["simulationMode"]}," is only used in the test environment. The optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["browserInfo"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referencePayId"]}," fields may be supplied for card and 3D Secure scenarios."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the hosted flow, the response contains the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," your frontend sends the customer to:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentId\": \"pmt_01HXXX...\",\n  \"redirectUrl\": \"https://test.paygate.nexigroup.com/hostedpaymentpage/...\",\n  \"status\": \"PENDING\",\n  \"responseCode\": null,\n  \"responseDescription\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter also stores the Nexi payment details on the Norce order and registers order hooks so that cart and shipping changes keep the Nexi payment amount in sync."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Hosted vs. Direct integration"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The adapter supports both a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted"]}," (redirect) and a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Direct"]}," (server-side) integration type. The Hosted flow described here is the recommended path and the one used when building a storefront frontend. In the Direct flow the response returns the payment result inline (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseCode"]},") instead of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]},", and no browser redirect or callback URLs are used."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"building-a-frontend-redirect-flow"},"children":["Building a Frontend (Redirect Flow)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Building a frontend on top of the Nexi adapter has the most in common with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/adapters/adyen-checkout-adapter"},"children":["Adyen Checkout Adapter"]},": the payment is initiated with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../orders/{order_id}/payments"]}," call. The difference is how the payment UI is rendered. Because Nexi uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted Forms"]}," flow, your storefront renders its own payment-method selector; when the customer picks a method, the adapter returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," and you send the customer to Nexi's hosted form to enter their details. There is no embedded drop-in component or client-side SDK."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The flow is:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Render the method selector and create the payment."]}," Present the available payment methods in your own UI. When the customer selects one, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/checkout/v1/orders/{order_id}/payments"]}," from your backend (or a backend-for-frontend layer) with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods.integrationType"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Hosted"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods.type"]}," set to the chosen method. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-merchant"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-channel"]}," headers identify the configuration to use."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redirect the browser."]}," Take the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," from the response and redirect the customer to it (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window.location.href = redirectUrl"]},"). The customer enters their payment details on Nexi's hosted form."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle the return."]}," When the customer finishes (or cancels), Nexi redirects them back to the adapter's return or cancel endpoint. The adapter resolves the payment status and then redirects (HTTP 303) the customer to your configured ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls.confirmationPage"]}," (success) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls.checkoutPage"]}," (failure/cancel), substituting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.merchant}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{order.channel}"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{errorCode}"]}," placeholders."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rely on the webhook for the final state."]}," The authoritative payment state is set asynchronously when Nexi calls the adapter's webhook. Read the order's payment state from the Norce order rather than trusting the redirect alone."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Difference from Adyen"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Adyen adapter renders an embedded drop-in via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@adyen/adyen-web"]}," SDK and exposes additional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," endpoints for in-page state exchange. The Nexi adapter has no client-side SDK and no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," endpoints — after creating the payment, the browser is redirected to Nexi's hosted form and returns via the configured redirect URLs. Note that with Nexi's Hosted Forms flow your storefront owns the payment-method selection UI, whereas Adyen's drop-in renders the method selection for you."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-configuration"},"children":["Webhook Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nexi notifies the adapter of payment status changes through a server-to-server webhook. The adapter registers the webhook URL with Nexi automatically when the payment is created (using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.internalUrl"]}," base URL) — no manual configuration in a Nexi dashboard is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The webhook URL pattern is:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{internalUrl}/api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/webhook?m={merchant}&c={channel}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because Nexi cannot send Norce's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-merchant"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-channel"]}," headers, merchant and channel are passed as query parameters. The webhook payload contains the Nexi ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payId"]},"; the adapter fetches the full payment details from Nexi and maps the Nexi status to a standardized Norce payment state:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Nexi Status"},"children":["Nexi Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Norce Payment State"},"children":["Norce Payment State"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUCCESS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURE_REQUEST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captured"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REVERSED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["other"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"post-purchase-operations"},"children":["Post-Purchase Operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capture, refund, and cancel follow the generic pattern described in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/payment-adapters#post-purchase-operations"},"children":["Payment Adapters Overview"]},". For Nexi these operations always apply to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["full"]}," payment amount — partial capture and partial refund are not supported."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Allowed From State"},"children":["Allowed From State"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Result State"},"children":["Result State"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Capture"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captured"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Refund"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Cancel / reversal"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reserved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/order/v1/orders/{order_id}/payments/{payment_id}/capture\nHost: {slug}.api-se.stage.norce.tech\nx-merchant: {merchant}\nx-channel: {channel}\nAuthorization: Bearer {token}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refund"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancel"]}," in place of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture"]}," for the corresponding operations. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refresh"]}," endpoint (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../payments/{payment_id}/refresh"]},") rebuilds the list of available payment actions on the Norce order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-nexi-specific"},"children":["Troubleshooting (Nexi Specific)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the generic troubleshooting steps:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment creation fails (400/404):"]}," Verify the order exists and that the requested ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods.type"]}," is enabled for your Nexi account and channel. A payment method that is not configured returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMETHOD INVALID"]}," error from Nexi."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment creation fails (409 Conflict):"]}," A Nexi payment already exists for this order. Remove the existing payment or use a different order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication errors:"]}," Confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.clientId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.clientSecret"]}," are correct and that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiSettings.apiUrl"]}," points at the matching environment (test vs. production)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customer not redirected back:"]}," Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls.confirmationPage"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrls.checkoutPage"]}," are configured, and that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.publicUrl"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.internalUrl"]}," are reachable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Final state not updating:"]}," The final payment state depends on the webhook. Confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["adapter.internalUrl"]}," is reachable from Nexi and check the adapter logs for incoming webhook calls."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"links-and-references"},"children":["Links and References"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference/nco/openapi/nexi-adapter-read"},"children":["Nexi Checkout Adapter OpenAPI Specification"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/payment-adapters"},"children":["Payment Adapters Overview"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-portal/app-development/nco/adapters/adyen-checkout-adapter"},"children":["Adyen Checkout Adapter"]}," — closest frontend integration reference"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["Nexi Checkout Adapter (Business Overview)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.paygate.nexigroup.com/nexi-developer/rest-api-hosted-forms"},"children":["Nexi Paygate REST API — Create Payment (External)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.paygate.nexigroup.com/nexi-developer/rest-api-webhooks"},"children":["Nexi Paygate Webhooks Guide (External)"]}," "," "]}]}]},"headings":[{"value":"Nexi Checkout Adapter","id":"nexi-checkout-adapter","depth":1},{"value":"Overview and Unique Capabilities","id":"overview-and-unique-capabilities","depth":2},{"value":"Limitations","id":"limitations","depth":3},{"value":"Configuration in Norce Admin","id":"configuration-in-norce-admin","depth":2},{"value":"API Settings","id":"api-settings","depth":3},{"value":"Adapter URLs","id":"adapter-urls","depth":3},{"value":"Payment Settings (Optional)","id":"payment-settings-optional","depth":3},{"value":"Redirect URLs","id":"redirect-urls","depth":3},{"value":"Nexi API Environments","id":"nexi-api-environments","depth":2},{"value":"Create Payment","id":"create-payment","depth":2},{"value":"Building a Frontend (Redirect Flow)","id":"building-a-frontend-redirect-flow","depth":2},{"value":"Webhook Configuration","id":"webhook-configuration","depth":2},{"value":"Post-Purchase Operations","id":"post-purchase-operations","depth":2},{"value":"Troubleshooting (Nexi Specific)","id":"troubleshooting-nexi-specific","depth":2},{"value":"Links and References","id":"links-and-references","depth":2}],"frontmatter":{"checkout_path":"Norce Checkout (NCO)","execution_domain":"NCO Order API / NCO Adapters","product_area":"Checkout","product_component":"NCO","audience":"developers","seo":{"title":"Nexi Checkout Adapter"}},"lastModified":"2026-07-27T08:01:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-portal/app-development/nco/adapters/nexi-checkout-adapter","userData":{"isAuthenticated":false,"teams":["anonymous"]}}