- Integration Guidelines
- Implementing a Merchant Boarding API Integration
- Create or Update Merchant
Create or Update Merchant
It allows you to create or update a merchant account and set merchants' general details, add or update configuration for an acquirer link used by the merchant for payment processing, and add or update payment configuration details for an existing merchant.
- The general details include merchant details (for example, merchant id, merchant name, locale), contact details (for example, address, phone numbers), and the password for the merchant administrator of the merchant account.
- A merchant can be configured for one or more acquirer links, where each acquirer link must have a unique identifier provided in the
acquirerlLink.idfield. Multiple acquirer links can be added or updated in a single API call. - The payment details include details about how a merchant will transact (Authorize, Pay, or both), the supported transactions (for example, Verification Only, Refund, Standalone Capture transactions), and the associated privileges. It also allows you to enable or disable and configure services offered by the MasterCard Payment Gateway such as DirectAPI, Reporting, Hosted Payment Session, Batch, Tokenization, Transaction Filtering, and Risk Management.
Merchant General Details
The general details include merchant details (for example, merchant id, merchant name, locale), contact details (for example, address, phone numbers), and the password for the merchant Administrator of the merchant account.
When you create a merchant account, the gateway creates a merchant administrator user. This user has limited privileges. To allow the merchant to perform detailed configuration or use Merchant Administration to perform transactions, the merchant administrator must create a new merchant operator with the requisite privileges.
Assigning a Merchant to a Merchant Organization
A Merchant Organization (MO) allows you to effectively manage your gateway merchant profiles, and organize them into a structure of your choice, for example, your corporate structure. For more information on MOs, see Implementing a Merchant Organization API Integration.
To assign a merchant to an MO, provide the merchant.merchantOrganization[n] field in the Create or Update Merchant request. You can assign one or more parent MOs to a merchant; however, ensure that the MOs you assign are owned by you.
Update Merchant API Reference[REST][NVP]
Merchant Payment Details
The payment details include details about how a merchant will transact (Authorize, Pay or both), the supported transactions (for example, Verification Only, Refund, Standalone Capture transactions) and the associated privileges. It also allows you to enable/disable and configure services offered by the Payment Gateway such as Direct API, Reporting API, Hosted Payment Form, Batch, Transaction Vault, Transaction Filtering and Risk Management.
Enabling/Disabling Gateway Transaction Vault
Gateway Tokenization allows merchants to store payment details in a secured environment in exchange for a token. This is useful to merchants as they do not have to comply with all of the restrictions and regulations associated with storing sensitive payment data on their system and it reduces their PCI-compliance obligations. The token can be used in place of payment details in transaction requests to the gateway. Further, if the payment details are stored into a token as part of a customer registration or account creation process, the token may be used when the payer returns to make another purchase.
You can enable Gateway Tokenization by providing a token repository ID in the Update Merchant Payment Details request. If you want to disable Transaction Vault after enabling it, exclude the token repository ID from the request. For more details, see Gateway Tokenization Information.
Enabling/Disabling Network Tokenization
Network tokenization, also known as Scheme Tokenization, allows merchants to securely replace the payer's primary Account Number (PAN) with a network token generated by network tokenization service providers such as Mastercard Digital Enablement Service (MDES). You, on behalf of your merchant can request for both new and existing account PANs on file to be tokenized and each PAN to be replaced with a unique network token (subject to issuer participation in the network tokenization service and the enabled card account ranges). The Authorization/Pay request initiated by merchants will attempt to use the network token if available, else the Funding PAN (FPAN) stored against the gateway token will be used.
To use Network Tokenization, you must be first enabled for Gateway Tokenization.
You can enable network tokenization for a scheme by providing fields specific to the network tokenization provider in the Create or Update Merchant request. To disable it after enabling it, exclude these fields from the request. For more details, see Network Tokenization Information.
Enabling/Disabling Transaction Filtering
Transaction Filtering enables the gateway to reject or mark transactions for review based on simple rules. You can configure rules per merchant and/or rules that apply to all merchants (via Merchant Manager). Merchants can configure rules themselves via Merchant Administration. If any individual rule fails, the gateway will reject the transaction or mark it for review and the order will not be allowed to proceed. See Transaction Filtering Rules Information for details on how to use Create or Update Merchant to configure rules for a merchant.
Enabling/Disabling External Risk Providers
You can enable an external risk provider for a merchant to risk assess their transactions performed through the gateway.
The gateway currently supports the following risk providers: Accertify Interceptas, GateKeeper, NuDetect. For more information, see Risk Management.
Enabling/Disabling Dynamic Currency Conversion (DCC)
DCC services enable merchants to accept payments in the currencies of their order from payers whose currencies are different. See Enabling Dynamic Currency Conversion for how to enable DCC.
If you want to disable DCC after enabling it, exclude all DCC-related fields from a request.
Enabling/Disabling Masterpass
Masterpass is a digital wallet provider that allows payers to store their payment details such as card details, billing and shipping address in a secure server. When paying online the payer can simply log onto Masterpass and select the stored payment details, saving the payer from having to provide their payment details every time they pay online.
You can enable Masterpass for your merchant by providing an checkout identifier in the Create or Update Merchant or request. If you want to disable Masterpass after enabling it, exclude the checkout identifier from the request.
Update Merchant Payment Details API Reference[REST][NVP]
Merchant Acquirer Link
A merchant can be configured for one or more acquirer links where each acquirer link must have a unique identifier provided in the merchant.acquirerlLink.id field. You must use separate API calls to create or update each link.
You can set merchantAcquirerLink.status to Disabled to prevent the merchant from performing transactions using this acquirer link.
Acquirer Information
Depending on the acquirer, you may be required to include or exclude some of the fields, or provide additional fields specific to this acquirer in the Create or Update Merchant request. Key points to note:
- The fields specific to an acquirer are contained in the
merchant.acquirerLink.{id}.acquirergroup. For example, fields that are specific to the acquirer 'PayPal' are grouped undermerchant.acquirerLink.{id}.acquirer.paypal. - The fields that are not specific to an acquirer may be mandatory, optional, or not applicable, depending on the acquirer. For example, for the acquirer 'giropay', the field
merchant.acquirerLink.cardTypesis not applicable as this acquirer is used for online bank transfer. - The valid values for a field differ based on the acquirer. For example, for the acquirer 'TSYS', Euro (EUR) is not a valid currency.
Contact the gateway to access these details for the acquirers you wish to configure. Building this information into your integration will enable you to provide valid values for the relevant fields in the Update Merchant Acquirer link request.
Exclusion Rules Information
You can configure exclusion rules that define the type of cards that can be processed through the merchant-acquirer link. These rules can be based on the funding method and the issuer country of the payer's card. You can set up the exclusion rules for the merchant-acquirer link based on the business requirements of the merchant or MSO. The funding methods that are supported for the exclusion rules are credit, debit, charge, and unknown. You can specify all countries or selective countries while configuring the exclusion rules for a merchant.
The parameter group merchant.acquirerLink.{id}.exclusionRules[n] allows you to specify different fields based on card type, funding method, and country of issuance of the payer's card. You can use the following fields when you configure the exclusion rules.
merchant.acquirerLink.{id}.exclusionRules[n].cardTypes: Allows you to define the list of supported card types for the merchant acquirer link for which the exclusion rules to be applied If you do not provide this field or you provide the field without entering the card type, the exclusion rule will apply to all cards.merchant.acquirerLink.{id}.exclusionRules[n].fundingMethods: Allows you to define the list of supported card types for the merchant-acquirer link for which the exclusion rule should be applied. If you do not provide this field the exclusion rule will apply to all cards.merchant.acquirerLink.{id}.exclusionRules[n].issuerCountries: Allows you to define the list of issuer countries for which the exclusion rule should be applied. You need to provide the three-letter country code as per the ISO 3166 alpha-3 standards.merchant.acquirerLink.{id}.exclusionRules[n].excludedIssuerCountries: Allows you to define the list of issuer countries that you want to exclude from the exclusion rule. You need to provide the three-letter country code as per the ISO 3166-1 alpha -3 standards.merchant.acquirerLink.{id}.exclusionRules[n].unknownIssuerCountry: Allows you to define the action taken by the gateway when the gateway is unable to determine the issuer country of the payer's card.
For example,if you want to exclude transactions for all debit cards issued in Canada, provide the field values as merchant.acquirerLink.{id}.exclusionRules[n].fundingMethods=[DEBIT]
and merchant.acquirerLink.{id}.exclusionRules[n].issuerCountries=[CAN]. For more information on how to use these parameters, see merchant.acquirerLink.{id}.exclusionRules[n] under the Create or Update Merchant API Reference tab.
Payment Plan Information
You can enable payment plans supported by the gateway and the acquirer on a merchant acquirer link by providing the plan ID and the configuration details of the payment plan. See Payment Plan Information to retrieve the plan ID for the payment plan you wish to configure for the merchant.
3-D Secure Scheme Information
You can enable 3-D Secure schemes supported by Payment Gateway and the acquirer on a merchant acquirer link by providing the credentials and the configuration details for the scheme. Note that if you provide credentials for a 3-D Secure scheme for one of the acquirer links, then you must provide details on all the acquirer links configured for the merchant else you will not be able to approve the merchant.