Update Merchant Payment Details
Operation to create or update a merchant's payment details.
Authentication
This operation requires authentication via one of the following methods:
- Certificate authentication.
-
Basic HTTP authentication as described at
w3.org.
Provide 'MSO.
<your gateway MSO ID>
' in the userid portion and your API password in the password portion.
Request
URL Parameters
Alphanumeric + additional characters
REQUIRED
The identifier that uniquely identifies you or an MSO that has authorized you to use this operation on their behalf.
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
Min length: 1 Max length: 16Alphanumeric + additional characters
REQUIRED
The unique identifier issued to you by your payment provider.
This identifier can be up to 12 characters in length.
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
Min length: 1 Max length: 36Fields
String
= UPDATE_MERCHANT_PAYMENT_DETAILS
FIXED
Any sequence of zero or more unicode characters.
String
OPTIONAL
A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Data can consist of any characters
REQUIRED
The merchant's payment details.
Enumeration
REQUIRED
The card number masking format applied by the gateway when the merchant supplied the card number.
This format will be used for transactions originating from Web Services API and Merchant Administration.
Formats for masking card numbers.
Value must be a member of the following list. The values are case sensitive.
DISPLAY_0_4
Display last 4 digits of Card Number.
DISPLAY_6_3
Display first 6 and last 3 digits of Card Number.
DISPLAY_6_4
Display first 6 and last 4 digits of Card Number.
DISPLAY_FULL
Display Full Card Number.
DISPLAY_NONE
Display No Card Number.
String
OPTIONAL
The Certificate Set ID is a unique identifier that you have assigned to uniquely identify a merchant's test and production SSL certificates.
Provide this field if the merchant will use SSL certificates to authenticate to the gateway when using the API. If not provided, the merchant will be enabled for Password Authentication.
If your customer has multiple gateway merchant profiles, then they can share the same Certificate Set. In this case, provide the same Certificate Set ID for each of their gateway merchant profiles.
You can create Certificate Sets for your merchants from the Merchant Manager UI.
Data can consist of any characters
OPTIONAL
Configuration details to enable the Dynamic Currency Conversion (DCC) service.
DCC enables merchants to accept payments from payers in their currency, which can differ from the merchant's currency for the order.
Upper case alphabetic text
OPTIONAL
The base currency registered for the merchant ID at the DCC provider.
The value must be expressed as an ISO 4217 alpha code.
Data must consist of the characters A-Z
Alpha
OPTIONAL
The identifier for the acquirer the merchant has registered with the DCC provider.
Data may consist of the characters a-z, A-Z
Enumeration
REQUIRED
DCC rate quote providers.
Value must be a member of the following list. The values are case sensitive.
FEXCO
FEXCO DCC provider.
FTT
FTT Global DCC provider.
GLOBAL_PAYMENTS
GLOBAL_PAYMENTS DCC provider.
IBM
IBM DCC provider.
TRAVELEX_CURRENCY_SELECT
Travelex DCC provider.
UNICREDIT
UNICREDIT DCC provider.
Alphanumeric
OPTIONAL
The unique identifier for the merchant account at the DCC provider.
Data may consist of the characters 0-9, a-z, A-Z
Enumeration
REQUIRED
The currency conversion rate that will apply to a refund transaction executed against an exiting order.
The currency conversion rate that will apply to a refund transaction executed against an existing order.
Value must be a member of the following list. The values are case sensitive.
CURRENT
A new rate quote is being requested to provide the actual rate at the refund transaction date.
HISTORICAL
The rate used when the order was created.
Enumeration
REQUIRED
Specifies the Visa disclosure region for the merchant.
This determines the Dynamic Currency Conversion offer and receipt texts presented to the payer.
Value must be a member of the following list. The values are case sensitive.
EUROPE
The Visa disclosure rules for Europe
INTERNATIONAL
The Visa disclosure rules for the International region
OPTIONAL
Use this parameter group to enable and configure a merchant for debt repayments.
Enumeration
OPTIONAL
To enable the merchant for debt repayments you must provide at least one funding method for which debt repayments are allowed.
When submitting a debt repayment the merchant must indicate on the transaction request that it is for a debt repayment and may have to provide additional information about the payment recipient. Where the gateway is unable to detect the funding method (UNKNOWN) for a transactions request, the gateway will always reject the transaction if it is a debt repayment.
Value must be a member of the following list. The values are case sensitive.
CREDIT
Debt transactions can be processed using Credit Card.
DEBIT
Debt transactions can be processed using Debit Card.
CHARGE
Debt transactions can be processed using Charge Card.
Enumeration
OPTIONAL
Sets the default value used for order certainty when the merchant does not provide a value on the API request.If you do not specify this value it will be set to FINAL.
Value must be a member of the following list. The values are case sensitive.
ESTIMATED
Merchant's orders will be assumed to have an order certainty of ESTIMATED where none is specified in WS-API requests.
FINAL
Merchant's orders will be assumed to have an order certainty of FINAL where none is specified in WS-API requests.
Integer
OPTIONAL
Defines the excess amount permitted to be captured on the original authorized amount, as a percentage.
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
OPTIONAL
Details regarding the merchant's MasterPass Online configuration.
Alphanumeric
REQUIRED
A unique identifier for the merchant in the MasterPass Online system, issued by MasterPass Online when boarding the merchant.
Data may consist of the characters 0-9, a-z, A-Z
Boolean
OPTIONAL
If enabled, the payer's shipping address is collected at MasterPass Online and returned to the merchant in the transaction response
JSON boolean values 'true' or 'false'.
String
OPTIONAL
The consumer key value as issued by Masterpass for the merchant's production profile.
Data can consist of any characters
String
OPTIONAL
The consumer key value as issued by Masterpass for the merchant's sandbox profile.
Data can consist of any characters
Alphanumeric
OPTIONAL
The shipping location defines which countries the merchant ships to and restricts the customer's shipping address selection in MasterPass Online accordingly.
If provided, this shipping location applies for all MasterPass Online transactions. If not provided, MasterPass Online uses the preferred shipping profile configured against the merchant's MasterPass Online profile.
Data may consist of the characters 0-9, a-z, A-Z
OPTIONAL
String
OPTIONAL
The configuration that will be applied to this merchant for the 'Tax and Product Details' section on the Order Entry page in Merchant Administration.
Data can consist of any characters
Enumeration
OPTIONAL
Defines which privileges are enabled for the merchant.
Privileges listed in the request are enabled for the merchant.
Value must be a member of the following list. The values are case sensitive.
ALLOW_ACQUIRER_TRACE_ID
Enables the merchant to provide Trace ID in the API request. Trace id is the unique identifier that allows issuer to link related transactions.
ALLOW_LEVEL_2_ORDER_CREATION
Enables the merchant to create level 2 orders, i.e. provide level 2 specific data when creating an order.
AMEX_SAFEKEY_2
May perform 3DS 2.0 American Express SafeKey authentications.
AUTHORIZATIONS
Enables the merchant to perform authorizations.
AUTO_AUTH_REVERSAL_ON_EXPIRY
The gateway will automatically reverse any outstanding Authorization amounts where an Authorization has expired.
AUTO_AUTH_REVERSAL_ON_PARTIAL_CAPTURE
Where the merchant indicates on a Partial Capture transaction that it is the last Capture they are intending to submit against the Authorization, the gateway will automatically reverse the outstanding Authorization amount.
AVS_TRANSACTION_FILTERING_RULES_OVERRIDE
Enables the merchant to submit a transaction request with Transaction Filtering rules for AVS response codes that override the ones configured for all of their transactions.
BULK_CAPTURES
Enables the merchant to perform multiple captures using a single action in Merchant Administration.
BYPASS_AUTHENTICATION_CAPABILITY_VALIDATION
The gateway rejects financial transaction requests with payer authentication data if the acquirer integration does not have support for this data. If you enable this privilege, the gateway will instead process the financial transaction (i.e. ignore the authentication data).
BYPASS_CARD_CHANGE_FOR_AGREEMENT_VALIDATION
The gateway ensures that when the card used for a recurring, installment, unscheduled or other agreement changes, the merchant must submit a customer-initiated payment. Where this privilege is enabled, this validation is not applied for this merchant.
BYPASS_UNUSUAL_TRANSACTION_PROTECTION
The gateway's Unusual Transaction Protection Service helps to protect merchants from processing unusual transactions. If you decide to opt out from the Unusual Transaction Protection Service, this protection will not be applied and the number of unauthorized excessive transactions (and other similar occurrences) processed by the merchant may increase. By opting out of the Unusual Transaction Protection Service, you accept and agree that you are solely responsible for this increased risk, including any increased charges the merchant may incur in relation to the processing of excessive or unusual transactions.
CAPTURES
Enables the merchant to perform captures.
CARD_ON_FILE
Enables the Merchant to indicate whether the card is stored on file by default.
CARTE_BANCAIRE_3DS2
May perform 3DS 2.0 Carte Bancaire authentications.
CASH_ADVANCE
Enables the merchant to submit Cash Advance transactions.
CHANGE_MERCHANT_TRANSACTION_SOURCE
Enables the merchant to provide the source of the transaction when creating the transaction. If not enabled or not provided by the merchant, the gateway automatically assigns the default transaction source.
CHANGE_ORDER_CERTAINTY
Enables the merchant to make use of a value of order certainty other than their configured default (see defaultOrderCertainty) by supplying it in WS-API requests or in the Create Order UI.
CHANGE_TRANSACTION_FREQUENCY
Enables the merchant to change the frequency of a transaction. Note: Values set for transaction frequency only apply if the merchant uses version 53 and lower of the API.
CREDIT_CARD_BILL_PAYMENTS
Enables the merchant to submit credit card bill payments that disburse funds to the recipient's credit card account.
ENABLE_REFUND_REQUESTS
Enables an operator to request approval for a refund transaction. The refund transaction is not submitted to the acquirer.
ENFORCE_CARD_NUMBER_MASKING_FOR_INPUT
Enforces card masking when entering a payer's card number in Merchant Administration.
ENFORCE_GATEWAY_TOKEN_FOR_CARD_STORED_ON_FILE_TRANSACTIONS
Where enabled, the gateway will enforce the use of gateway tokens for all transactions that indicate that stored card details are used.
ENFORCE_REFUNDS_WITHOUT_AUTHORIZATIONS
Where supported by the acquirer, the gateway attempts to submit an Authorization to the issuer before submitting the Refund to the acquirer. When this privilege is enabled, the gateway will not attempt to submit an Authorization for the Refund.
ENFORCE_UNIQUE_MERCHANT_TRANSACTION_REFERENCE
Enforces a unique Merchant Transaction Reference for every transaction submitted by the merchant. Transactions without a unique Merchant Transaction Reference are rejected by the gateway.
ENFORCE_UNIQUE_ORDER_REFERENCE
Enforces a unique Order Reference across all orders submitted by the merchant. Transactions without a uniqueOrder Reference are rejected by the gateway.
EXCESSIVE_REFUNDS
Enables the merchant to perform refunds for amounts greater than the authorized amount.
GAMING_WINNINGS_PAYMENTS
Enables the merchant to submit transactions that disburse gaming winnings to the payer's account.
IDENTITY_CHECK_EXPRESS
Enables a merchant with privileges and configuration enabling them to use EMV 3DS to make use of SCA Delegation functionality, so that they can provide their customers a frictionless authentication process where they have already authenticated the customer using an approved authentication mechanism.
INSTANT_REFUNDS
Where supported by the acquirer, the gateway attempts to submit refunds for processing in near real time so that the money will instantly be available in the payer's account.
MANUAL_BATCH_CLOSURE
Enables the merchant to manually trigger settlement for a batch in Merchant Administration or via the 'Close Batch' Web Services API operation.
MASTERCARD_INSTALLMENTS_ENHANCED_AUTHORIZATION_DATA
Enables the merchant to offer issuer Mastercard Installments (MCI) using enhanced authorization data. If enabled the gateway will ask the issuer for available offers. Where offers are available the merchant can then present them to the payer.
MOTO
Enables the merchant to manually create orders in Merchant Administration.
NO_CARDS_SUBMITTED_THROUGH_API_SAQ_A
Support merchant to meet SAQ-A obligation when using merchant user interfaces
NO_CARDS_SUBMITTED_THROUGH_UI_SAQ_A
Support merchant to meet SAQ-A obligation when using merchant user interfaces.
ORDER_DOWNLOAD
Enables the merchant to download order level data in CSV format.
PROCESS_AUTHORIZATION_AS_PURCHASE
May process Authorizations as Purchase
PSD2_EXEMPTIONS
Enables the merchant to claim an exemption from the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area. When enabled the merchant can indicate the type of exemption being claimed when using the Authenticate Payer operation or submitting an Authorize or Pay transaction request.
PURCHASES
Enables the merchant to perform purchases.
REFUNDS
Enables the merchant to create refunds. A refund is the transfer of funds from a merchant to the payer's account.
SECURECODE_2
May perform 3DS 2.0 MasterCard SecureCode authentications.
STANDALONE_CAPTURES
Enables the merchant to perform a capture without first performing an authorization. The merchant must perform the authorization externally, and provide the corresponding authorization code as input to the stand alone capture.
STANDALONE_REFUNDS
Enables the merchant to perform a refund without first creating an order (with a capture or purchase).
STATEMENT_DESCRIPTOR
Enables the merchant to print their contact information on payer's account statements.
SURCHARGE_RULES
Enables the merchant to configure rules for calculating surcharge amounts.
TXN_DOWNLOAD
Enables the merchant to download transaction level data in CSV format.
UPDATE_AUTHORIZATION
Enables the merchant to update an existing authorization, allowing to update the authorized amount or expand the validity period for the order.
VERIFIED_BY_VISA_2
May perform 3DS 2.0 Verified by Visa authentications.
VIEW_SETTLEMENT_PAGES
Enables the merchant to view batch settlement details in Merchant Administration.
VIEW_UNMASKED_ACCOUNT_IDENTIFIERS
Enables the merchant to allow merchant operators to view unmasked account identifiers in Merchant Administration.
VOIDS
Enables the merchant to void transactions. A void is the cancellation of a previous transaction. Voids can only be performed if the transaction is in an unreconciled batch and if the operation is supported by the acquirer.
OPTIONAL
Details regarding the merchant's risk configuration.
OPTIONAL
Configuration details for the external risk profile
Enumeration
OPTIONAL
Defines when the gateway sends the transaction to the external risk provider for risk scoring.
Value must be a member of the following list. The values are case sensitive.
AFTER_TRANSACTION_PROCESSING
The request includes relevant data elements from the merchant's transaction request, a globally unique transaction identifier, a risk assessment identifier generated by the payment gateway together with relevant transaction response data from the Acquirer. AVS and CSC results are available for risk assessment.
BEFORE_TRANSACTION_PROCESSING
The request includes relevant data elements from the merchant's transaction request, a globally unique transaction identifier, and a risk assessment identifier generated by the payment gateway. No AVS, CSC or other Acquirer response data is available. Please note that, if you select external risk only (i.e. not internal risk) and "May Use Verification Only for AVS/CSC Risk Assessment" then "Before transaction processing" is not a valid option. This is because the only reason to use the Verification Only transaction is to obtain AVS and CVC results for use in risk assessment. If the risk assessment decision has already been made then performing the Verification Only transaction is an additional and unnecessary action.
Enumeration
OPTIONAL
The risk scoring status for the external risk provider.
Value must be a member of the following list. The values are case sensitive.
TEST_AND_PRODUCTION
The external risk provider will assess both test and live transactions for risk scoring.
TEST_ONLY
The external risk provider will assess only test transactions for risk scoring.
OPTIONAL
Configuration details for the GateKeeper profile
Enumeration
OPTIONAL
Indicates the action to be taken when the gateway is unable to get risk scoring from GateKeeper, for example, due to connectivity issues.
Value must be a member of the following list. The values are case sensitive.
ACCEPT_NOT_CHECKED
The gateway allows the order to progress and risk assessment will not be performed. The risk recommendation for the order will be set to "Not Checked".
REVIEW
The merchant must review the order and accept or reject the order.
OPTIONAL
Credentials for the merchant's production profile used to access the GateKeeper scoring module.
String
OPTIONAL
The GateKeeper merchant ID used to identify the GateKeeper profile linked to this merchant profile.
Data can consist of any characters
Enumeration
OPTIONAL
Indicates if the gateway should submit the merchant ID for the merchant's gateway profile to Gatekeeper when submitting transactions for risk assessment.
If selected, this will apply to all gateway merchant profiles configured to use this Gatekeeper profile.
Value must be a member of the following list. The values are case sensitive.
DO_NOT_SEND
Do not send the merchant ID for the merchant's gateway profile to Gatekeeper when submitting transactions for risk assessment.
SEND
Send the merchant ID for the merchant's gateway profile to Gatekeeper when submitting transactions for risk assessment.
Enumeration
OPTIONAL
The service level offering that the Merchant has signed up to with GateKeeper.
Value must be a member of the following list. The values are case sensitive.
GOLD
The Gold service level.
Enumeration
OPTIONAL
A GateKeeper Profile can support risk scoring for one or many Merchant Profiles. An organisation with multiple Merchant Profiles may use a single GateKeeper Profile to minimise risk management overheads and to leverage their collective experience of trading with customers. However, if the Merchant Profiles have significantly different business models such as different typical order values or customer purchase patterns, consideration should be given to setting up separate GateKeeper Profiles.
Value must be a member of the following list. The values are case sensitive.
MULTIPLE_MERCHANT_PROFILES
The profile supports being assigned to multiple merchants.
SINGLE_MERCHANT_PROFILE
The profile only supports being assigned to a single merchant.
OPTIONAL
Credentials for the merchant's test profile used to access the GateKeeper scoring module.
String
OPTIONAL
The GateKeeper merchant ID used to identify the GateKeeper profile linked to this merchant profile.
Data can consist of any characters
OPTIONAL
Configuration details for the Interceptas profile
OPTIONAL
Email
OPTIONAL
The Interceptas tenant's billing contact email.
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
String
REQUIRED
The Interceptas tenant's billing contact name.
Data can consist of any characters
String
OPTIONAL
The Interceptas tenant's billing contact phone.
Data can consist of any characters
OPTIONAL
Email
OPTIONAL
The Interceptas tenant's business contact email.
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
String
OPTIONAL
The Interceptas tenant's business contact name.
Data can consist of any characters
String
OPTIONAL
The Interceptas tenant's business contact phone.
Data can consist of any characters
Enumeration
OPTIONAL
This identifies the type of business that your Merchant is in and influences the risk assessment that will be performed by Interceptas.
Value must be a member of the following list. The values are case sensitive.
AIRLINE_TRAVEL_AGENT
Airline/Travel Agent.
RETAILER_OF_DIGITAL_GOODS
Retailer of digital goods.
RETAILER_OF_PHYSICAL_GOODS
Retailer of physical goods.
Upper case alphabetic text
OPTIONAL
Currency is used by Interceptas to define the risk rules (e.g. average order size).
Any transactions submitted to Interceptas using a different currency will be converted to the corresponding value in the base currency before being risk assessed. The value must be expressed as an ISO 4217 alpha code.
Data must consist of the characters A-Z
Enumeration
OPTIONAL
Indicates the action to be taken when the gateway is unable to get risk scoring from Interceptas, for example, due to connectivity issues. For a merchant with the service level "Bronze", the only valid option is "Accept - Not Checked" as the merchant cannot perform a review.
Value must be a member of the following list. The values are case sensitive.
ACCEPT_NOT_CHECKED
The gateway allows the order to progress and risk assessment will not be performed. The risk recommendation for the order will be set to "Not Checked".
REVIEW
The merchant must review the order and accept or reject the order.
String
OPTIONAL
The default language which will be used when users sign into Interceptas.
The value must be provided in the format '<Language>_<Country>', e.g. 'en_US'. <Language> must be a two-letter language code according to ISO 639-1. <Country> must be a two-letter country code according to ISO 3166-1 alpha-2.
Data can consist of any characters
OPTIONAL
Credentials for the merchant's production profile used to access the Interceptas scoring module.
String
OPTIONAL
The password used to authenticate this merchant profile on the Interceptas scoring module.
Data can consist of any characters
Url
OPTIONAL
The Interceptas URL to which the payment gateway sends the risk scoring request.
Ensure that the URL begins with 'https' and is longer than 11 characters.
String
OPTIONAL
The tenant ID used to identify the Interceptas tenant linked to this merchant profile.
Data can consist of any characters
String
OPTIONAL
The user name used to identify this merchant profile on the Interceptas scoring module.
Data can consist of any characters
Enumeration
OPTIONAL
The service level offering that the Merchant has signed up to with Accertify.
Value must be a member of the following list. The values are case sensitive.
BRONZE
The Bronze service level.
GOLD
The Gold service level.
SILVER
The Silver service level.
Enumeration
OPTIONAL
An Interceptas Tenant can support risk scoring for one or many Merchant Profiles. An organisation with multiple Merchant Profiles may use a single Interceptas Tenant to minimise risk management overheads and to leverage their collective experience of trading with customers. However, if the Merchant Profiles have significantly different business models such as different typical order values or customer purchase patterns, consideration should be given to setting up separate Interceptas Tenants.
Value must be a member of the following list. The values are case sensitive.
MULTIPLE_MERCHANT_PROFILES
The tenant supports being assigned to multiple merchants.
SINGLE_MERCHANT_PROFILE
The tenant only supports being assigned to a single merchant.
OPTIONAL
Email
OPTIONAL
The Interceptas tenant's technical contact email.
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
String
REQUIRED
The Interceptas tenant's technical contact name.
Data can consist of any characters
String
OPTIONAL
The Interceptas tenant's technical contact phone.
Data can consist of any characters
OPTIONAL
Credentials for the merchant's test profile used to access the Interceptas scoring module.
String
OPTIONAL
The password used to authenticate this merchant profile on the Interceptas scoring module.
Data can consist of any characters
Url
OPTIONAL
The Interceptas URL to which the payment gateway sends the risk scoring request.
Ensure that the URL begins with 'https' and is longer than 11 characters.
String
OPTIONAL
The tenant ID used to identify the Interceptas tenant linked to this merchant profile.
Data can consist of any characters
String
OPTIONAL
The user name used to identify this merchant profile on the Interceptas scoring module.
Data can consist of any characters
String
OPTIONAL
The default timezone which will be used when users sign into Interceptas.
The value must be provided in the form '<Continent>/<City>', e.g. 'America/New_York'. For a complete list of timezones please refer to http://twiki.org/cgi-bin/xtra/tzdatepick.html.
Data can consist of any characters
String
OPTIONAL
The unique identifier for this external risk profile.
When using an existing profile this must be the profile name as defined at the external risk provider. When creating a new profile, the name cannot be subsequently updated and should indicate the merchant or merchant group assigned.
Data can consist of any characters
Enumeration
OPTIONAL
The unique identifier for this external risk provider issued by the gateway.
Merchant Boarding API supported external risk providers
Value must be a member of the following list. The values are case sensitive.
GATEKEEPER
INTERCEPTAS
NUDETECT
Enumeration
OPTIONAL
Risk management privileges assigned to the merchant.
Value must be a member of the following list. The values are case sensitive.
RISK_VERIFY_ONLY
Allows the gateway to submit a Verification Only transaction to the acquirer to obtain the AVS and CSC results for use in risk assessment. This avoids having to perform the financial transaction before risk assessment and the need to release the hold on cardholder funds in the event the transaction is rejected due to risk assessment.
SYSTEM_REFUND
Allows the gateway to refund against an order if risk assessment rejects the order after the financial transaction has successfully been performed. This privilege is required only, if the Refunds privilege is not enabled.
OPTIONAL
Configuration details for the transaction risk management functionality for the merchant.
The transaction risk management functionality ensures that the merchant's transactions are submitted to the Risk Service Provider for risk assessment and blocked if they are identified as fraudulent.
Only provide the fields in this parameter group if you want to override the default configuration for the transaction risk management functionality that you have configured in Merchant Manager on the 'Risk Management - Transaction Risk Management' page.
To apply the default configuration to the merchant, do not include this parameter group.
Enumeration
OPTIONAL
Determines if the transaction is submitted to the Risk Service Provider for risk assessment before or after being submitted to the acquirer for processing.
You must provide this field if the request contains merchant.risk.transactionRiskManagement.status=ENABLED.
Value must be a member of the following list. The values are case sensitive.
AFTER_TRANSACTION_PROCESSING
Transactions will be submitted to the Risk Service Provider for risk assessment before being submitted to the acquirer for processing.
BEFORE_TRANSACTION_PROCESSING
Transactions will be submitted to the Risk Service Provider for risk assessment after being submitted to the acquirer for processing. The gateway will be able to include acquirer response details in the risk assessment request to the Risk Service Provider.
Enumeration
REQUIRED
Determines if the transaction risk management functionality should be applied to the merchant's transaction requests.
If you provide this field you are overriding the default configuration for the transaction risk management functionality that you have configured in Merchant Manager on the 'Risk Management - Transaction Risk Management' page.
Value must be a member of the following list. The values are case sensitive.
DISABLED
The transaction risk management functionality is disabled for the merchant.
ENABLED
The transaction risk management functionality is enabled for the merchant.
Enumeration
OPTIONAL
A gateway feature that you can enable for a merchant.
Use this field to enable a service on this merchant profile.
Note: the options available to you are determined by your gateway configuration and in addition to the rules defined by the merchant themselves.
Value must be a member of the following list. The values are case sensitive.
ENABLE_AMEX_EXPRESS_CHECKOUT
Enables the merchant to use the Amex Express Checkout digital wallet to collect the payer's payment details.
ENABLE_BATCH
Enables the merchant to integrate with the gateway via the Batch API. The Authentication mode is set to 'Password Authentication'.
ENABLE_CHECKOUT
Enables the merchant to collect the payer's payment details using a Hosted Checkout.
ENABLE_DECRYPT_APPLE_PAY
Enables the merchant to present Apple Pay payment tokens.
ENABLE_DECRYPT_GOOGLE_PAY
Enables the merchant to present Google Pay payment tokens.
ENABLE_DECRYPT_SAMSUNG_PAY
Enables the merchant to present Samsung Pay payment tokens.
ENABLE_DEVICE_PAYMENTS
Enables the merchant to use supported device payment methods such as Apple Pay, Android Pay or Samsung Pay.
ENABLE_HOSTED_PAYMENT_FORM
Enables the merchant to collect the payer's payment details through their own payment form while submitting them directly from the payer's browser to the gateway.
ENABLE_MASTERPASS_ONLINE
Enables the merchant to use the MasterPass Online digital wallet to collect the payer's payment details.
ENABLE_MSO_CONFIGURED_TRANSACTION_FILTERING
Enables you to configure transaction filtering rules for this merchant. If you enable this service, you should also configure the rules you want to apply in the merchant.transactionFiltering parameter group.
ENABLE_NOTIFICATIONS
Enables the merchant to configure merchant email notifications as well as customer email notifications.
ENABLE_PAYMENTS_WITHOUT_AUTHENTICATION
Enables the merchant to process payments without any merchant authentication.
ENABLE_REPORTING_API
Enables the merchant to integrate with the gateway via the Reporting API.
ENABLE_SUBGATEWAY_PROCESSING
Enables the merchant to act as a subgateway. A subgateway can submit requests to the gateway on behalf of their client merchants to access gateway services. Client merchants of the subgateway do not need merchant profiles created on the gateway.
ENABLE_VISA_CHECKOUT
Enables the merchant to use the Visa Checkout digital wallet to collect the payer's payment details.
ENABLE_WEB_SERVICES_API
Enables the merchant to integrate with the gateway via the Web Services API. The Authentication mode is set to 'Password Authentication'.
OPTIONAL
Information about a merchant you have enabled to act as a subgateway.
These fields only apply if you have set ENABLE_SUBGATEWAY_PROCESSING in the merchant.service[n] field.
Use these fields to provide information so that our gateway can process requests submitted by this merchant on behalf of their client merchants.
String
OPTIONAL
This lets you limit the scope of this subgateway to the client merchants that they own.
The gateway will only process requests from this subgateway merchant that have a acquirer.merchantId value that is in this list.
The acquirer.merchantId is the Bank Merchant ID/SE Number/account name or such issued by this acquirer. You can specify a comma-separated list of either:
- • merchant ids, or
- • a dash separated range (inclusive) of merchant ids.
- kddfg\-x, eam1340-eam1343,a8-a11,009-011,x y
- kddfg-x, eam1340, eam1341, eam1342, eam1343, a8, a9, a10, a11, 009, 010, 011, x y
Data can consist of any characters
Enumeration
REQUIRED
The card number masking format applied by the gateway when the card number was supplied by the customer rather than the merchant.
This format will be used for transactions originating from Hosted Payment Form integrations.
Formats for masking card numbers.
Value must be a member of the following list. The values are case sensitive.
DISPLAY_0_4
Display last 4 digits of Card Number.
DISPLAY_6_3
Display first 6 and last 3 digits of Card Number.
DISPLAY_6_4
Display first 6 and last 4 digits of Card Number.
DISPLAY_FULL
Display Full Card Number.
DISPLAY_NONE
Display No Card Number.
OPTIONAL
Configuration details for the Tokenization functionality
Enumeration
OPTIONAL
Enable the use of AETS scheme tokens from the selected token repository for this merchant.
Where enabled, the gateway will use the scheme token (rather than the actual card details) stored against the gateway token when processing a request with this gateway token. Tokenization of card details with AETS requires additional configuration on the merchant.tokenization.tokenRepository.schemeTokenization.aets group.
Value must be a member of the following list. The values are case sensitive.
ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
Enable use of network tokens for the production as well as the test merchant profile.
ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
Enable use of network tokens for the test merchant profile only.
Enumeration
OPTIONAL
Enable the use of MDES scheme tokens from the selected token repository for this merchant.
Where enabled, the gateway will use the scheme token (rather than the actual card details) stored against the gateway token when processing a request with this gateway token. Tokenization of card details with MDES requires additional configuration on the merchant.tokenization.tokenRepository.schemeTokenization.mdes group.
Value must be a member of the following list. The values are case sensitive.
ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
Enable use of network tokens for the production as well as the test merchant profile.
ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
Enable use of network tokens for the test merchant profile only.
Boolean
OPTIONAL
The Token Maintenance Service attempts to ensure that the card details stored against a token are current thereby increasing the likelihood of successfully processing a recurring payment that uses the token.
The Token Maintenance Service uses the Account Updater functionality. Therefore the Account Updater functionality must be enabled for at least one Merchant-Acquirer-Link for the merchant. Only tokens with payment details for which requests would be processed via such a Merchant-Acquirer-Link can be updated.
JSON boolean values 'true' or 'false'.
OPTIONAL
Details regarding the token repository configuration.
OPTIONAL
Provide the merchant credentials for accessing a scheme tokenization service provider such as Mastercard Digital Enablement Service (MDES).
Where provided, the gateway will perform scheme tokenization for gateway tokens (that contain card details).
OPTIONAL
Configuration details for the American Express Tokenization Service (AETS).
String
REQUIRED
An identifier assigned by American Express Token Service (AETS) for authentication to the service.
The merchant can find the Client ID value in the AETS Dashboard.
Data can consist of any characters
Base64
REQUIRED
A key provided by American Express Token Service (AETS) for authentication to the service.
The merchant can find the Client Secret value in the AETS Dashboard.
Data is Base64 encoded
Base64
REQUIRED
A static 256-bit AES encryption key provided by American Express Token Service (AETS) for encrypting cardholder account data sent to the service, and decrypting token data returned by the service.
The merchant can find the Encryption Key value on the AETS Dashboard.
Data is Base64 encoded
String
REQUIRED
The identifier of the static 256-bit AES encryption key provided by American Express Token Service (AETS).
This is used to identify the static AES key in the encrypted cardholder account data sent to the service and in the encrypted token data returned by the service. The merchant can find the Encryption Key ID value on the AETS Dashboard.
Data can consist of any characters
String
REQUIRED
A unique identifier assigned to a merchant by American Express Token Service (AETS).
This identifier will be used for all merchants using this token repository.
Once configured, it cannot be updated. A new token repository would have to be assigned to the merchant.
Data can consist of any characters
OPTIONAL
Configuration details for the Mastercard Digital Enablement Service (MDES).
String
REQUIRED
A unique identifier assigned to a merchant by Mastercard Digital Enablement Service (MDES).
This identifier will be used for all merchants using this token repository.
Once configured, it cannot be updated. A new token repository would have to be assigned to the merchant.
Data can consist of any characters
OPTIONAL
Configuration details for the Visa Token Service (VTS).
String
REQUIRED
A unique identifier assigned to the merchant by Visa Token Service (VTS).
This identifier is used to identify the merchant in requests submitted by the gateway to VTS.
Note that the same identifier will be used for all merchants using this token repository.
Once configured, the value cannot be updated.
Data can consist of any characters
String
REQUIRED
A unique identifier assigned to a merchant by Visa Token Service (VTS).
This identifier will be used for all merchants using this token repository.
Once configured, it cannot be updated. A new token repository would have to be assigned to the merchant.
Data can consist of any characters
Enumeration
OPTIONAL
Defines the strategy used to generate a token.
Mandatory, if repository must be created.
Value must be a member of the following list. The values are case sensitive.
MERCHANT_SUPPLIED
Tokens are supplied by the merchant. Any merchant supplied token is validated to not be a valid card number.
PRESERVE_6_4
Tokens are generated preserving the first 6 and last 4 digits of the account identifier, e.g. card number. The remaining digits are randomized, and the token is guaranteed to fail a Luhn (Mod-10) check so that it does not create a valid card number.
RANDOM_WITH_LUHN
Tokens are generated as random numbers. It starts with a '9' (so that is does not create a valid card number) and passes a Luhn (Mod-10) check.
Enumeration
OPTIONAL
Defines how tokens within the repository are managed by the gateway.
Mandatory, if repository must be created.
Value must be a member of the following list. The values are case sensitive.
UNIQUE_ACCOUNT_IDENTIFIER
A single token is assigned against an account identifier, defines as a one-to-one relationship between the account identifier and the token. An attempt to store the account identifier against another token will result in an error.
UNIQUE_TOKEN
A unique token is assigned every time an account identifier is saved in the token repository, defining a one-to-many relationship between an account identifier and the token.
ASCII Text
OPTIONAL
Unique identifier of the token repository.
Token repositories can be shared across merchants; however, a single merchant can be associated with only one token repository at a given time. Every token repository has a corresponding test token repository, which only the merchants with the corresponding test profiles can access. For example, if the repository ID is ABC, the test repository ID will be TestABC. Hence, the system displays an error if you specify a repository ID that starts with 'Test'
Data consists of ASCII characters
Enumeration
OPTIONAL
The type of verification performed by the gateway for payment details stored against a token repository for this merchant.
Value must be a member of the following list. The values are case sensitive.
ACQUIRER
The gateway performs a Web Services API Verify request. Depending on the payment type, you may need to provide additional details to enable the submission of a Verify request.
BASIC
The gateway validates the format of the payment details. For cards it also validates that the card number falls within a valid BIN range. For ACH payment details it also validates the check digit for the routing number
NONE
The gateway does not perform any verification.
Enumeration
OPTIONAL
Enable the use of VTS scheme tokens from the selected token repository for this merchant.
Where enabled, the gateway will use the scheme token (rather than the actual card details) stored against the gateway token when processing a request with this gateway token. Tokenization of card details with VTS requires additional configuration. This configuration is currently only available in Merchant Manager.
Value must be a member of the following list. The values are case sensitive.
ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
Enable use of network tokens for the production as well as the test merchant profile.
ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
Enable use of network tokens for the test merchant profile only.
OPTIONAL
Configuration of transaction filtering rules that apply to transactions processed by this merchant.
You only need to set this if you want to define rules for this merchant, in addition to those that you have configured to apply to all of your merchants, and in addition to the rules defined by the merchant themselves.
The gateway complies with all configured rules when determining if a transaction should be processed.
OPTIONAL
Transaction filtering rules based on the results of 3-D Secure payer authentication.
These rules enable the gateway to reject or mark transactions for review, based on rules you can configure.
You only need to use this parameter group if you want to specify rules to apply to this merchant and therefore override any global filtering rules you have set.
You can set values for only one of customFilter, managedFilters, or noFilter. If you provide none of these values, the gateway will apply any global filtering rules that you have specified.
String
OPTIONAL
The name of the 3DS1 custom rule set that you want to apply to this merchant's transactions.
Use this field if the managed rules provided by the gateway are not suitable. Note: You must first provide the gateway with your custom rule set using the MSO UI.
Data can consist of any characters
String
OPTIONAL
The name of the 3DS2 custom rule set that you want to apply to this merchant's transactions.
Use this field if the managed rules provided by the gateway are not suitable. Note: You must first provide the gateway with your custom rule set using the MSO UI.
Data can consist of any characters
OPTIONAL
This group lets you select filtering rules managed by the gateway.
If you use this, then you must select at least one field in this parameter group.
Boolean
OPTIONAL
Block e-commerce transactions where 3-D Secure authentication of the payer has not been attempted.
That is, a directory server lookup was not attempted, or an 'Enrolled' response was not followed by an ACS interaction.
JSON boolean values 'true' or 'false'.
Boolean
OPTIONAL
Block e-commerce transactions where 3-D Secure authentication of the payer has not resulted in liability shift to the issuer.
JSON boolean values 'true' or 'false'.
Boolean
OPTIONAL
Block e-commerce transactions where the cardholder has not been successfully authenticated with 3-D Secure.
JSON boolean values 'true' or 'false'.
Boolean
OPTIONAL
Block e-commerce transactions based on the gateway's evaluation of the 3-D Secure authentication results against recommendations for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
Based on this assessment, the transaction will be blocked or processed as fully authenticated, authentication attempted, or as an unauthenticated transaction.
JSON boolean values 'true' or 'false'.
Boolean
OPTIONAL
No 3-D Secure filtering is applied to the merchant's transactions.
Use this option when you have configured global 3-D Secure filters that apply to all of your merchants and do not want that filtering to apply to this merchant.
JSON boolean values 'true' or 'false'.
OPTIONAL
Transaction filtering rules based on card BIN ranges.Block transactions for this merchant where the BIN for the card number is in this range.
Note that you can either configure a set of BIN ranges for which requests will be blocked (blacklist)or a set of BIN ranges for which requests will be allowed (whitelist), but not both.
When defining a blacklist, all requests with card numbers outside the defined BIN ranges are allowed.When defining a whitelist, all requests with card numbers outside the defined BIN ranges will be blocked.
Integer
OPTIONAL
The last BIN of the BIN range you want blocked.
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
Integer
REQUIRED
The first BIN of the BIN range you want blocked.
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
OPTIONAL
Transaction filtering rules for IP addresses.
Transactions originating from an IP address in these ranges will be blocked.
IpAddress
OPTIONAL
The last IP address of an IP address range to be blocked, in nnn.nnn.nnn.nnn format.
Ensure that the IpAddress is in the format n.n.n.n, where each n is in the range of 0 to 255
IpAddress
REQUIRED
The first IP address of an IP address range to be blocked, in nnn.nnn.nnn.nnn format.
Ensure that the IpAddress is in the format n.n.n.n, where each n is in the range of 0 to 255
Enumeration
OPTIONAL
Block transactions based on the absence of the Card Security Code (CSC) or the response from the card issuer.
Value must be a member of the following list. The values are case sensitive.
REJECT_CSC_NOT_PRESENT_ON_CARD
Rejects transactions where the merchant has indicated that CSC is not present on the card.
REJECT_ISSUER_NOT_CERTIFIED
Rejects transactions for which the issuer is not certified for CSC processing.
REJECT_NOT_PROCESSED
Rejects transactions where the CSC is not processed.
REJECT_NO_CSC_MATCH
Rejects transactions where the CSC submitted is invalid or does not match the one associated with the card.
Boolean
OPTIONAL
Enable Dynamic 3-D Secure Authentication for this merchant.
The merchant can only be enabled for this functionality if they are configured for at least one 3-D Secure authentication scheme and also configured to use an external risk provider (merchant.risk parameter group).
JSON boolean values 'true' or 'false'.
OPTIONAL
Transaction filtering rules for countries based on IP address.
Transactions originating from IP addresses associated with the countries you specify will be blocked. You can also choose to block transactions from unidentified countries or anonymous proxy servers.
Boolean
OPTIONAL
Block transactions originating from anonymous proxy servers.
Do not set to 'false' if merchant.transactionFiltering.ipCountry.rejectCountry is populated.
JSON boolean values 'true' or 'false'.
Alpha
OPTIONAL
Block transactions originating from IP addresses associated with this country.
Provide the 3 character ISO 3166-1 alpha-3 country code of the country to be blocked.
Data may consist of the characters a-z, A-Z
Boolean
OPTIONAL
Block transactions from IP addresses when the gateway cannot identify the country from which it originated.
Do not set to 'false' if merchant.transactionFiltering.ipCountry.rejectCountry is populated.
JSON boolean values 'true' or 'false'.
OPTIONAL
Transaction filtering rules based on card BIN ranges.Allow transactions for this merchant where the BIN for the card number is in this range.
Note that you can either configure a set of BIN ranges for which requests will be blocked (blacklist)or a set of BIN ranges for which requests will be allowed (whitelist), but not both.
When defining a blacklist, all but requests with card numbers within the defined BIN ranges are allowed.When defining a whitelist, all but requests with card numbers within the defined BIN ranges will be blocked.
Integer
OPTIONAL
The last BIN of the BIN range you want whitelisted.
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
Integer
REQUIRED
The first BIN of the BIN range you want whitelisted.
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
Response
Fields
String
CONDITIONAL
A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Data can consist of any characters
Enumeration
ALWAYS PROVIDED
A system-generated high level overall result of the operation.
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown
Errors
Information on possible error conditions that may occur while processing an operation using the API.
Enumeration
Broadly categorizes the cause of the error.
For example, errors may occur due to invalid requests or internal system failures.
Value must be a member of the following list. The values are case sensitive.
INVALID_REQUEST
The request was rejected because it did not conform to the API protocol.
REQUEST_REJECTED
The request was rejected due to security reasons such as firewall rules, expired certificate, etc.
SERVER_BUSY
The server did not have enough resources to process the request at the moment.
SERVER_FAILED
There was an internal system failure.
String
Textual description of the error based on the cause.
This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Data can consist of any characters
String
Indicates the name of the field that failed validation.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Data can consist of any characters
String
Indicates the code that helps the support team to quickly identify the exact cause of the error.
This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
Data can consist of any characters
Enumeration
Indicates the type of field validation error.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Value must be a member of the following list. The values are case sensitive.
INVALID
The request contained a field with a value that did not pass validation.
MISSING
The request was missing a mandatory field.
UNSUPPORTED
The request contained a field that is unsupported.
Enumeration
A system-generated high level overall result of the operation.
Value must be a member of the following list. The values are case sensitive.
ERROR
The operation resulted in an error and hence cannot be processed.