Last updated

Norce Checkout - Nexi Adapter API

Version: 1.0.0

Adapter for the Nexi Paygate payment gateway. Handles payment creation (Hosted Forms and Direct integration), webhooks, and order management (capture, refund, cancel).

Base URLs

  • http://nexi-adapter.checkout.playground.norce.tech/

Endpoints

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/webhook

Nexi webhook

Webhook callback from Nexi Paygate. Receives the Nexi payId and resolves the final payment status.

Parameters

  • merchant (query) required
    • Merchant identifier (query param — Nexi cannot send custom headers)
    • Type: string
  • channel (query) required
    • Channel identifier (query param)
    • Type: string
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Nexi webhook payload containing the payId

Content-Type: application/json

Schema: BasicWebhook

Content-Type: text/json

Schema: BasicWebhook

Content-Type: application/*+json

Schema: BasicWebhook

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

GET /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/return

Payment return URL

Invoked when the customer is redirected back from the Nexi hosted payment form after completing payment. Resolves the final payment status by querying Nexi for payment details, then redirects the browser to the configured confirmation page (success) or checkout page (failure).

Parameters

  • merchant (query) required
    • Merchant identifier (query param — browser redirects cannot send custom headers)
    • Type: string
  • channel (query) required
    • Channel identifier (query param)
    • Type: string
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

303

See Other

GET /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/cancel

Payment cancel URL

Invoked when the customer cancels payment on the Nexi hosted form. Marks the payment as cancelled if it has not already been reserved or captured, then redirects the browser to the configured checkout page.

Parameters

  • merchant (query) required
    • Merchant identifier (query param — browser redirects cannot send custom headers)
    • Type: string
  • channel (query) required
    • Channel identifier (query param)
    • Type: string
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

303

See Other

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/update-payment

Update payment hook

Internal hook invoked by checkout-order when the cart changes on an order with an active Nexi payment. Updates the Nexi payment amount to match the new order total.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Full Norce order payload from the hook

Content-Type: application/json

Schema: NorceOrder

Content-Type: text/json

Schema: NorceOrder

Content-Type: application/*+json

Schema: NorceOrder

Responses

200

OK

Content-Type: application/json

Schema: Array of PatchOperation

Content-Type: text/json

Schema: Array of PatchOperation

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/state-updated

State updated hook

Internal hook invoked by checkout-order when the order state changes. Currently a no-op — order state advancement is driven from the external webhook/return callbacks.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Request Body

Full Norce order payload from the hook

Content-Type: application/json

Schema: NorceOrder

Content-Type: text/json

Schema: NorceOrder

Content-Type: application/*+json

Schema: NorceOrder

Responses

200

OK

Content-Type: application/json

Schema: Array of PatchOperation

Content-Type: text/json

Schema: Array of PatchOperation

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

POST /api/checkout/v1/orders/{order_id}/payments

Initialize a Nexi payment

Creates a new Nexi payment for an existing Norce checkout order. Returns a redirect URL for Hosted integration, or inline payment result for Direct integration.

Parameters

Request Body

Payment method selection and optional browser/device data for Direct integration

Content-Type: application/json

Content-Type: text/json

Content-Type: application/*+json

Responses

200

OK

Content-Type: application/json

Schema: NexiCheckoutOrder

Content-Type: text/json

Schema: NexiCheckoutOrder

400

Bad Request

Content-Type: application/json

Schema: Error

Content-Type: text/json

Schema: Error

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

409

Conflict

Content-Type: application/json

Schema: Error

Content-Type: text/json

Schema: Error

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/capture

Capture payment

Capture a reserved Nexi payment. Transfers the authorized funds from the customer's account. Only available when the payment is in Reserved state.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

409

Conflict

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/refund

Refund payment

Refund a captured Nexi payment. Returns the captured funds to the customer. Only available when the payment is in Captured state.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

409

Conflict

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/cancel

Cancel payment

Cancel a reserved Nexi payment. Releases the authorization hold without capturing. Only available when the payment is in Reserved state.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

200

OK

400

Bad Request

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

409

Conflict

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/refresh

Refresh payment actions

Rebuilds the available action list (Capture, Cancel, Refund) on the Norce payment to reflect the current payment state.

Parameters

  • merchant (header)
  • order_id (path) required
    • Type: string
  • payment_id (path) required
    • Type: string

Responses

200

OK

404

Not Found

Content-Type: application/json

Schema: ProblemDetails

Content-Type: text/json

Schema: ProblemDetails

Schemas

Addon

Properties

  • reference (null,string)
  • price (number,string)

Address

Properties

  • type - CustomerType
  • givenName (null,string)
  • familyName (null,string)
  • careOf (null,string)
  • reference (null,string)
  • organizationName (null,string)
  • streetAddress (null,string)
  • streetAddress2 (null,string)
  • postalCode (null,string)
  • city (null,string)
  • region (null,string)
  • country (null,string)
  • phone (null,string)
  • email (null,string)
  • nationalIdentificationNumber (null,string)
  • organizationIdentificationNumber (null,string)
  • attributes (null,object)

ApplePay

Properties

  • token (null,string)
  • merchantIdentifierOfPublicKey (null,string)

BasicWebhook

Properties

  • payId (null,string)

BrowserInfoDto

Properties

  • acceptHeaders (null,string)
  • ipAddress (null,string)
  • javaEnabled (null,boolean)
  • javaScriptEnabled (null,boolean)
  • language (null,string)
  • colorDepth (null,integer,string)
  • screenHeight (null,integer,string)
  • screenWidth (null,integer,string)
  • timeZoneOffset (null,string)
  • userAgent (null,string)

Callback

Properties

  • id (null,string)
  • adapterId (null,string)
  • event - CallbackEvent
  • url (null,string)

CallbackEvent

Card

Properties

  • subType (null,array)
  • dccEnabled (null,boolean)
  • template
  • prefillInfo
  • number (null,string)
  • cardHolderName (null,string)
  • expiryDate (null,string)
  • brand (null,string)
  • securityCode (null,string)
  • startDate (null,string)
  • sequenceNumber (null,string)
  • brandSelection
  • tokenData

CardBrandSelection

CardPrefillInfo

Properties

  • cardHolderName (null,string)

CardSubType

CardTemplate

Properties

  • name (null,string)
  • fontSize (null,integer,string)
  • textColor (null,string)
  • backgroundColor (null,string)
  • backgroundImage (null,string)
  • fontName (null,string)
  • tableWidth (null,integer,string)
  • tableHeight (null,integer,string)
  • customFields (null,object)

CardTokenData

Properties

  • cryptogram (null,string)
  • eci (null,string)
  • tokenRequestor

CardTokenRequestor

Cart

Properties

  • reference (null,string)
  • items (null,array)
  • discounts (null,array)
  • total
  • attributes (null,object)

Properties

  • id (null,string)
  • checked (boolean)
  • text (null,string)
  • required (boolean)

CreatePaymentRequest

Properties

  • paymentMethods - PaymentMethods required
  • browserInfo
  • device
  • referencePayId (null,string)
  • simulationMode (null,string)

Customer

Properties

CustomerType

DeliveryDetails

Properties

  • carrier (null,string)
  • class (null,string)
  • product
  • pickupLocation

DeviceDto

Properties

  • deviceId (null,string)
  • deviceType (null,string)
  • deviceOs (null,string)

DirectDebit

Properties

  • account
  • mandate
  • method (null,string)

DirectDebitAccount

Properties

  • number (null,string)
  • accountHolderName (null,string)
  • code (null,string)
  • bankName (null,string)

DirectDebitMandate

Properties

  • mandateId (null,string)
  • dateOfSignature (null,string)

Discount

Properties

  • type - DiscountType
  • name (null,string)
  • code (null,string)
  • value
  • attributes (null,object)

DiscountType

EasyCollect

Properties

  • eventToken
  • mandateId (null,string)

EasyCollectEventToken

Error

Properties

  • code (null,string)
    • Error code
    • Example: "cart-not-found"
  • message (null,string)
    • Detailed error information
    • Example: "Cart with id:{id} now found."

GooglePay

Properties

  • token (null,string)

Hook

Properties

  • id (null,string)
  • adapterId (null,string)
  • subscribeTo (null,string)
  • target (null,string)
  • invoke (null,string)

IntegrationType

Item

Properties

  • id (null,string)
  • reference (null,string)
  • name (null,string)
  • sku (null,string)
  • url (null,string)
  • imageUrl (null,string)
  • quantity (integer,string)
  • unit (null,string)
  • price
  • total
  • originalTotal
  • vatRate (number,string)
  • discounts (null,array)
  • logistics
  • attributes (null,object)

Logistics

Properties

  • weight (null,integer,string)
  • height (null,integer,string)
  • width (null,integer,string)
  • length (null,integer,string)

NexiCheckoutOrder

Properties

  • paymentId (null,string)
    • Identifier of the payment created in the Norce checkout order.
  • redirectUrl (null,string)
    • URL to the Nexi hosted payment form. Redirect the customer here to complete payment.
  • status (null,string)
  • responseCode (null,string)
  • responseDescription (null,string)

NorceOrder

Properties

  • id (null,string)
  • merchant (null,string)
  • channel (null,string)
  • reference (null,string)
  • created (string)
  • lastModified (string)
  • state
  • culture (null,string)
  • currency (null,string)
  • country (null,string)
  • cart
  • shippings (null,array)
  • payments (null,array)
  • customer
  • consents (null,array)
  • validations (null,array)
  • hooks (null,array)
  • notifications (null,array)
  • total
  • attributes (null,object)

OrderStatus

PatchOperation

Properties

  • op (null,string)
  • path (null,string)
  • value

Payment

Properties

  • id (null,string)
  • adapterId (null,string)
  • name (null,string)
  • merchant (null,string)
  • channel (null,string)
  • currency (null,string)
  • type - PaymentType
  • orderId (null,string)
  • amount (number,string)
  • upperLimitAmount (null,number,string)
  • state - PaymentState
  • reference (null,string)
  • attributes (null,object)
  • actions (null,array)
  • recurring

PaymentAction

Properties

  • id (null,string)
  • adapterId (null,string)
  • type (null,string)
  • url (null,string)

PaymentMethods

Properties

PaymentMethodType

PaymentState

PaymentType

PayPal

Properties

  • accountId (null,string)
  • expressCheckout (null,boolean)
  • hideAddress (null,boolean)

PfConnect

Properties

  • merchantCountryCode (null,string)
  • financialProductId (null,string)
  • shoppingBasketAmount (null,integer,string)
  • downPaymentAmount (null,integer,string)
  • deliveryDate (null,string)
  • applicationDate (null,string)
  • aboId (null,string)
  • quotationId (null,string)
  • customerRole (null,string)

PickupLocation

Properties

  • reference (null,string)
  • name (null,string)
  • address

PickupLocationAddress

Properties

  • streetAddress (null,string)
  • city (null,string)
  • postalCode (null,string)
  • country (null,string)

Price

Properties

  • includingVat (number,string)
  • excludingVat (number,string)

ProblemDetails

Properties

  • type (null,string)
  • title (null,string)
  • status (null,integer,string)
  • detail (null,string)
  • instance (null,string)

Product

Properties

  • reference (null,string)
  • name (null,string)

Ratepay

Properties

  • subType
  • transferType

RatepaySubType

RatepayTransferType

Recurring

Properties

  • token (null,string)
  • description (null,string)
  • attributes (null,object)

RequiredMerchantHeaderModel

Properties

  • merchantId (null,string) required
    • Merchant identifier.
    • Example: "norce"
  • channel (null,string) required
    • Channel identifier
    • Example: 1

Shipping

Properties

  • id (null,string)
  • merchant (null,string)
  • channel (null,string)
  • state - ShippingState
  • reference (null,string)
  • tmsReference (null,string)
  • orderId (null,string)
  • adapterId (null,string)
  • name (null,string)
  • total
  • vatRate (number,string)
  • deliveryDetails
  • addons (null,array)
  • attributes (null,object)

ShippingState

State

Properties

Transition

Properties