Nuvei Mirakl Plugin for Marketplaces

Looking for one marketplace-focused solution, which is also fully compliant with the PSD2 regulatory requirements?

You’re in the right place!

Our solution for marketplace platforms has been designed to seamlessly integrate with Mirakl’s e-marketplace products and allows for fully customizable marketplace onboarding and split payments processes.

Mirakl Marketplace Platform is one of the most modern, flexible, and feature-rich Marketplace solution available, with years of best practices built in and also offering clients unparalleled expertise from their team of 30+ business, technical, and operational marketplace experts.

Not using Mirakl? No problem: we also offer Marketplace APIs to help you manage marketplace payments. More info here: https://docs-apm.nuvei.com/category/marketplace-api/.

The solution provides access to credit card payments and alternative payment methods for a Marketplace in a simple yet reliable legal and technical setup.

We are committed to help marketplaces run their business without worrying about the associated regulatory requirements from the new PSD2 directive which have come into force beginning 2018.

Nuvei solution ensures that all of the participating shops as well as the marketplace will benefit of a seamlessly onboarding process, reliable and secure transaction processing, reconciliation to the penny and prompt settlements.

The Mirakl plugin features:

  • automated import of all the the newly created shops and required documents from Mirakl to Smart2pay platform – leading to a fully customizable and seamless onboarding process.
  • automated shop approval notification which contains all info you need to start processing right away. More info here: Mirakl Notification for Shop Approval.
  • automated import of all payment instructions to marketplace participants and handling all the commission fees for the marketplace operator. Please discuss with our technical support the setup of your Mirakl voucher generation process.
  • supporting a wide range of payment methods from credit card payment to alternative payment methods with an all-in-one unified API and settlement flow. 

Here is how it works:

1 Marketplace - Processes and Systems

The technical process (KYC Flow) with all the necessary steps is described next:

    All KYC processes related to marketplace onboarding of the participating shops take place in Mirakl KYC system. All KYC processes related to payments take place in Nuvei KYC system.

  • Mirakl Marketplace accepts a new shop on its platform and creates an entry in its database.
  • Mirakl Marketplace exposes an API which Nuvei KYC platform calls several times per day to pull information about the newly created shops.
  • Nuvei KYC platform pulls all available information about the shop (ShopID, Alias, shop representative e-mail, documents etc.). If all the required information is not available, the merchant representative will have to fill it in on Nuvei KYC platform.
  • Nuvei will create an account for the shop in the Nuvei KYC platform and send an e-mail to the shop representative with the login details.
  • The shop representative will fill in any missing company related data and upload KYC/UBO specific documentation.
  • The shop representative signs online the Merchant agreement for Payment processing.
  • Nuvei Risk team reviews the company.
  • In case of approval, a siteID is generated in the Nuvei platform.
  • Nuvei will do a push notification to a page designated by Mirakl with the following info ShopID, SiteID, APIKEY. The last two parameters need to be used when calling Nuvei REST API when processing the payments. Mirakl Marketplace needs to respond with HTTP return code 204 (No content) to the POST notification.

Please contact our support team at technicalsupport-s2p@nuvei.com to schedule a more in depth demo on how we help your marketplace to process payments and perform split settlements.

Get the List of Shops from Mirakl Marketplace

Mirakl Marketplace Platform exposes an API which Nuvei can call to pull the list of newly created shops, using an action based on GET HTTP request. The response will contain a shop list in JSON format that returns all the shops that were created or updated after last_updated_date

Only a limited amount of details for each shop will be provided.

Definition: GET /api/shops?shop_ids=…&premium=…&state=…&updated_since=…&paginate=…

Where:
  • shop_ids – List of shop ids separated with comma. Limited to 100 values;
  • premium – Boolean : “ALL” (default), “FALSE” or “TRUE”. If TRUE (FALSE) returns only offers of premium (not premium) shop;
  • state – State of the shop;
  • updated_since – Filter all the shop that have been modified since the value of this parameter;
  • paginate – [optional] Control the pagination usage. Default : true.

