Developers

Overview

This section describes how to send a payment and other requests on behalf of your sub-merchants.

What is a PayFac?

A payment facilitator (PayFac) is a “merchant service provider” that provides the following to their clients (the “sub-merchants”):

• Payment processing services. – Payment 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 only a few extra parameters to identify the sub-merchant.
• A “sub-merchant” account. – The PayFac has a standard Nuvei “merchant” account with multiple “merchant sites” connected to it, each representing one of their “sub-merchant” accounts.
• A simplified “merchant enrollment process”.
• A PayFac acts on behalf of their sub-merchants in a number of ways, for example:
  • Signing a Merchant Acceptance Agreement on behalf of an acquirer.
  • Send payment and other requests on behalf of their sub-merchant.
  • Receive settlement transaction proceeds from acquirers on behalf of their sub-merchants.

PayFac Integration

Payments and other requests are sent by the PayFac on behalf of their sub-merchants.
Nuvei PayFacs can choose any of the Nuvei integration methods listed in the “Accept Payment” menu item, in the Introduction page.

Include the following field blocks in sub-merchant transaction requests:

1. Include a subMerchant block, containing the following fields, when calling these requests: /openOrder, /payment, /settleTransaction, /refundTransaction, voidTransaction, and /payout:
   
   The subMerchant block must contain these fields:

   Field Name	Description
   countryCode String(2)	Sub-merchant’s two-letter ISO country code.
   city String(20)	Sub-merchant’s city name.
   id String(15)	Internal merchant ID to be forwarded to MC as "subMerchantId". Validation: Type: ANS, not null, maximum length (15)
2. If you are using the Web SDK, then include a dynamicDescriptor block, when calling /openOrder (prior to calling the Web SDK createPayment()):
   The dynamicDescriptor block contains the merchant name and contact information fields, (which will be displayed by the issuer in the transaction line item on the customer’s card statement).
   
   The dynamicDescriptor block should contain these fields:

   Field Name	Description
   Use a different field name depending on which method you are calling: Use merchantName String(22) when calling: /openOrder, /payment, /payout, (or these depreciated methods: /dynamic3D, /payment3D, paymentCC, or paymentAPM). Use descriptorMerchantName as the field name when calling: /settleTransaction.	Structure: XXX*<merchant name> where: XXX String(3) This is the PayFac prefix (approved by Nuvei underwriting team) <merchant name> String(18)
   Use a different field name depending on which method you are calling: Use merchantPhone when calling: /openOrder, /payment, /payout, (or these depreciated methods: /dynamic3D, /payment3D, paymentCC, or paymentAPM). Use descriptorMerchantPhone as the field name when calling: /settleTransaction.	The merchant contact information can either be a phone number or an email address.

Example /payment Request that includes a subMerchant and dynamicDescriptor Blocks

{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "<your merchantId goes here>",
    "merchantSiteId": "<your merchantSiteId goes here>",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "10",
    "countryCode": "GB",
    "city": "London",
    "id": "12323",
    "dynamicDescriptor": {
        "MerchantName": "PFC*merchantName",
        "MerchantPhone": "00442030513031"
    },
    "subMerchant": {
        "id": "123123",
        "countryCode": "GB",
        "city": "London"
    },
    "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"
}