Storebox/Nexi Engage Integration

Value Proposition

Why Integrate Netaxept with Storebox?

In today's retail landscape, customers expect convenience and personalization at checkout. By connecting Netaxept’s secure payment processing with Storebox’s digital receipt and loyalty platform, you can automatically deliver digital receipts, unlock personalized loyalty rewards, and enroll customers into your membership programs—all triggered seamlessly by their payment card.

Business Benefits for Merchants

📌 Developer Integration Guide

Below you will find the complete, step-by-step developer integration guidelines to connect Netaxept with the Storebox API.

Storebox Integration Flow

This guide explains the full merchant flow: what must be arranged before integration, how a merchant obtains the PanHash from a Netaxept card-registration flow, and how to send it to Storebox.

Netaxept handles the card entry and registration. For Netaxept-specific concepts and operations, see the Netaxept developer documentation and REST API reference. Storebox API uses the resulting PanHash to enroll/add the card to Storebox.

How the Complete Flow Works

There are three separate activities:

1. Merchant onboarding: Storebox and Netaxept/Nexi provision the merchant and the credentials/configuration required for the integration.
2. Card registration with Netaxept: The merchant starts a Netaxept card-registration transaction, presents the Netaxept payment window to the customer, and obtains the PanHash from the completed transaction/query result.
3. Add the card to Storebox: The merchant backend sends the merchant ID, and PanHash to POST /storebox/addpanhash. The Storebox API adds the card to Storebox vault.

The merchant should call the Storebox endpoint only after the Netaxept card-registration flow has completed and the resulting PanHash is available. Do not send raw card details to the Storebox endpoint.

1. Complete Merchant Onboarding

The following diagram illustrates the merchant onboarding flow between Netaxept and Storebox.

Before making API calls, the merchant's integration owner should coordinate onboarding with the Storebox and Netaxept/Nexi teams. The diagram's onboarding flow represents the exchange and configuration of the merchant details and credentials that connect these systems.

Confirm all of the following for each environment (for example, test and production):

• Storebox merchant setup: The merchant has a Storebox account and knows which Storebox member identifier memberId to use for each customer.
• Netaxept merchant setup: Merchant has a Netaxept Merchant Idenitifer Netaxept merchantId which is associated with the card-registration transactions.
• API caller registration: The merchant has an Credentials from Netaxept to call the Storebox API. The same credentials can be used for different Netaxept merchant identifiers (for example, by country, city, or business unit)
• Environment URLs: Obtain the correct Netaxept environment, `Storebox API base URL, and any callback URL required by the integration. Test credentials and identifiers must not be used in production.

2. Register the Customer's Card with Netaxept

The following diagram illustrates the transaction card registration flow between the Merchant and Netaxept.

This step happens in the merchant's Netaxept integration, before calling Storebox:

1. The merchant backend initiates a Netaxept transaction intended for card registration, using the merchant's Netaxept configuration and the flow described in the official Netaxept developer documentation

2. Netaxept returns the transaction ID needed to continue the flow.

3. The merchant loads the Netaxept payment window for that transaction and presents it to the customer. The customer enters their card details and completes any authentication required by Netaxept.

4. After the customer returns or the transaction completes, the merchant backend queries Netaxept for the completed transaction. Follow the Netaxept query flow (https://developer.nexigroup.com/netaxept/en-EU/docs/query-call/) for the configured integration.

5. Read the PanHash from the relevant Netaxept result. Keep it associated with the correct customer and merchant. The PanHash is the value to pass as cardToken in the Storebox request.

   The Netaxept transaction registration, payment-window URL, and query request belong to the merchant's Netaxept integration. They are not performed by POST /storebox/addpanhash, and their exact parameters depend on the merchant's Netaxept setup. Use the official Netaxept API reference for those requests.

3. Obtain an Access Token for the Storebox API

The merchant backend must authenticate to the Storebox API with bearer access token.

Ask the Netaxept for the credentials. Do not embed a client secret in a browser or mobile application.

Request a token from the tenant's v2 endpoint:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

Form body (replace placeholders with credentials provisioned for the merchant):

client_id={client-id}
&client_secret={client-secret}
&scope={api-app-id-uri}/.default
&grant_type=client_credentials

Use the returned access_token as the bearer token on the Storebox API request. Obtain a new token when it expires.

4. Send the PanHash to Storebox

Endpoint

Request fields

memberid merchantId and cardToken must not be empty.

### Example request

POST {Storebox-API-base-url}/storebox/addpanhash HTTP/1.1
Authorization: Bearer {access-token}
Content-Type: application/json

{
  "memberId": "member-12345",
  "merchantId": "merchant-67890",
  "cardToken": "{panhash-from-Netaxept-query}",
  "callbackUrl": null
}

Or send the same request with curl:

curl --request POST \
  --url "{Storebox-API-base-url}/storebox/addpanhash" \
  --header "Authorization: Bearer {access-token}" \
  --header "Content-Type: application/json" \
  --data '{

Response

Success — 200 OK
The body is the Storebox card-add response. Example shape:

{
  "status": 0,
  "reason": "Card added",
  "externalCardId": "storebox-card-id",
  "enrollmentUrl": "https://storebox.example.com/enroll/..."
}

status: 0 means Okay in this API. Treat externalCardId and enrollmentUrl according to the Storebox integration agreed for the merchant. A 200 indicates that the Storebox API returned Okay; it does not, by itself, confirm completion of a separate customer SCA step.

Errors

Data handling and operational guidance

Treat PanHashes, access tokens, client secrets, and card-enrollment URLs as sensitive. Transmit them only over TLS and keep them out of browser code, source control, and application logs. Use separate merchant configuration and credentials per environment