On this page:

Overview
- What is a payment facilitator?
- What is a Merchant-Site Template?
Registering as a PayFac Merchant
Onboarding a Submerchant
- Select a Merchant-Site Template
- Submit the Payload
PayFac Integration
- subMerchant Class
- dynamicDescriptor Class

Overview

What is a payment facilitator?

A payment facilitator (PayFac) is a “merchant service provider” who has a merchant account in the Nuvei system that is configured for onboarding submerchants and offers “Payment Acceptance” and “Payment Processing Services” to their clients (the “submerchants”).
A PayFac provides the following to their clients (the “submerchants”):
- Payment Processing Services:
  Payments and other requests sent by the PayFac merchant (on behalf of their submerchants) are processed by the Nuvei system in the same way as any other regular merchant with a few extra parameters to identify the submerchant.
- A “submerchant” account:
  The PayFac has a Nuvei “merchant” account with one or more “merchant sites” connected to it. Each “merchant site” represents a “submerchant” account belonging to one of the PayFac’s clients (the “submerchant”).
- A PayFac acts on behalf of their submerchants in a number of ways, for example:
  - Sending payment and other requests on behalf of their submerchant.
  - Receiving settlement transaction proceeds from acquirers on behalf of their submerchants.
  - Signing a Merchant Acceptance Agreement with their submerchants on behalf of an acquirer.
- A simplified “merchant enrollment process”:
  Registering as a merchant with multiple card issuing institutions requires a considerable investment in time and involves meeting many financial and performance requirements.
A “PayFac merchant” account must be configured for onboarding submerchants. (For details, contact the Nuvei Integration Support Team.)

What is a Merchant-Site Template?

A “merchantSite” template is a specially designated “merchantSite” account linked to a “PayFac merchant” account that is used by the API method during the “submerchant” onboarding (registration) process. The method “clones” all the necessary configurations from the template and, together with other parameters provided, creates a new merchantSite account that represents the new “submerchant”.
Each merchant-site template configuration is customized by Nuvei to meet the regulatory requirements for particular submerchant profile or particular industry.
“MerchantSite” templates are created for you by the Nuvei Sales Team.
A “PayFac merchant” is the only type of merchant that can call an API request.
“PayFac merchants” can only have “merchantSite” templates and “merchantSite” accounts linked to their account.
“Merchant-site” templates are custom-built and linked to a “PayFac merchant” account and cannot be transferred to another “PayFac merchant” account.

Registering as a PayFac Merchant

To register as a Nuvei PayFac merchant, the Nuvei Sales Team creates a new PayFac merchant account for you, as well as one or more merchant-site templates. This involves:

Finalizing all the contracts and legalities.
We guide you through all the legal work and procedures till the point where you are ready to onboard submerchants yourself.
We create a “PayFac merchant” account for you and enable the facility for onboarding submerchants yourself.
Then we create one or more merchant-site templates in your account and customize their configurations to meet the regulatory requirements for particular submerchant profiles or particular industry.
This involves:
- Identifying submerchant profiles or particular industries that suit your client profiles in order to associate the correct MCC (merchant category code) to the templates.
- Configuring other relevant submerchant profile or industry particular information, for example, industry specific parameters, settings, or configurations.
Registration complete.
We provide you with your new Nuvei master account (the merchant account), credentials (merchantId and merchantSecretKey), and one or more merchant-site templates (merchantSiteId) that you specified.

Onboarding a Submerchant

Register your clients as “submerchants” in the Nuvei system using our simplified “merchant enrollment process” as follows:

Select a Merchant-Site Template

Finalize all contracts and other legalities with your client (the submerchant).

Select the appropriate merchant-site template from the templates in your account.

Submit the Payload

Submit the payload using Nuvei’s onboarding API as follows:

Credentials

Enter your API credentials – Credentials (username and password) should be created for the PayFac with appropriate permissions, after which this user receives an email notification to set up (or reset) their credentials.

Endpoints

Call the endpoints in the following flow:

Authorization

applink.nuvei.com/api/Account/Login?api-version=1.0

Authorization returns a bearer token that must be used in subsequent calls.

Username: Provided by Nuvei Team
Password: Provided by Nuvei Team

After authorization, continue with the following three required operations:

Application Creation

applink.nuvei.com/api/Application/bc359770-845e-45fd-82f8-b22d97d1ecb0?api-version=1.0

The key in the application creation endpoint below is specific to EU PayFac and must be used.

This submission returns an applicationID to be used for subsequent operations.

Document Attachment

applink.nuvei.com/api/Document/{applicationID}?api-version=1.0

Application Submission

applink.nuvei.com/api/Application/Submit/{applicationID}?api-version=1.0

Submit the Sample Request

Include the mandatory and other relevant input parameters in the API request:

Request Input Parameters

Class	Name	Description	Type	Mandatory
	merchantId	Your `merchantId` as the PayFac merchant, provided by Nuvei.	string(20)	yes
	subMerchantId	Your client's identifier (submerchant) in your system.	string(15)	yes
	subMerchantName	Your client's name (submerchant) in your system.	string(100)	yes
	siteName	The merchant’s site name.	string(100)	yes
	templateId	The `merchantSiteId` (provided by Nuvei) of the merchant-site template, on which you selected to base the new submerchant account.	string(20)	yes
	gatewayTemplateId	The `gatewayId` (provided by Nuvei) of the Payfac template. This template is used to copy all the settings to and from the newly created accounts.	string(20)	yes
	MCCCode	A 4-digit number that classifies the type of goods or services a business offers.	string(4)	yes
	defaultTransactionType	For example: "Sale", "Auth", etc.	string(16)	yes
registeredAddress	buildingNumber	Specifies the building number if there is more than one building at an address.	string(20)	no
	country	2-letter ISO code (... of the submerchant)	string(2)	yes
	zip	... of the submerchant.	string(10)	yes
	city	... of the submerchant.	string(20)	yes
	street	... of the submerchant.	string(60)	yes
	state	... of the submerchant.	string(2)	no
	phoneNumber	... of the submerchant.	string(18)	yes
mainContact	firstName	... of the submerchant.	string(30)	yes
	lastName	... of the submerchant.	string(40)	yes
	email	... of the submerchant.	string(100)	no
	partnerId	The partner ID in the Nuvei CRM, provided by Nuvei.	string(20)	yes
	websiteURL	The website of the submerchant. If they do not have one, use the website of the PayFac/partner.	string(100)	yes
	monthlyProcessingVISAMC	The merchant's estimated monthly processing with VISA and MC combined.	number(16)	yes
	chargebackAmountRatio	The merchant's estimated chargeback ratio, as a percentage of the total number of transactions. Possible Picklist values are: Under 0.5%, 0.5–1%, 1–2%, 2–5%, Above 5%	Picklist	yes
	refundAmountRatio	The merchant's estimated refund ratio, as a percentage of the total number of transactions. Possible Picklist values are: Under 0.5%, 3–5%, 5–10%, Above 10%	Picklist	yes
	principalOwnerFirstName	First name of the principal owner of the capital of your submerchant.	string(32)	yes
	principalOwnerLastName	Last name of the principal owner of the capital of your submerchant.	string(32)	yes
	principalOwnerCountry	Country of origin of the principal owner of the capital of your submerchant.	string(100)	yes
	principalOwnerPhoneNumber	Phone number of the principal owner of the capital of your submerchant.	string(20)	yes
	newExistingTerminatedSubMerchant	The status of the submerchant. Possible values: New, Existing, Terminated Possible Picklist values are: New, Existing, Terminated	Picklist	yes
	reasonForTermination	If the status is Terminated, provide a reason or leave empty.	string(20)	no

Example Request

