Nexi Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

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.

The adapter uses Nexi's Hosted Forms integration (Nexi's 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 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.

Supported payment methods and other features: Features Overview

Limitations

• Redirect flow only. Building a frontend on top of the Nexi adapter uses the hosted redirect flow (see Building a Frontend). Unlike the Adyen adapter, there is no embedded drop-in component or client-side SDK.
• 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.
• No webhook signature verification. The webhook endpoint is anonymous; merchant and channel identity travel as query parameters (see Webhook Configuration).

Configuration in Norce Admin

The adapter configuration is stored per merchant and channel. It is grouped into apiSettings (Nexi credentials), adapter (adapter URLs), paymentSettings (optional behavior), and redirectUrls (customer redirect targets).

API Settings

The apiSettings section holds the credentials you obtain from Nexi. These are secrets.

The adapter authenticates every call to Nexi using HTTP Basic authentication with clientId and clientSecret.

Adapter URLs

The adapter section defines the base URLs the adapter uses when registering callback URLs with Nexi.

Payment Settings (Optional)

The paymentSettings section is optional and controls payment behavior.

Redirect URLs

The redirectUrls section defines where the customer is sent after leaving the Nexi hosted form. Both fields support the placeholders {order.merchant}, {order.channel}, and {order.id}; checkoutPage additionally supports {errorCode}.

Nexi API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Nexi uses the following external API environments. The adapter appends /api/v2 to the configured apiUrl.

Create Payment

To start a Nexi payment, create a payment on an existing Norce Checkout order:

POST /api/checkout/v1/orders/{order_id}/payments
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}
Content-Type: application/json

{
  "paymentMethods": {
    "integrationType": "Hosted",
    "type": "Card"
  },
  "simulationMode": "0000"
}

The paymentMethods.type selects the Nexi payment method (for example Card, Ideal, Paypal, Swish, Vippsmobilepay). simulationMode is only used in the test environment. The optional browserInfo, device, and referencePayId fields may be supplied for card and 3D Secure scenarios.

For the hosted flow, the response contains the redirectUrl your frontend sends the customer to:

{
  "paymentId": "pmt_01HXXX...",
  "redirectUrl": "https://test.paygate.nexigroup.com/hostedpaymentpage/...",
  "status": "PENDING",
  "responseCode": null,
  "responseDescription": null
}

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.

Building a Frontend (Redirect Flow)

Building a frontend on top of the Nexi adapter has the most in common with the Adyen Checkout Adapter: the payment is initiated with the same POST .../orders/{order_id}/payments call. The difference is how the payment UI is rendered. Because Nexi uses the Hosted Forms flow, your storefront renders its own payment-method selector; when the customer picks a method, the adapter returns a 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.

The flow is:

1. Render the method selector and create the payment. Present the available payment methods in your own UI. When the customer selects one, call POST /api/checkout/v1/orders/{order_id}/payments from your backend (or a backend-for-frontend layer) with paymentMethods.integrationType set to Hosted and paymentMethods.type set to the chosen method. The x-merchant and x-channel headers identify the configuration to use.
2. Redirect the browser. Take the redirectUrl from the response and redirect the customer to it (for example window.location.href = redirectUrl). The customer enters their payment details on Nexi's hosted form.
3. 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 redirectUrls.confirmationPage (success) or redirectUrls.checkoutPage (failure/cancel), substituting the {order.id}, {order.merchant}, {order.channel}, and {errorCode} placeholders.
4. 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.

Webhook Configuration

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 adapter.internalUrl base URL) — no manual configuration in a Nexi dashboard is required.

The webhook URL pattern is:

{internalUrl}/api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/webhook?m={merchant}&c={channel}

Because Nexi cannot send Norce's x-merchant and x-channel headers, merchant and channel are passed as query parameters. The webhook payload contains the Nexi payId; the adapter fetches the full payment details from Nexi and maps the Nexi status to a standardized Norce payment state:

Post-Purchase Operations

Capture, refund, and cancel follow the generic pattern described in the Payment Adapters Overview. For Nexi these operations always apply to the full payment amount — partial capture and partial refund are not supported.

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/capture
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Use refund and cancel in place of capture for the corresponding operations. A refresh endpoint (POST .../payments/{payment_id}/refresh) rebuilds the list of available payment actions on the Norce order.

Troubleshooting (Nexi Specific)

In addition to the generic troubleshooting steps:

• Payment creation fails (400/404): Verify the order exists and that the requested paymentMethods.type is enabled for your Nexi account and channel. A payment method that is not configured returns a PAYMETHOD INVALID error from Nexi.
• Payment creation fails (409 Conflict): A Nexi payment already exists for this order. Remove the existing payment or use a different order.
• Authentication errors: Confirm apiSettings.clientId and apiSettings.clientSecret are correct and that apiSettings.apiUrl points at the matching environment (test vs. production).
• Customer not redirected back: Verify redirectUrls.confirmationPage and redirectUrls.checkoutPage are configured, and that adapter.publicUrl and adapter.internalUrl are reachable.
• Final state not updating: The final payment state depends on the webhook. Confirm adapter.internalUrl is reachable from Nexi and check the adapter logs for incoming webhook calls.

Links and References

• Nexi Checkout Adapter OpenAPI Specification
• Payment Adapters Overview
• Adyen Checkout Adapter — closest frontend integration reference
• Nexi Checkout Adapter (Business Overview)
• Nexi Paygate REST API — Create Payment (External)
• Nexi Paygate Webhooks Guide (External)