Payment Facilitator

Introduction

📘

Please note, that this functionality has not been certified with all authorisation protocols our Gateway supports.

Payment facilitators (PFAC) take the role of a service provider, and are merchants registered by an acquirer to facilitate transactions on behalf of sub-merchants. The provider of the goods/services becomes the sub-merchant instead of the merchant. When the cardholder makes a purchase, the sub-merchant routes the transaction data to the payment facilitator. The payment facilitator incorporates all necessary transaction and merchant identification data and sends this to the acquirer.

There are 2 most commonly used PFAC models - Single-MID and Multi-MID model.

Single-MID model also known as Aggregator does not provide a separate merchant ID (MID) to their sub-merchants, they use aggregator’s own MID, simplifying the process for businesses that handle very low volumes of transactions.
Multi-MID model provides MID for each of the sub-merchants, that sign on under them. This model works great for medium sized businesses who don’t want to deal with the hassle involved in the traditional model.

The way how PFAC transactions are processed and flagged in the authorization message depends mainly on your boarding requirement, if you wish to get all your sub-merchants boarded in the Gateway or you would rather prefer to avoid boarding all your sub-merchants and initiate all transactions from your master-store (PFAC merchant).

Transaction initiated from Master-store

We highly recommend to check with your integration or 2nd level support team, if your store is eligible to use this functionality before proceeding with the implementation.

Once your store has been configured in our Gateway and flagged as PFAC master-store, you can send a transaction request on behalf of your sub-stores to the Gateway including paymentFacilitator object.

The following JSON document represents an example of a 'Sale' transaction triggered by PFAC master-store on behalf of their sub-store:

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": "10.00",
    "currency": "EUR"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "414746******0067",
      "securityCode": "XXX",
      "expiryDate": {
        "month": "08",
        "year": "29"
      }
    },
  "paymentFacilitator": {
     "subMerchantData":{
        "mcc": "5655",
        "legalName": "SubMerchant",
        "email": "[email protected]",
        "timezone": "Europe/Berlin",
        "address": {
					"address1": "Main Str. 55",
					"address2": "App. 234",
					"city": "Frankfurt",
					"region": "HE",
					"postalCode": "84375",
					"country": "DE"
    },
    "merchantId": "98765432"
		}
		}
  }
}

The following example represents the API response of an approved transaction:

{
    "clientRequestId": "2811bbe3-572a-41ff-a854-70873526ac22",
    "apiTraceId": "Y6ResHyDYXJ2lNo13ccwuwAAAxY",
    "ipgTransactionId": "84615279640",
    "orderId": "R1671716528939615968",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "VISA",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "08",
                "year": "2029"
            },
            "bin": "414746",
            "last4": "0067",
            "brand": "VISA"
        },
        "paymentMethodType": "PAYMENT_CARD"
    },
    "country": "Germany",
    "terminalId": "00011001",
    "merchantId": "000000011",
    "transactionTime": 1671716528,
    "approvedAmount": {
        "total": 10,
        "currency": "EUR",
        "components": {
            "subtotal": 10
	}
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:349415:4615279989:YYYM:301672",
    },
    "processor": {
        "referenceNumber": "084615279640",
	      "authorizationCode": "349415",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "avsResponse": {
            "streetMatch": "Y",
            "postalCodeMatch": "Y"
        },
        "securityCodeResponse": "MATCHED"
        }
    }
   
}

Transaction initiated from Sub-store

In case you preferred to board all your sub-merchants in our Gateway and your stores have been setup properly, you do not need to include any additional details when initiating a transaction request from a sub-store. The Gateway will provide all necessary flagging according your sub-store configuration.

The following JSON document represents an example of a transaction request including minimal set of elements:

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": "10.00",
    "currency": "EUR"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "414746******0067",
      "securityCode": "XXX",
      "expiryDate": {
        "month": "08",
        "year": "29"
      }
    }