Request Model:

GET /api/shops/{last_updated_date}
Authorization: Basic Pre-shared-APIKEY

Not all fields are mandatory in the above request! If Mirakl Marketplace does not provide all the necessary data, the shop representative will fill the missing fields in Nuvei platform. Another method of providing missing or incomplete data is by adding it in the additional fields and document fields in your Mirakl back office, if the initial configuration allows you to.

Once Nuvei identifies a newly created shop, it creates an account in Nuvei KYC platform for the shop representative and sends an email asking to finalize the application (e.g. fill missing info, upload documents, sign the online contract).

Get the List of Documents from Mirakl Marketplace

Information about the required documents can be retrieved by using an action based on GET HTTP request. The response will contain a list of documents provided for each Shop ID in JSON format.

Definition: GET /api/shops/documents?shop_ids=…

Where:
  • shop_ids – [required] A list of shop identifiers.

Request Model:

GET /api/shops/{shop_id}/documents
Authorization: Basic Pre-shared-APIKEY

The following documents are required by Nuvei KYC platform:

  1. Bank statement (Not older than 6 months, with account holder and IBAN code visible);
  2. Company certificate / Incorporation certificate (Not older than 6 months);
  3. Register of directors (or any other document showing the company’s legal representatives) (Not older than 6 months);
  4. Passport copy of company’s legal representatives and UBO (Ultimate Beneficial Owners – all natural persons that own or control, directly or indirectly more than 25% of the Company): Legible ID copy in color within validity period;

    5. Take into consideration that for each of the company UBOs that own or control more than 25% of the company you must also provide proper identity documents (Legible ID copy in color within validity period)!

  5. Utility bill that can be used as proof of address for company’s legal representatives (Not older than 6 months).

Mirakl Notification for Shop Approval

Whenever a shop is approved in Nuvei onboarding system, a notification is sent from Nuvei to Mirakl Marketplace where the following info is send, and whether it was successful or not.

Mirakl Marketplace needs to respond with HTTP return code 204 (No Content) otherwise the approval will be resubmitted!

Definition: POST /api/shop/{ID}/notification

Where:
  • {ID} – ID of the shop

Shop Approval Notification Format:

{
    "merchant_site": {
        "shop_id": Int,
        "site_id": Int (eg. 31261),
        "api_key": "SmasdsPx6n2KJU9MNKcBdlqdLJZOXSl9IA/kdksjSsdDWD",
        "created": "Date (yyyy-mm-dd hh:mm:ss, eg. 2018-12-31 23:59:59)",
        "url": "http://www.johnshop.it",
    }
}

Response:

204 No Content

We recommend you to always verify the Notification content we sent and not just simply/automatically respond to our notifications.

In exceptional cases it is possible to receive duplicate notifications and your system should be able to handle such situations.

If you do not respond to the notifications of type Approval or our system will keep sending the notifications until it receives a response!

Transactional Flow for Mirakl Marketplace

Orders containing items from multiple shops will be sent for authorization in multiple transactions, each transaction containing items for a single shop.

Credit card transactions are authorized and their status is communicated on the following route: Acquirer -> Nuvei -> Mirakl Marketplace.

Transactions should be captured within 7 days from authorization. For more information regarding capturing payments, please go to our section: Capture a Payment.

Tokenization, 3D and fraud prevention solutions are available upon request. For more information visit: Credit Card Payments.

Alternative payment methods are authorized and captured in one step and their status is communicated on the following route: Payment method provider -> Nuvei -> Mirakl Marketplace.

You need to integrate our REST API described here: https://docs-apm.nuvei.com.

Reconciliation process for Mirakl Marketplace

Nuvei reconciles at transaction level with the acquiring banks and alternative method providers.

