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.