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).
Payment
The splits
array represents the payment split between sellers.
Each block 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.
This chapter presents how to include the splits payments feature with the payment flow for each of the following integrations:
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.
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.
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
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.
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 |