{
  "merchantId":"<your merchantId>",
  "subMerchantId": "<submerchant ID in your system>",
  "subMerchantName":"<submerchant name in your system>",
  "siteName":"<merchant’s site name>",
  "templateId":"<ID of a merchant-site template>",
  "gatewayTemplateId":"3340",
  "MCCCode":"3599",
  "defaultTransactionType":"Auth",
  "registeredAddress":{
    "buildingNumber":"221B",
    "country":"GB",
    "state":"",
    "city":"London",
    "street":"Baker Street",
    "zip":"NW1 6XE",
    "phoneNumber":"+442072243688"
  },
  "mainContact":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]"
  },
  "partnerId":"01p7J0000067Pt2",
  "websiteURL":"http://test-web-site.com",
  "monthlyProcessingVISAMC":"102345435",
  "chargebackAmountRatio":"Under 0.5%",
  "refundAmountRatio":"3 - 5%",
  "principalOwnerFirstName":"TESTFIRST",
  "principalOwnerLastName":"TESTLAST",
  "principalOwnerCountry":"United Kingdom",
  "principalOwnerPhoneNumber":"+442072243688",
  "newExistingTerminatedSubMerchant":"New",
  "reasonForTermination":"fraud"
}

The API method checks that:

The merchant’s account (your PayFac account) is configured for onboarding submerchants. (For details, contact the Nuvei Sales Team.)
The merchant-site template (the template to be cloned as identified by templateId) is correctly configured and is linked to your merchant account. (Merchant-site templates are created by Nuvei on request. For details, contact the Nuvei Sales Team.)
Validates the identity of the calling merchant by verifying the checksum.

Example Response – Success Result

{
  "subMerchant":{
    "id":"1234566",
    "status":"active"
  }"resultStatus":"SUCCESS"
}

The id returned is the new merchantSiteId, which you need to identify the submerchant when sending requests on their behalf.

Example Response – Error Result

{
  "subMerchant":{
    "id":"",
    "status":""
  }"resultStatus":"ERROR",
  "resultCode":"5000.1022",
  "resultDescription":"Invalid merchant site ID"
}

PayFac Integration

Payments and other requests are sent by the PayFac on behalf of their submerchants.

Include the following input parameters in transaction requests performed on behalf of the submerchant.

`subMerchant` Class

The subMerchant class contains the following parameters:

Parameter	Description
countryCode (String, 2)	The 2-letter ISO country code of the payment facilitator's submerchant.
city (String, 20)	The city name of the payment facilitator's submerchant.
id (String, 15)	Represents the internal merchant's ID, which is sent to the relevant card scheme.
address (String, 48)	The physical location of the transaction or the business location for online transactions. For PayFac-enabled transactions, `subMerchant.address` is mandatory.
state (String, 6)	The Country Subdivision Codes of the payment facilitator's submerchant. For PayFac-enabled transactions, `subMerchant.state` is mandatory.
phone (String, 18)	Phone number of the submerchant for transaction inquiries. For payment facilitator-enabled transactions, the submerchant's customer service phone number. For PayFac-enabled transactions, `subMerchant.phone` is recommended.

`dynamicDescriptor` Class

The dynamicDescriptor class contains the submerchant name and contact information parameters, which is displayed by the issuer in the transaction line item on the customer’s card statement.

If you are using the Web SDK, then include a dynamicDescriptor class when calling /openOrder (prior to calling the Web SDK createPayment())

Parameter	Description
merchantName (String, 22)	Format: `XXX<merchant name>` where:* `XXX` This is the PayFac prefix (approved by Nuvei Underwriting Team). Can be a length of 3, 7, 9, or 12. * – A fixed character. `<merchant name>` The name of the submerchant. Can be a length of 18, 14, 12, or 9, respectively.
merchantPhone (String, 13)	The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.

Example `/payment` Request that Includes the `dynamicDescriptor`and `subMerchant` Classes

{
    "sessionToken": "<sessionToken from getSessionToken>",
    "merchantId": "<your merchantId goes here>",
    "merchantSiteId": "<submerchant identifier>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "GBP",
    "amount": "10",
    "subMerchant": {
        "countryCode": "GB",
        "city": "London",
        "id": "12323"
    }
    "dynamicDescriptor": {
        "merchantName": "<merchantName>",
        "merchantPhone": "<merchantPhone>"
    },
    "paymentOption": {
        "card": {
            "cardNumber": "4017356934955740",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217"
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "billingAddress": {
        "country": "GB",
        "email":" [email protected] "

    },
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}

Payment Facilitators