The SiteID / APIKEY will be used to initiate the transactions towards Smart2Pay. The Mirakl Marketplace Transaction ID needs to be submitted by Nuvei REST API in the OriginatorTransactionID field for reporting and reconciliation purposes towards the shops / Mirakl Marketplace.

Settlement Flow for Mirakl Marketplace

Settlement cycles are defined in Nuvei system. Based on this, Nuvei generates settlement invoices for each shop. Also, Nuvei generates a commission settlement invoice for Mirakl Marketplace.

The acquiring banks and alternative payment method providers settle to Nuvei the Gross amount – Acquiring/Processing Fees:

  • Nuvei settles gross amount – operator commission – acquiring fees to each shop. Settlement frequency: weekly. If a different settlement frequency is needed, please contact your Nuvei account manager.
  • Nuvei settles commission to Mirakl Marketplace based on Transaction Log API exposed by the Mirakl. Settlement frequency: weekly. If a different settlement frequency is needed, please contact your Nuvei account manager.

Optional functionalities:

  • Subscription fee can be collected by Nuvei from the shops on behalf of the marketplace operator.
  • Manual credits / debits can be issued towards the shops by the Marketplace operator using Mirakl backoffice and will be performed by Smart2Pay.
  • Mirakl Marketplace can withhold the payment of certain transactions towards the shop (e.g. only the transactions with PaymentStatus marked as PAID will be settled).

Mirakl’s Pre-Settlement Transaction API

Mirakl Marketplace exposes a Transaction Log API based on which Nuvei settles commissions for. Information about all the transactions created or updated within a certain interval can be retrieved by using an action based on GET HTTP request. The response will contain a transaction list in JSON format that returns all the transactions that were created or updated in the interval start_date – end_date.

Only a limited amount of details for each transaction will be provided.

Definition: GET /api/transactions_logs?shop_id=…&start_date=…&end_date=…&start_transaction_date=…&e
nd_transaction_date=…&updated_since=…&payment_voucher=…&payment_states=…&transactio
n_types=…&paginate=…&accounting_document_number=…&order_ids=…&order_line_ids=…

Where:
  • shop_id – [optional] shop id for filtering;
  • start_date – [optional] creation date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • end_date – [optional] creation date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • start_transaction_date – [optional] transaction date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • end_transaction_date – [optional] transaction date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • updated_since – [optional] last updated date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • payment_voucher – [optional] payment voucher number for filtering;
  • payment_states – [optional] payment states separated by comma for filtering;
  • transaction_types – [optional] transaction types separated by comma for filtering;
  • paginate – [optional] Control the pagination usage. Default: true;
  • accounting_document_number – [optional] an accounting document number for filtering (invoice or credit note number);
  • order_ids – [optional] order id list for filtering, using comma (,) as a separator;
  • order_line_ids – [optional] order line id list for filtering, using comma (,) as a separator.

Request Model:

GET /v1/transactions?{start_date}&{end_date}
Authorization: Basic Pre-shared-APIKEY

The transaction_type field contains the following information:

  • COMMISSION_VAT
  • COMMISSION_FEE
  • ORDER_SHIPPING_AMOUNT
  • ORDER_AMOUNT
  • MANUAL_CREDIT
  • MANUAL_CREDIT_VAT
  • ORDER_AMOUNT_TAX
  • ORDER_SHIPPING_AMOUNT_TAX
  • REFUND_ORDER_AMOUNT
  • REFUND_ORDER_SHIPPING_AMOUNT
  • REFUND_COMMISSION_FEE
  • REFUND_COMMISSION_VAT
  • REFUND_ORDER_AMOUNT_TAX
  • REFUND_ORDER_SHIPPING_AMOUNT_TAX
  • SUBSCRIPTION_FEE
  • SUBSCRIPTION_VAT

Only the transactions with payment_state = “PAID” will be settled in the current settlement cycle.

Reporting process for Mirakl Marketplace

  1. Nuvei generates a daily transactional report file for Mirakl. The transactional report file contains the following information:
    ID
    ID
    Definition
    The ID of the transaction in Smart2Pay system
    Type
    int
    : The ID of the transaction in Nuvei system;
    MerchantTransactionID
    MerchantTransactionID
    Definition
    Merchant Transaction ID, a number that uniquely identifies a transaction in your system.
    Type
    string
    : Merchant Transaction ID, a number that uniquely identifies a transaction in your system;
    OriginatorTransactionID
    OriginatorTransactionID
    Definition
    The ID of the transaction/refund in The Marketplace system
    Type
    string
    : The ID of the transaction/refund in The Marketplace system;

    InputDateTime
    InputDateTime
    Definition
    The date and time of inserting the transaction in Smart2Pay system
    Type
    datetime
    : The date and time of inserting the transaction in Nuvei system;

    PaymentStateDefID
    PaymentStateDefID
    Definition
    The ID of the payment status in Smart2Pay system. It can have the following values: 1 - Open, 2 - Success, 3 - Cancelled, 4 - Failed, 5 - Expired, 9 - Authorized, 11 - Captured.
    : The status id of the transaction in Nuvei system;

    Status
    Status
    Definition
    The description of the transaction status in the Smart2Pay system: Open (Pending), Success (not used for card payments), Cancelled, Failed, Expired, Authorized, Captured.
    : The description of the transaction status in the Nuvei system;

    MerchantAmount
    MerchantAmount
    Definition
    The amount of the transaction.
    Type
    float
    : The amount of the transaction;

    MerchantCurrency
    MerchantCurrency
    Definition
    The currency of the transaction. ISO 4217 format (e.g. EUR)
    : The currency of the transaction;

    CapturedAmount
    CapturedAmount
    Definition
    The amount that has been captured. Float with 2 decimals (e.g. 33.99)
    Type
    float
    : The amount that has been captured;

    MethodID
    MethodID
    Definition
    The ID of the payment methods used. For credit cards payments the ID is 6.
    Type
    int
    : The ID of the payment methods used. For credit cards payments this is 6.;

    MethodName
    MethodName
    Definition
    The name of the payment method used: SmartCards.
    : The name of the payment method used.;

    ReportedByBOTOperatorDate
    ReportedByBOTOperatorDate
    Definition
    The date when the transaction was exported to CSV file.
    Type
    datetime
    : The date when the transaction was exported to csv file;

    SpecificDetails
    SpecificDetails
    Definition
    Specific Details
    : Not used;

    ReconciliationProviderID
    ReconciliationProviderID
    Definition
    The ID that appears on the bank statement of the customer (usually same as RootProviderTransactionID).
    Type
    string
    : ID appearing on the bank statement of the customer (usually same as RootProviderTransactionID);

    ProviderTransactionID
    ProviderTransactionID
    Definition
    Provider Transaction ID
    : Not used for card payments;

    MerchantAlias
    MerchantAlias
    Definition
    The name of the Shop.
    Type
    string
    : Shop Name;

    RootProviderTransactionID
    RootProviderTransactionID
    Definition
    The ID of the payment in acquiring system.
    Type
    string
    : ID of the payment in acquiring system;

    Country
    Country
    Definition
    The country of the payer if available. ISO_3166-1_alpha-2 format. (e.g. IT).
    : The country of the payer if available.

    2.  

  2. Nuvei will generate a Settlement invoice report containing information at transaction level for each shop. The Settlement invoice report contains the following information:1 Settlement invoice report per shop
    GPaymentId
    GPaymentId
    Definition
    GPaymentId
    : Not used;
    PaymentId
    PaymentId
    Definition
    The ID of the payment in Smart2Pay system.
    Type
    int
    : PaymentID in Nuvei system;

    Type
    Type
    Definition
    Transaction Type. It can be type: Payment, Refund, Inquiry or Chargeback.
    Type
    string
    : Transaction Type. Can be Payment, Refund, Inquiry or Chargeback;

    PaymentMethodName
    PaymentMethodName
    Definition
    The name of the payment method used. E.g. SmartCards
    Type
    string
    : Name of the payment method used;

    CustomerName
    CustomerName
    Definition
    The name of the customer, if available.
    Type
    string
    : The name of the customer, if available;

    MerchantName
    MerchantName
    Definition
    The name of the merchant account.
    Type
    string
    : The name of the merchant account;

    MerchantID
    MerchantID
    Definition
    The ID of the transaction/refund in your system.
    Type
    string
    : The transaction/refund id in your system;

    GtId
    GtId
    Definition
    GtId
    : Not used;

    IssuerName
    IssuerName
    Definition
    Issuer Name
    : Not used;

    IdealTrxId
    IdealTrxId
    Definition
    IdealTrxId
    : Not used;

    Country
    Country
    Definition
    The country of the payer, if available. ISO_3166-1_alpha-2 format. (e.g. IT).
    : The country of the payer, if available;

    InputDateTime
    InputDateTime
    Definition
    The date and time of inserting the transaction in Smart2Pay system.
    Type
    datetime
    : The date and time of inserting the transaction in Nuvei system;

    Amount
    Amount
    Definition
    The amount of the transaction.
    Type
    float
    : The amount of the transaction;

    Currency
    Currency
    Definition
    The currency of the transaction. ISO 4217 format (e.g. EUR).
    : The currency of the transaction;

    Status
    Status
    Definition
    The description of the transaction status in the Smart2Pay system: Open (Pending), Success (not used for card payments), Cancelled, Failed, Authorized, Captured
    : The description of the transaction status in the Nuvei system;

    ExchangeRate
    ExchangeRate
    Definition
    The exchange rate if the transaction needs to be converted from transaction currency to the settlement currency.
    Type
    float
    : The exchange rate if the transaction needs to be converted from transaction currency to the settlement currency;

    CalculatedAmount
    CalculatedAmount
    Definition
    The transaction amount converted to the settlement currency.
    Type
    float
    : The transaction amount converted to the settlement currency;

    ReferenceCurrency
    ReferenceCurrency
    Definition
    The settlement currency.
    Type
    float
    : The settlement currency;

    TransactionFee
    TransactionFee
    Definition
    Gateway fee (if applies).
    Type
    float
    : Gateway fee (if applies);

    GeneralFee
    GeneralFee
    Definition
    Gateway fee (if applies)
    Type
    float
    : Gateway fee (if applies);

    AttemptFee
    AttemptFee
    Definition
    Gateway fee (per attempt, if applies).
    Type
    float
    : Gateway fee (per attempt, if applies);

    IssuedFee
    IssuedFee
    Definition
    Gateway fee (per acquiring bank/payment method provider attempt fee if applies).
    Type
    float
    : Gateway fee (per acquiring bank/payment method provider attempt fee if applies);

    LocalVatFee
    LocalVatFee
    Definition
    Local payment method VAT (if applies).
    Type
    float
    : Local payment method VAT (if applies);

    VAT
    VAT
    Definition
    Value added tax (if applies).
    Type
    float
    : Value added tax (if applies);

    Comission
    Comission
    Definition
    Commission of the marketplace/agent (if applies).
    Type
    float
    : Commission of the marketplace/agent (if applies);

    SiteID
    SiteID
    Definition
    The ID of the shop.
    Type
    int
    : ID of the shop;

    SiteAlias
    SiteAlias
    Definition
    Shop Alias.
    Type
    string
    : Shop Alias;

    OriginatorTransactionID
    OriginatorTransactionID
    Definition
    The ID of the transaction/refund in The Marketplace system.
    Type
    string
    : The ID of the transaction/refund in The Marketplace system.

    3.  

  3. Nuvei will also generate an aggregated Settlement invoice report containing information at transaction level for the Marketplace. Settlement of the commission will be based on this settlement invoice. Format is the same as in the Settlement invoice report above.

Below there are examples of Settlement invoice reports in all supported formats: