On this page:

Overview

Nuvei provides marketplace payment flows to accept customer payments for their multi-seller purchase, and handles the payment splits between the relevant marketplace sellers.

Nuvei’s marketplace multi-seller workflows allow customers to do the following:

Place a single order for goods that they select from multiple marketplace sellers (shops belonging to that marketplace).
Perform a single-checkout event on your marketplace checkout page or pop-up.
Pay for their purchases with a single payment transaction using one of their previously stored payment methods, or capture the details of another payment method.

For example, a customer shopping on an online marketplace site can order a shirt from Seller-A and shoes from Seller-B. They only need to perform a single checkout action on the marketplace checkout page and pay for their multi-seller purchases with a single payment transaction.

This page describes the payment flow with split payments for marketplaces for the supported integrations (REST API, Web SDK, and Simply Connect), as well as for financial transactions (Settle, Refund, and Void).

A payment flow with split payments is the same as a regular payment flow for each of the supported integrations, except that the splits array needs to be included, as described below.

Payment

The splits array represents the payment split between sellers.

Each class in the array should provide one set of order detail parameters for each split (seller) who is part of the multi-seller purchase:

sellerUniqueId – The unique transaction identifier in the marketplace system for this seller’s transaction.
sellerCustomData – This parameter can be used to pass any type of information.
sellerId – Seller processing ID received by the marketplace at the end of the boarding process.
amount – The payment amount for this split.
originalAmount – The original amount of the transaction in the currency that the merchant requested.
commission – The Marketplace service fee associated with the transaction.

All parameters in the splits array are mandatory except originalAmount and commission.

In addition to the initial 3D-Secure payment transaction, the splits array must be sent for all subsequent payment transactions, such as after a 3D-Secure challenge.

transactionType=Sale is relevant only for alternative payment methods (APMs), meaning non-card payments.

This chapter presents how to include the splits payments feature with the payment flow for each of the following integrations:

REST API
Web SDK and Simply Connect

REST API

A payment flow with split payments is the same as a regular 3D-Secure v2 REST API payment flow, except that the splits array needs to be included in the /payment calls.

The examples below show how to include the splits array in the /payment requests, and how it is returned in the responses.

Example `/payment` Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "card":{
      "cardNumber":"4000027891380961",
      "cardHolderName":"CL-BRW1",
      "expirationMonth":"12",
      "expirationYear":"2030",
      "CVV":"217",
      "threeD":{
        "methodCompletionInd":"Y",
        "version":"2.1.0",
        "notificationURL":"<notificationURL>",
        "merchantURL":"<merchantURL>",
        "platformType":"02",
        "v2AdditionalParams":{
          "challengeWindowSize":"05"
        },
        "browserDetails":{
          "acceptHeader":"text/html,application/xhtml+xml",
          "ip":"192.168.1.11",
          "javaEnabled":"TRUE",
          "javaScriptEnabled":"TRUE",
          "language":"EN",
          "colorDepth":"48",
          "screenHeight":"400",
          "screenWidth":"600",
          "timeZone":"0",
          "userAgent":"Mozilla"
        }
      }
    }
  },
  "splits":[
    {
      "sellerUniqueId":"34991440-A",
      "sellerCustomData":"34991440-A",
      "sellerId":"1111",
      "amount":"160",
      "originalAmount" : "150",
      "commission":"10"
    },
    {
      "sellerUniqueId":"34991440-B",
      "sellerCustomData":"34991440-B",
      "sellerId":"2222",
      "amount":"40",
      "originalAmount" : "20",
      "commission":"10"
    }
  ],
  "relatedTransactionId":"<transactionId returned from initPayment>",
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/payment` Response

{
  "orderId":"277057469",
  "paymentOption":{
    "userPaymentOptionId":"",
    "card":{
      "ccCardNumber":"4****0961",
      "bin":"400002",
      "last4Digits":"0961",
      "ccExpMonth":"12",
      "ccExpYear":"22",
      "acquirerId":"19",
      "cvv2Reply":"",
      "avsCode":"",
      "cardType":"Credit",
      "cardBrand":"VISA",
      "threeD":{
        "threeDFlow":"1",
        "acsUrl":"https://3dsn.sandbox.nuvei.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL2RvY3Muc2FmZWNoYXJnZS5jb20vM0RzaW11bGF0b3Ivbm90aWZpY2F0aW9uVXJsLnBocCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOTIyNzgxZjEtMmZlYy00MGQ5LWIyYjUtYTMwMmZkMzRlNWI2IiwiYWNzVHJhbnNJRCI6ImQ1ZWMxMmRkLTQ1ZGUtNDRkYS04YjZmLWNhYjJjYzU0MTVkNCIsImRzVHJhbnNJRCI6IjdmN2UwZGNjLTg3ZTktNDkwYy1iOTFlLWNiZjgwOTdmYjllOSJ9",
        "eci":"5",
        "version":"2.1.0",
        "whiteListStatus":"",
        "cavv":"",
        "acsChallengeMandated":"Y",
        "cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjkyMjc4MWYxLTJmZWMtNDBkOS1iMmI1LWEzMDJmZDM0ZTViNiIsImFjc1RyYW5zSUQiOiJkNWVjMTJkZC00NWRlLTQ0ZGEtOGI2Zi1jYWIyY2M1NDE1ZDQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
        "authenticationType":"01",
        "cardHolderInfoText":"",
        "sdk":{
          "acsSignedContent":""
        },
        "result":"C",
        "acsTransId":"d5ec12dd-45de-44da-8b6f-cab2cc5415d4",
        "dsTransID":"7f7e0dcc-87e9-490c-b91e-cbf8097fb9e9",
        "threeDReasonId":"",
        "isExemptionRequestInAuthentication":"0",
        "challengePreferenceReason":"12"
      }
    }
  },
  "transactionStatus":"REDIRECT",
  "gwErrorCode":0,
  "gwExtendedErrorCode":0,
  "transactionType":"Auth3D",
  "transactionId":"1110000000011302215",
  "externalTransactionId":"",
  "authCode":"",
  "customData":"",
  "sessionToken":"acb48e94-a464-48d8-846a-9142ed556231",
  "internalRequestId":235059509,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"427583496191624621",
  "merchantSiteId":"142033",
  "version":"1.0",
  "clientRequestId":"20210126115246",
  "splits":[
    {
      "splitId":"1000",
      "sellerUniqueId":"eg. 34991440-A",
      "sellerCustomdData":"eg. 34991440-A",
      "sellerId":"1111"
    },
    {
      "splitId":"2000",
      "sellerUniqueId":"eg. 34991440-B",
      "sellerCustomdData":"eg. 34991440-B",
      "sellerId":"2222"
    }
  ]
}

Web SDK and Simply Connect

A payment flow with split payments is the same as regular Web SDK and Simply Connect payment flows except that the splits array needs to be included in the /openOrder call.

The examples below show how to include the splits array in the /openOrder request, and how it is returned in the response.

Example `/openOrder` Request

{
  "merchantId":"<your merchantId goes here>",
  "merchantSiteId":"<your merchantSiteId goes here>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "currency":"USD",
  "amount":"200",
  "splits":[
    {
      "sellerUniqueId":"34991440-A",
      "sellerCustomData":"34991440-A",
      "sellerId":"1111",
      "amount":"160",
      "commission":"10"
    },
    {
      "sellerUniqueId":"34991440-B",
      "sellerCustomData":"34991440-B",
      "sellerId":"2222",
      "amount":"40",
      "commission":"10"
    }
  ],
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/openOrder` Response

