Update Merchant Payment Details

Operation to create or update a merchant's payment details.

PUT https://qnbalahli.test.gateway.mastercard.com/api/rest/version/45 / mso / {msoId} / merchant / {merchantId}

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

{msoId} Alphanumeric + additional characters REQUIRED

The identifier that uniquely identifies you on the gateway.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 16
{merchantId} Alphanumeric + 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: 36

Fields

apiOperation String = UPDATE_MERCHANT_PAYMENT_DETAILS FIXED

Any sequence of zero or more unicode characters.

correlationId 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

Min length: 1 Max length: 100
merchant REQUIRED

The merchant's payment details.

merchant.cardMaskingFormat 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.

merchant.certificateSetId 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

Min length: 0 Max length: 50
merchant.currencyConversion 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.

merchant.currencyConversion.baseCurrency 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

Min length: 3 Max length: 3
merchant.currencyConversion.dccProviderAcquirerId 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

Min length: 3 Max length: 3
merchant.currencyConversion.dccProviderId Enumeration REQUIRED

DCC rate quote providers.

Value must be a member of the following list. The values are case sensitive.

FEXCO

FEXCO DCC provider.

TRAVELEX_CURRENCY_SELECT

Travelex DCC provider.

merchant.currencyConversion.dccProviderMerchantId 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

Min length: 1 Max length: 16
merchant.currencyConversion.dccRefundRate 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.

merchant.currencyConversion.disclosureRegion.visa 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

merchant.defaultOrderCertainty Enumeration OPTIONAL

Sets the value of order certainty assumed on a merchants orders where they do not specify one in the API request.If you do not specify this value, when updating a merchant profile for whom transactionMode is AUTH_CAPTURE, 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.

merchant.excessiveCaptureLimit 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.

Min value: 0 Max value: 2147483647
merchant.masterPassOnline OPTIONAL

Details regarding the merchant's MasterPass Online configuration.

merchant.masterPassOnline.checkoutIdentifier 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

Min length: 1 Max length: 255
merchant.masterPassOnline.collectShippingAddressAtMasterPassOnline 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'.

merchant.masterPassOnline.consumerKey String OPTIONAL

The consumer key value as issued by Masterpass for the merchant's production profile.

Data can consist of any characters

Min length: 97 Max length: 97
merchant.masterPassOnline.sandboxConsumerKey String OPTIONAL

The consumer key value as issued by Masterpass for the merchant's sandbox profile.

Data can consist of any characters

Min length: 97 Max length: 97
merchant.masterPassOnline.shippingLocationId 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

Min length: 1 Max length: 8
merchant.privilege[n] 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_LEVEL_2_ORDER_CREATION

Enables the merchant to create level 2 orders, i.e. provide level 2 specific data when creating an order.

BULK_CAPTURES

Enables the merchant to perform multiple captures using a single action in Merchant Administration.

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.

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_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.

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.

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.

REFUNDS

Enables the merchant to create refunds. A refund is the transfer of funds from a merchant to the payer's account.

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.

TXN_DOWNLOAD

Enables the merchant to download transaction level data in CSV format.

VIEW_SETTLEMENT_PAGES

Enables the merchant to view batch settlement details in Merchant Administration.

VIEW_UNMASKED_SENSITIVE_DATA

Enables the merchant to allow merchant operators to view unmasked sensitive data 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.

merchant.risk OPTIONAL

Details regarding the merchant's risk configuration.

merchant.risk.externalRisk OPTIONAL

Configuration details for the external risk profile

merchant.risk.externalRisk.assessmentInitiation 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.

merchant.risk.externalRisk.enableRiskScoring 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.

merchant.risk.externalRisk.gatekeeper OPTIONAL

Configuration details for the GateKeeper profile

merchant.risk.externalRisk.gatekeeper.defaultActionWhenUnableToRiskScore 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.

merchant.risk.externalRisk.gatekeeper.productionCredentials OPTIONAL

Credentials for the merchant's production profile used to access the GateKeeper scoring module.

merchant.risk.externalRisk.gatekeeper.productionCredentials.merchantId String OPTIONAL

The GateKeeper merchant ID used to identify the GateKeeper profile linked to this merchant profile.

Data can consist of any characters

Min length: 1 Max length: 36
merchant.risk.externalRisk.gatekeeper.serviceLevel 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.

merchant.risk.externalRisk.gatekeeper.supportRiskScoringFor 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.

merchant.risk.externalRisk.gatekeeper.testCredentials OPTIONAL

Credentials for the merchant's test profile used to access the GateKeeper scoring module.

merchant.risk.externalRisk.gatekeeper.testCredentials.merchantId String OPTIONAL

The GateKeeper merchant ID used to identify the GateKeeper profile linked to this merchant profile.

Data can consist of any characters

Min length: 1 Max length: 36
merchant.risk.externalRisk.interceptas OPTIONAL

Configuration details for the Interceptas profile

merchant.risk.externalRisk.interceptas.billingContact OPTIONAL
merchant.risk.externalRisk.interceptas.billingContact.email 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

merchant.risk.externalRisk.interceptas.billingContact.name String REQUIRED

The Interceptas tenant's billing contact name.

Data can consist of any characters

Min length: 1 Max length: 100
merchant.risk.externalRisk.interceptas.billingContact.phone String OPTIONAL

The Interceptas tenant's billing contact phone.

Data can consist of any characters

Min length: 1 Max length: 20
merchant.risk.externalRisk.interceptas.businessContact OPTIONAL
merchant.risk.externalRisk.interceptas.businessContact.email 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

merchant.risk.externalRisk.interceptas.businessContact.name String OPTIONAL

The Interceptas tenant's business contact name.

Data can consist of any characters

Min length: 1 Max length: 100
merchant.risk.externalRisk.interceptas.businessContact.phone String OPTIONAL

The Interceptas tenant's business contact phone.

Data can consist of any characters

Min length: 1 Max length: 20
merchant.risk.externalRisk.interceptas.businessType 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.

merchant.risk.externalRisk.interceptas.currency 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

Min length: 3 Max length: 3
merchant.risk.externalRisk.interceptas.defaultActionWhenUnableToRiskScore 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.

merchant.risk.externalRisk.interceptas.locale 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

Min length: 2 Max length: 5
merchant.risk.externalRisk.interceptas.productionCredentials OPTIONAL

Credentials for the merchant's production profile used to access the Interceptas scoring module.

merchant.risk.externalRisk.interceptas.productionCredentials.password String OPTIONAL

The password used to authenticate this merchant profile on the Interceptas scoring module.

Data can consist of any characters

Min length: 1 Max length: 32
merchant.risk.externalRisk.interceptas.productionCredentials.scoringUrl 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.

merchant.risk.externalRisk.interceptas.productionCredentials.tenantId String OPTIONAL

The tenant ID used to identify the Interceptas tenant linked to this merchant profile.

Data can consist of any characters

Min length: 1 Max length: 36
merchant.risk.externalRisk.interceptas.productionCredentials.userName String OPTIONAL

The user name used to identify this merchant profile on the Interceptas scoring module.

Data can consist of any characters

Min length: 1 Max length: 256
merchant.risk.externalRisk.interceptas.serviceLevel 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.

merchant.risk.externalRisk.interceptas.supportRiskScoringFor 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.

merchant.risk.externalRisk.interceptas.technicalContact OPTIONAL
merchant.risk.externalRisk.interceptas.technicalContact.email 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

merchant.risk.externalRisk.interceptas.technicalContact.name String REQUIRED

The Interceptas tenant's technical contact name.

Data can consist of any characters

Min length: 1 Max length: 100
merchant.risk.externalRisk.interceptas.technicalContact.phone String OPTIONAL

The Interceptas tenant's technical contact phone.

Data can consist of any characters

Min length: 1 Max length: 20
merchant.risk.externalRisk.interceptas.testCredentials OPTIONAL

Credentials for the merchant's test profile used to access the Interceptas scoring module.

merchant.risk.externalRisk.interceptas.testCredentials.password String OPTIONAL

The password used to authenticate this merchant profile on the Interceptas scoring module.

Data can consist of any characters

Min length: 1 Max length: 32
merchant.risk.externalRisk.interceptas.testCredentials.scoringUrl 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.

merchant.risk.externalRisk.interceptas.testCredentials.tenantId String OPTIONAL

The tenant ID used to identify the Interceptas tenant linked to this merchant profile.

Data can consist of any characters

Min length: 1 Max length: 36
merchant.risk.externalRisk.interceptas.testCredentials.userName String OPTIONAL

The user name used to identify this merchant profile on the Interceptas scoring module.

Data can consist of any characters

Min length: 1 Max length: 256
merchant.risk.externalRisk.interceptas.timeZone 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

Min length: 1 Max length: 40
merchant.risk.externalRisk.profileId 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

Min length: 1 Max length: 150
merchant.risk.externalRisk.providerId 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
merchant.risk.privilege[n] 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.

merchant.service[n] Enumeration OPTIONAL

Defined which services are enabled for the merchant.

Services listed in the request are enabled.

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_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_INTERNAL_RISK

Enables the merchant to use the internal risk management module to risk assess transactions performed through the gateway.

ENABLE_MASTERPASS_ONLINE

Enables the merchant to use the MasterPass Online digital wallet to collect the payer's payment details.

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_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'.

merchant.systemCapturedCardMaskingFormat 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.

merchant.tokenization OPTIONAL

Configuration details for the Tokenization functionality

merchant.tokenization.tokenRepository OPTIONAL

Details regarding the token repository configuration.

merchant.tokenization.tokenRepository.tokenGeneration 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.

merchant.tokenization.tokenRepository.tokenManagementStrategy 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_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.

merchant.tokenization.tokenRepositoryId 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

Min length: 1 Max length: 16
merchant.tokenization.verificationStrategy 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.

merchant.transactionMode Enumeration REQUIRED

Defines the merchants transaction mode, i.e. if the funds are immediately requested to be moved from the payer's account or the payment is authorized only and the funds will be moved/captured later.

Value must be a member of the following list. The values are case sensitive.

AUTH_CAPTURE

The payment is authorized only (AUTHORIZATION transaction). The merchant must submit a Capture request to move the funds from the payer's account to the merchant's account.

PURCHASE

The payment happens immediately (PURCHASE transaction). The funds are immediately moved from the payer's account to the merchant's account.

Response

Fields

correlationId 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

Min length: 1 Max length: 100
result 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

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause 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.

error.explanation 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

Min length: 1 Max length: 1000
error.field 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

Min length: 1 Max length: 100
error.supportCode 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

Min length: 1 Max length: 100
error.validationType 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.

result 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.

Resources

Glossary FAQs