Payment Facilitators (PayFac)

On this page:

Overview

This section describes:

What is a PayFac?
  • A payment facilitator (PayFac) is a “merchant service provider” who has a merchant account in the Nuvei system, and offers payment acceptance and 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 has the configuration parameter merchantsOnboarding set to subMerchants.
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” on-boarding (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 to meet the regulatory requirements for particular sub-merchant profile or particular industry.
  • A merchantSite template is identified as a template account by the configuration parameter isSubMerchantTemplate, which is set to TRUE.
  • 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.

Register as a Nuvei PayFac Merchant

To register as a Nuvei PayFac merchant, the Nuvei sales team will create a new PayFac merchant account for you, and create one or more merchant-site templates. This involves:

  1. Finalizing all the contracts and legalities.
    We will guide you through all the legal work and procedures till the point where you are ready to on-board sub-merchants yourself.
  2. We’ll create a “PayFac merchant” account for you, and enable the facility for on-boarding 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 will 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.

On-board 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 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:
      1. 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.
      2. 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 will be 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 will be 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 will take the default from template (if it exists, if not it will default to false). boolean(5) no
      hppSettings useIpGeoLocation If not provided, then it will take the default from template (if it exists, if not it will default to true). boolean(5) no
      hppSettings useShippingDetails If not provided, then it will take the default from template (if it exists, if not it will default 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) has the attribute: merchantsOnboarding = subMerchant
    • The merchant-site template (the template to be cloned identified by templateId) has the attribute isSubMerchantTemplate = true, and that it is linked to your merchant account.
    • 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 will 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 will be displayed by the issuer in the transaction line item on the customer’s card statement).

    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:
    		 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:
    		 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"
}

 

 

 

Parameter Name to Use: Parameter Value and Format: