Payment facilitator model
Payment facilitator model
The payment facilitator model is used to clarify sub-merchant information and clearly identify the payment facilitator’s sub-merchants that may be participating in a transaction. This helps strengthening fraud monitoring and authorization screening, and provides clarity about transactions both for acquirers and cardholders.
To support this model and obtain more transparency, all of the following additional request parameters are required to be sent to the acquirer by the payment facilitators as part of the transaction details, except for subMerchantState
which is only required if subMerchantCountry
code is US
or CA
.
Parameter | Within fingerprint | Data type | Short description |
---|---|---|---|
subMerchantId |
Required if used. |
Alphanumeric with special characters and a variable length of up to 15 characters. |
Unique ID of sub-merchant. |
subMerchantName |
Required if used. |
Alphanumeric with special characters and a variable length of up to 22 characters. |
Name of sub-merchant. |
subMerchantCountry |
Required if used. |
Alphanumeric with a fixed length of 2 characters. |
Country code of sub-merchant. |
subMerchantState |
Required if used. |
Alphabetic with a variable length of up to 3 characters. |
State of sub-merchant. |
subMerchantCity |
Required if used. |
Alphanumeric with a variable length of up to 13 characters. |
City of sub-merchant. |
subMerchantStreet |
Required if used. |
Alphanumeric with a variable length of up to 38 characters. |
Street name of sub-merchant. |
subMerchantZipCode |
Required if used. |
Alphanumeric with a variable length of up to 10 characters. |
Zip code of sub-merchant. |
Contact our support teams for enabling these additional request parameters for your merchant account.
For the back-end operations deposit, refund and recurPayment the required order when computing the fingerprint is: subMerchantId
, subMerchantName
, subMerchantStreet
, subMerchantCity
, subMerchantState
, subMerchantCountry
and subMerchantZipCode
.
Error messages
If your merchant account is configured as payment facilitator account, you need to send the additional sub-merchant data as part of the transaction details otherwise the transaction will be rejected and appropriate error messages will be returned.
The following error messages are sent if the above mentioned parameters are not transmitted in the request:
-
SUBMERCHANT_ID is missing.
-
SUBMERCHANT_NAME is missing.
-
SUBMERCHANT_COUNTRY is missing.
-
SUBMERCHANT_STREET is missing.
-
SUBMERCHANT_ZIP_CODE is missing.
-
SUBMERCHANT_CITY is missing.
-
SUBMERCHANT_STATE is missing.
The following error messages are sent if the transmitted request parameters do not have the correct length:
-
SUBMERCHANT_ID has an invalid length.
-
SUBMERCHANT_NAME has an invalid length.
-
SUBMERCHANT_COUNTRY has an invalid length.
-
SUBMERCHANT_STREET has an invalid length.
-
SUBMERCHANT_ZIP_CODE has an invalid length.
-
SUBMERCHANT_CITY has an invalid length.
The following error messages are sent if the contents of the above mentioned parameters is not correct:
-
SUBMERCHANT_ID is invalid.
-
SUBMERCHANT_NAME is invalid.
-
SUBMERCHANT_COUNTRY is invalid.
-
SUBMERCHANT_STREET is invalid.
-
SUBMERCHANT_ZIP_CODE is invalid.
-
SUBMERCHANT_CITY is invalid.