{
  "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
  "orderId":"39272",
  "merchantId":"427583496191624621",
  "merchantSiteId":"142033",
  "clientUniqueId":"12345",
  "clientRequestId":"1484759782197",
  "internalRequestId":"866",
  "status":"SUCCESS",
  "errCode":"0",
  "reason":"",
  "version":"1.0",
  "splits":[
    {
      "splitId":"1000",
      "sellerUniqueId":"eg. 34991440-A",
      "sellerCustomdData":"eg. 34991440-A",
      "sellerId":"1111"
    },
    {
      "splitId":"2000",
      "sellerUniqueId":"eg. 34991440-B",
      "sellerCustomdData":"eg. 34991440-B",
      "sellerId":"2222"
    }
  ]
}

Settle

After the internal order management workflows takes place, the Marketplace can initiate a settle request to move the funds (total or partial) from the customer into the designated Marketplace account by sending one or more /settleTransaction requests, where the total does not exceed the original purchase value.

Send a /settleTransaction request with its mandatory parameters, and include splitId for the split (seller) and commission, as shown below.

splitId for settlements in the 3D-Secure flow should only be taken from the financial transactions with transactionStatus=APPROVED:

frictionless flow – splitId from the first payment transaction with Approved status.
challenge flow – splitId from the second payment transaction with Approved status.

Example `/settleTransaction` Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in MARKETPLACE system (e.g. 34991440)>",
  "amount":"100",
  "currency":"EUR",
  "relatedTransactionId":"<transactionId returned from payment (e.g. 711000000014904840)>",
  "splitId":"<ID of the split payment returned from API per seller>",
  "commission": "<marketplace service fee associated with the transaction>", 
  "authCode":"<paymentAuthCode>",
  "urlDetails":{
    "notificationUrl":""
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/settleTransaction` Response

{
  "transactionId":"711000000014909141",
  "externalTransactionId":"",
  "issuerDeclineCode":"",
  "issuerDeclineReason":"",
  "gwErrorCode":0,
  "gwExtendedErrorCode":0,
  "transactionStatus":"APPROVED",
  "authCode":"111619",
  "clientUniqueId":"34991440",
  "CVV2Reply":"",
  "AVSCode":"",
  "transactionType":"Settle",
  "customData":"",
  "acquirerId":"19",
  "bin":"400002",
  "last4Digits":"5032",
  "ccCardNumber":"4****5032",
  "ccExpMonth":"12",
  "ccExpYear":"25",
  "cardType":"Credit",
  "cardBrand":"VISA",
  "issuerCountry":"GB",
  "issuerBankName":"River Valley Credit Union",
  "isPrepaid":"false",
  "internalRequestId":505535788,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2062949206179461709",
  "merchantSiteId":"191816",
  "version":"1.0",
  "clientRequestId":"20220830165034",
  "splitId":"1000"
}

Refund

After a payment is settled, you can refund the money back to the customer if necessary, by sending /refundTransaction requests, and include the splitId parameter for the split (seller), as shown below.

splitId for refunds in the 3D-Secure flow should only be taken from the financial transactions with transactionStatus=APPROVED:

frictionless flow – splitId from the first payment transaction with Approved status.
challenge flow – splitId from the second payment transaction with Approved status.

Alternatively, if the customer initiates a chargeback for the entire order amount via their card issuer, then Nuvei sends a real-time notifications of chargeback requests received, status updates of the dispute, and so on.

Example `/refundTransaction` Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in MARKETPLACE system (e.g. 34991440)>",
  "amount":"100",
  "currency":"EUR",
  "commission": "<negative value of MARKETPLACE service fee (e.g. -20)>",
  "relatedTransactionId":"<paymentTransactionId returned from payment>",
  "splitId": "<ID of the split payment returned from API per seller>",
  "authCode": "<paymentAuthCode>",
  "urlDetails": {
    "notificationUrl": ""
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/refundTransaction` Response

{
  "transactionId": "711000000014599174",
  "externalTransactionId": "",
  "issuerDeclineCode": "",
  "issuerDeclineReason": "",
  "gwErrorCode": 0,
  "gwExtendedErrorCode": 0,
  "transactionStatus": "APPROVED",
  "authCode": "111014",
  "clientUniqueId": "34991440",
  "CVV2Reply": "",
  "AVSCode": "",
  "transactionType": "Credit",
  "customData": "",
  "acquirerId": "19",
  "bin": "400002",
  "last4Digits": "5032",
  "ccCardNumber": "4****5032",
  "ccExpMonth": "12",
  "ccExpYear": "25",
  "cardType": "Credit",
  "cardBrand": "VISA",
  "issuerCountry": "GB",
  "issuerBankName": "River Valley Credit Union",
  "isPrepaid": "false",
  "internalRequestId": 500772878,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "850502379161961074",
  "merchantSiteId": "229708",
  "version": "1.0",
  "clientRequestId": "20220823155810",
  "splitId": "1000"
}

Void

When voiding a split payment, the void applies to the entire authorized payment amount of the multi-seller purchase.

/voidTransaction is relevant only for transactionType=Auth.

Approved payment requests, which do not have any /settleTransaction requests performed yet (not even for part of the amount), can be voided. The void releases the hold that was placed on the funds in the customer’s account.

You can void the payment authorization by sending a /voidTransaction API request (for the entire multi-seller payment amount), in order to release the hold on the funds in the customer’s account.

If one of the split payments was settled, then the payment authorization cannot be voided.

Example `/voidTransaction` Request

{
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "relatedTransactionId": "<transactionId returned from /payment>",
    "amount": "200",
    "currency": "USD",
    "urlDetails": {
     "notificationUrl": "<notificationURL>"
    },
    "clientRequestId": "<unique request ID in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}

Example `/voidTransaction` Response

{
    "transactionId": "1110000000004320759",
    "externalTransactionId": "",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionStatus": "APPROVED",
    "authCode": "111454",
    "clientUniqueId": "20200307173638",
    "CVV2Reply": "",
    "AVSCode": "",
    "transactionType": "VoidCredit",
    "customData": "",
    "acquirerId": "19",
    "bin": "400002",
    "last4Digits": "8694",
    "ccCardNumber": "4****8694",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "cardType": "Credit",
    "cardBrand": "VISA",
    "v2supported": "false",
    "internalRequestId": 178720058,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "4960497427404081578",
    "merchantSiteId": "197846",
    "version": "1.0",
    "clientRequestId": "20200307173638"
}

Error Codes

The following error codes are related to split payments:

errCode	Reason
9108	Seller information missing
9109	Seller {{seller number}}not active
9110	The settlement amount exceeds the allowed amount.
9111	The refund amount exceeds the allowed amount
9112	The retailers amounts do not match the total transaction amount
9113	Vaild Split cart information should be present in the request
9114	Split cart information should not be present in the request. The Seller is not defined as a Marketplace
9115	The Transaction identifiers are not unique for the different parts of the split cart. Contact Nuvei Technical Support to resolve the issue.
9116	Seller {seller Number} is associated with a different `merchantSiteId`.
9117	A split cart transaction amount can’t be 0. Contact Nuvei Technical Support to resolve the issue.
9121	Invalid or missing Marketplace sellerInfo block
9122	Invalid or missing Marketplace clientInfo block

Split Payments between Sellers

Overview

Payment

REST API

Example /payment Request

Example /payment Response

Web SDK and Simply Connect

Example /openOrder Request

Example /openOrder Response