Overview

Visa requires acquirers and payment processors to transmit marketplace seller information through a clearing process. To comply, Nuvei requires that marketplace seller information is included in ‘Sale’ and ‘Settle’ requests in the ‘items‘ block. The Nuvei gateway computes a single aggregate ForeignSellerAmount value and sends the following values in TCR E: position 103 (Foreign Retailer Indicator) and TCR E: position 104–115 (Foreign Retailer Transaction Amount). Nuvei forwards the data to the Cards Gateway, which builds a compliant Visa clearing message. No seller ID, country or line item reaches Visa.

Request

items Block

Each ‘Sale’ request and ‘Settle’ request must include an ‘items‘ block. Each entry in the ‘items‘ block is a line item for a single seller and must contain the following parameters:

Rules

• One entry per seller-item combination. If a single order contains products from multiple sellers, send one item entry per-seller per-product.
• MPSellerId consistency. For a specific seller, use the same identifier across all transactions.
• MPSellerCountry must be ISO 3166-1 alpha-2. Only two-letter codes are permitted.
  
  Use ‘US’ (not ‘USA’); use ‘GB’ (not ‘UK’).

• Sum consistency.
  • The sum of ‘price’ multiplied by ‘quantity’ across all entries should equal the transaction amount. Any mismatch may result in an incorrect foreign amount and incorrect scheme fees.
• Calculation.
  • Only run if the merchant is a marketplace and the card-issuer country matches the marketplace country.
  • UK and EEA countries are treated as domestic and considered as a single country.
  • If an item is sent without a seller country, then the full line total for the item is added to the foreign amount.

Example ‘items‘ Block

