Overview

This topic describes:

• Registering as a Nuvei PayFac merchant
• Onboarding a Sub-merchant
• PayFac Integration

What is a PayFac?

• A payment facilitator (PayFac) is a “merchant service provider” who has a merchant account in the Nuvei system that is configured for onboarding sub-merchants and offers “Payment Acceptance” and “Payment Processing Services” to their clients (the “sub-merchants”).
• A PayFac provides the following to their clients (the “sub-merchants”):
  • Payment Processing Services –
    Payments and other requests sent by the PayFac merchant (on behalf of their sub-merchants) are processed by the Nuvei system in the same way as any other regular merchant with a few extra parameters to identify the sub-merchant.
  • A “sub-merchant” account –
    The PayFac has a Nuvei “merchant” account with one or more “merchant sites” connected to it. Each “merchant site” represents a “sub-merchant” account belonging to one of the PayFac’s clients (the “sub-merchant”).
  • A PayFac acts on behalf of their sub-merchants in a number of ways, for example:
    • Sending payment and other requests on behalf of their sub-merchant.
    • Receiving settlement transaction proceeds from acquirers on behalf of their sub-merchants.
    • Signing a Merchant Acceptance Agreement with their sub-merchants 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 sub-merchants. (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 /createSubMerchant API method during the “sub-merchant” onboarding (registration) process. The method “clones” all the necessary configurations from the template and, together with other parameters provided, creates a new merchantSite account which represents the new “sub-merchant”.
• Each merchant-site template configuration is customized by Nuvei to meet the regulatory requirements for particular sub-merchant 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 a /createSubMerchant 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:

1. 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 sub-merchants yourself.
2. We’ll create a “PayFac merchant” account for you and enable the facility for onboarding sub-merchants yourself.
3. Then we’ll create one or more merchant-site templates in your account and customize their configurations to meet the regulatory requirements for particular sub-merchant profiles or particular industry.
   This involves:
   
   • Identifying sub-merchant 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 sub-merchant profile or industry particular information, for example, industry specific parameters, settings, or configurations.
4. Registration complete.
   We provide you with your new Nuvei master account (the merchant account), credentials (merchantId and secret key), and one or more merchant-site templates (merchantSiteId) that you specified.
   

Onboarding a Sub-merchant

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

1. Finalize all contracts and other legalities with your client (the sub-merchant).
2. Select the appropriate merchant-site template from the templates in your account.
   It is very important to correctly match the MCC (merchant category code) contained the merchant-site template representing a specific merchant profile or particular industry to your new sub-merchant’s merchant profile or particular industry.

3. Register your client as a “sub-merchant” in the Nuvei system by sending a /createSubMerchant API request.
   • The method “clones” all the necessary configurations from the specified the merchant-site template (templateId) and, together with other parameters provided, creates a new merchantSite account which represents the new “sub-merchant”.
   • Select the relevant Endpoint URL:
     • Live: https://selfconfiguration.safecharge.com/api/onboarding/createSubMerchant
     • Test: https://selfconfiguration-int.safecharge.com/api/onboarding/createSubMerchant
   • Include the mandatory and other relevant input parameters in the /createSubMerchant API request:
     

     /createSubMerchant 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 (sub-merchant) in your system.	string(15)	yes
     	subMerchantName	Your client's name (sub-merchant) in your system.	string(100)	yes
     	templateId	The merchantSiteId (provided by Nuvei) of the merchant-site template, that you selected to base the new sub-merchant account on.	string(20)	yes
     	timeStamp	Format is: YYYYMMDDHHMMSS	string(14)	yes
     	checksum	The checksum is used to verify the authenticity of the merchant sending the request. Calculate the checksum as follows: Concatenate the values the following parameters, in the given order, into a UTF-8 encoded string, with no spaces: merchantId, subMerchantId, subMerchantName, tempateId, timeStamp, merchantSecretKey. Calculate the hash value of the string, using either the SHA256 or MD5 algorithm.	string(256)	yes
     mainContact	firstName	... of the sub-merchant.	string(30)	yes
     mainContact	lastName	... of the sub-merchant.	string(40)	yes
     mainContact	email	... of the sub-merchant.	string(100)	no
     descriptor	merchantName	Sub-merchant name, which is displayed by the issuer in the transaction line item on the customer's card statement. Format:"XXX*<merchant name>" where: XXX string(3) - The PayFac prefix, approved by Nuvei underwriting team. <merchant name> string(18) - Sub-merchant name.	string(200)	yes
     descriptor	merchantContact	The sub-merchant contact information can either be a phone number or an email address, which is displayed by the issuer in the transaction line item on the customer's card statement.	string(50)	yes
     registeredAddress	country	2-Letter ISO Code (... of the sub-merchant)	string(2)	yes
     registeredAddress	zip	... of the sub-merchant.	string(10)	yes
     registeredAddress	city	... of the sub-merchant.	string(20)	yes
     registeredAddress	street	... of the sub-merchant.	string(60)	yes
     registeredAddress	state	... of the sub-merchant.	string(2)	no
     registeredAddress	phoneNumber	... of the sub-merchant.	string(18)	no
     personOfInterest[]	type	Director, ubo, etc.	string(10)	yes
     personOfInterest[]	firstName	... of the person of interest.	string(30)	yes
     personOfInterest[]	lastName	... of the person of interest.	string(40)	yes
     personOfInterest[]	passportOrId	... of the person of interest.	string(20)	yes
     personOfInterest[]	dateOfBirth	Format: YYYY-MM-DD	string(10)	yes
     	url[]	One or more sub-merchant websites.	string(2048)	yes
     monthlyProcessing	visa	The sub-merchant's expected monthly VISA turnover.	int	yes
     monthlyProcessing	mastercard	The sub-merchant's expected monthly Mastercard turnover. Note: This value is required in order to get Mastercard risk and compliance approval.	int	yes
     	defaultTransactionType	For example: "Sale", "Auth", etc.	string(16)	no
     	defaultLanguage	2-Letter ISO Code - default to "en" if not available in the template.	string(2)	no
     urlDetails	successUrl	The URL the customer is directed to after a successful transaction. (Default from the template.)	string(2048)	no
     urlDetails	pendingUrl	The URL the customer is directed to when the transaction response is pending. (Default from the template.)	string(2048)	no
     urlDetails	errorUrl	The URL the customer is directed to after an unsuccessful transaction. (Default from the template.)	string(2048)	no
     urlDetails	backUrl	The URL the customer is directed to when pressing the 'Back' button. (Default from the template.)	string(2048)	no
     urlDetails	policyUrl	(Default from the template.)	string(2048)	no
     urlDetails	termsAndConditionsUrl	(Default from the template.)	string(2048)	no
     urlDetails	notifyUrl	The URL to which DMNs are sent (see the DMNs Guide). (Default from the template.)	string(2048)	no
     urlDetails	refererUrl	(Default from the template.)	string(2048)	no
     hppSettings	pageTitle	If not provided, then the subMerchantName is used.	string(100)	no
     hppSettings	validateReferrer	If not provided, then it takes the default from the template if it exists (if not, it defaults to false).	boolean(5)	no
     hppSettings	useIpGeoLocation	If not provided, then it takes the default from the template if it exists (if not, it defaults to true).	boolean(5)	no
     hppSettings	useShippingDetails	If not provided, then it takes the default from the template if it exists (if not, it defaults to true).	boolean(5)	no

4. Example /createSubMerchant Request

   {
     "merchantId":"<your merchantId>",
     "subMerchantId":"<sub-merchant Id in your system>",
     "subMerchantName":"<sub-merchant name in your system>",
     "siteName":"<sub-merchant name provided by you>",
     "templateId":"<ID of a merchant-site template>",
     "defaultTransactionType":"Sale",
     "defaultLanguage":"en_US",
     "descriptor":{
       "merchantName":"PFC*merchantName",
       "merchantContact":"00442030513031"
     },
     "urlDetails":{
       "successUrl":"https://srv-bsf-devppptrunk.com/ppp/defaultSuccess.do4",
       "pendingUrl":"https://srv-bsf-devppptrunk.com/ppp/defaultPending.do4",
       "errorUrl":"https://srv-bsf-devppptrunk.com/ppp/defaultError.do4",
       "backUrl":"https://srv-bsf-devppptrunk.com/ppp/defaultBack.do4",
       "policyUrl":"https://srv-bsf-devppptrunk.com/ppp/policyURL4",
       "termsAndConditionsUrl":"https://srv-bsf-devppptrunk.com/ppp/termsAndConditionsURL4",
       "notifyUrl":"https://srv-bsf-devppptrunk.com/ppptest/NotifyMerchantTest4",
       "refererUrl":"https://srv-bsf-devppptrunk.com/ppp/refererURL4"
     },
     "hppSettings":{
       "pageTitle":null,
       "validate Referrer":true,
       "useIpGeoLocation":true,
       "useShippingDetails":true
     },
     "registeredAddress":{
       "country":"<sub-merchant country>",
       "city":"<sub-merchant city>",
       "street":"<sub-merchant street and number>",
       "zip":"<sub-merchant zip>",
       "phoneNumber":"<sub-merchant phone number>"
     },
     "timeStamp":"20210126144200",
     "mainContact":{
       "firstName":"<firstName of sub-merchant main contact>",
       "lastName":"<lastName of sub-merchant main contact>"
     },
     "checksum":"3889a69696e12e99a86d4fa506bbe8ea",
     "personOfInterest": [
        {
          "type": "Director",
          "firstName": "TESTFIRST",
          "lastName": "TESTLAST",
          "passportOrId": "AB12345678",
          "dateOfBirth": "2000-10-14"
        },
        {
          "type": "Director3",
          "firstName": "TESTFIRST3",
          "lastName": "TESTLAST3",
          "passportOrId": "AB123456789",
          "dateOfBirth": "2003-10-14"
        }
      ],
      "url": [
        "https://test.url"
      ]
   }

   The /createSubMerchant API method checks that:

   • The Merchant’s account (your PayFac account) is configured for onboarding sub-merchants. (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 /createSubMerchant Response – Success Result

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

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

   Example /createSubMerchant 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 sub-merchants.

Include the following input parameters in transaction requests performed on behalf of the sub-merchant:

• The descriptor block contains the sub-merchant 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 descriptor block when calling /openOrder (prior to calling the Web SDK createPayment())

  The descriptor block should contain these parameters:

  Parameter Name to Use:	Parameter Value and Format:
  1. Use one of these two parameter names, depending on the method used: merchantName - When calling: /openOrder, /payment, /payout, (or these depreciated methods: /dynamic3D, /payment3D, paymentCC, or paymentAPM). descriptorMerchantName - When calling: /settleTransaction.	Format: XXX*<merchant name> String(22) where: XXX String(3) This is the PayFac prefix (approved by Nuvei underwriting team) <merchant name> String(18)
  2. Use one of these two parameter names, depending on the method used: merchantPhone - When calling: /openOrder, /payment, /payout, (or these depreciated methods: /dynamic3D, /payment3D, paymentCC, or paymentAPM). descriptorMerchantPhone - When calling: /settleTransaction.	The merchant contact information can either be a phone number or an email address.

  Example /payment Request that includes the descriptor Block

  {
      "sessionToken": "<sessionToken from getSessionToken>",
      "merchantId": "<your merchantId goes here>",
      "merchantSiteId": "<sub-merchant identifier>",
      "userTokenId": "<a user identifier>",
      "clientUniqueId": "<The ID of the transaction in sub-merchant system>",
      "currency": "USD",
      "amount": "10",
      "countryCode": "GB",
      "city": "London",
      "id": "12323",
      "descriptor": {
          "MerchantName": "PFC*merchantName",
          "MerchantPhone": "00442030513031"
      },
      "paymentOption": {
          "card": {
              "cardNumber": "4017356934955740",
              "cardHolderName": "John Smith",
              "expirationMonth": "12",
              "expirationYear": "2022",
              "CVV": "217"
          }
      },
      "deviceDetails": {
          "ipAddress": "93.146.254.172"
      },
      "billingAddress": {
          "address": "address",
          "city": "city",
          "country": "DE",
          "state": "",
          "zip": "1335"
      },
      "timeStamp": "20191105081132",
      "checksum": "5582d0189dd440f4bbf960569ec22e77"
  }