"items": [
   { "name": "Wireless Headphones",  "price": "85.00", "quantity": "1", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
   { "name": "USB-C Charging Cable", "price": "15.00", "quantity": "2", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
   { "name": "Smartphone Case",      "price": "25.00", "quantity": "1", "MPSellerId": "SELLER_20015", "MPSellerCountry": "DE" },
   { "name": "Portable Power Bank",  "price": "40.00", "quantity": "1", "MPSellerId": "SELLER_30024", "MPSellerCountry": "ES" },
   { "name": "Laptop Stand",         "price": "35.00", "quantity": "2", "MPSellerId": "SELLER_40032", "MPSellerCountry": "FR" }
]

Total: (85.00×1) + (15.00×2) + (25.00×1) + (40.00×1) + (35.00×2) = 250.00

Integration

REST 1.0

The ‘ items‘ block applies to the following endpoints:

Sale – /payment.do

Example Request (Complete)

{
    "sessionToken": "8e7a8b8e-4f4e-4c1c-9a9d-1f1f1f1f1f1f",
    "merchantId": "1234567890",
    "merchantSiteId": "987654",
    "clientRequestId": "REQ-20260701-0001",
    "clientUniqueId": "ORDER-20260701-0001",
    "currency": "USD",
    "amount": "250",
    "userTokenId": "buyer_5567",
    "billingAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "address": "221B Baker Street",
        "city": "London",
        "country": "GB",
        "zip": "NW1 6XE",
        "email": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "192.168.1.10"
    },
    "paymentOption": {
        "card": {
            "cardNumber": "4000023104662535",
            "cardHolderName": "John Doe",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217"
        }
    },
    "items": [
        { "name": "Wireless Headphones", "price": "85.00", "quantity": "1", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
        { "name": "USB-C Charging Cable", "price": "15.00", "quantity": "2", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
        { "name": "Smartphone Case", "price": "25.00", "quantity": "1", "MPSellerId": "SELLER_20015", "MPSellerCountry": "DE" },
        { "name": "Portable Power Bank", "price": "40.00", "quantity": "1", "MPSellerId": "SELLER_30024", "MPSellerCountry": "ES" },
        { "name": "Laptop Stand", "price": "35.00", "quantity": "2", "MPSellerId": "SELLER_40032", "MPSellerCountry": "FR" }
    ],
    "timeStamp": "20260701120000",
    "checksum": "<<populated by merchant>>"
}

Settle – /settleTransaction.do

‘/settleTransaction.do‘ sends a seller-level breakdown of the settlement. The ‘items‘ block has the same structure as ‘/payment.do‘. For partial settlements, the ‘items‘ block includes only the line items in a specific settle call.

Open Order — /openOrder.do

If ‘/openOrder.do‘ initiates a payment session (such as in a Web SDK flow), include the ‘items‘ block in the ‘/openOrder‘  request. The information is retained through to the resulting Sale and Settle operations.

Web SDK

Web SDK does not collect line-item data on the front end. Before the Web SDK is invoked, seller information is passed on via the ‘/openOrder.do‘ (server-to-server). Web SDK completes the payment using the session created by ‘/openOrder.do‘ and seller information automatically flows through to clearing.

Recommended Flow

1. Server-side – The merchant backend calls ‘/openOrder.do‘ that includes the 'items' block.
   
   For more information about ‘items’ block, see REST 1.0 in this document.

2. Client-side – The merchant frontend initializes Web SDK with the ‘sessionToken‘ returned by ‘/openOrder.do‘.
3. Buyer – The buyer completes the payment in the Web SDK user-interface.
4. Settle – If the merchant settles the transaction (via auto-settle configuration or an explicit ‘/settleTransaction.do ‘ call), include the same 'items' block.

Server-side – /openOrder.do

Example Server-side – /openOrder.do

{
    "merchantId": "1234567890",
    "merchantSiteId": "987654",
    "clientRequestId": "REQ-20260701-0001",
    "clientUniqueId": "ORDER-20260701-0001",
    "currency": "USD",
    "amount": "250",
    "userTokenId": "buyer_5567",
    "items": [
        { "name": "Wireless Headphones", "price": "85.00", "quantity": "1", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
        { "name": "USB-C Charging Cable", "price": "15.00", "quantity": "2", "MPSellerId": "SELLER_10001", "MPSellerCountry": "GB" },
        { "name": "Smartphone Case", "price": "25.00", "quantity": "1", "MPSellerId": "SELLER_20015", "MPSellerCountry": "DE" },
        { "name": "Portable Power Bank", "price": "40.00", "quantity": "1", "MPSellerId": "SELLER_30024", "MPSellerCountry": "ES" },
       { "name": "Laptop Stand", "price": "35.00", "quantity": "2", "MPSellerId": "SELLER_40032", "MPSellerCountry": "FR" }
    ],
    "timeStamp": "20260701120000",
    "checksum": "<<populated by merchant>>"
}

Client-side Initialization

No change to the merchant Web SDK initialization code is required. Seller information is already attached to the session via ‘/openOrder.do‘. The function of the existing merchant checkout() or createPayment() invocation is not impacted.

Settle

If the merchant settles a transaction via ‘/settleTransaction.do‘, include the ‘items‘ block in the settle request using the same structure as in Server-side – /openOrder.do.

Validation

Take into account the following points in relation to validation.

• Length validation (only) is supported. The same length-based system validation that applies to existing ‘items‘ parameters applies to a new field. See Sale – /payment.do.
• No transaction declines. A transaction is not declined based on missing, incomplete, or malformed seller information.
• Compliance risk on merchant side. While a transaction clears, any missing or incorrect seller information exposes the merchant business to non-compliance with the Visa mandate and may result in scheme-level actions such as fees.
  • If the merchant does not send the ‘items‘ block , the transaction is not declined. The transaction is cleared without including the seller information that Visa requires and the total amount is reported as foreign, which is a non-compliance issue with possible downstream consequences via the scheme.

Response and DMN

The ‘items‘ block is not returned in the API Response or in the Direct Merchant Notification (DMN). No change is required on the merchant side to handle a response or webhook (DMN).

Testing in Sandbox

To test in the Nuvei sandbox:

1. Point the merchant integration to the Nuvei sandbox environment.
2. Submit the Sale (or an open order if using Web SDK) and Settle requests with the ‘items‘ block populated.
3. In the Sandbox Control Panel, verify that each transaction clears successfully and that the line-item data is reflected in the transaction details.
4. Test the following use cases:
   • Single seller, single item
   • Single seller, multiple items
   • Multiple sellers, multiple items
   • Foreign sellers (non-domestic MPSellerCountry)
   • Partial settlement with a subset of the original items

Important Considerations

• The mandate applies to all marketplace transactions, regardless of how many sellers are involved. For example, even if a transaction has only one seller, the merchant must send the seller block.
• If a merchant marketplace includes only domestic sellers, seller information is still required. Although the mandate’s primary objective is foreign-seller reporting, Visa requires seller information on every marketplace transaction for consistency in clearing.
• The MPSellerId value can be any string, as long as the string is unique for the seller on the merchant platform and remains stable. Because Nuvei uses the MPSellerId value to aggregate seller-level reporting, any change to the MPSellerId value for a specific seller fragments the reporting to Visa.
• If the merchant does not send the ‘items‘ block after October 1, 2026, the transaction is not declined. The transaction is cleared without including the seller information that Visa requires and the total amount is reported as foreign, which is a non-compliance issue with possible downstream consequences via the scheme.
• The scope of this document is Sale and Settle. Refund and Void behavior is unchanged. In future, if Visa extends the mandate to include refund flows, this document is subject to update.
• The merchant does not need to change anything in response handling or in webhook processing because the ‘items‘ block does not impact the response or DMN.

Support