Payment Options Inquiry

Request to retrieve the payment options you can present to the payer, for example, the available payment methods and card types.

The returned options depend on your merchant profile configuration in the gateway and your input.For example, when you provide the order currency in the request, the response only contains payment options that are available for orders with this currency.

If you do not provide any input parameters, all values that could apply for all fields are returned: all of the possible card types, all of the possible currencies, and so on.

Depending on your configuration and the input parameters the response may also contain

  • a rate quote for Dynamic Currency Conversion.
  • the applicable Surcharge for the order.
  • the applicable Payment Plan Offers for the cart or the order.

Usage Note

You may not need to use this operation if your merchant profile configuration rarely changes and therefore the available payment options can be hard-coded into your website.

However, the operation will allow you to build the presentation and input validation for your checkout process in a dynamic way. As you are collecting more details from the payer during the checkout process, the operation tells you what fields to collect and what validation to apply.

If you have a simple configuration (for example, only accept a list of card types for s single currency), you can use the unmodified data set returned if the request is called without any input parameters for building the website's presentation and input validation.

If you have a more complex configuration (for example, accept USD and EUR currencies on Mastercard and Visa, but only USD on American Express), call the operation with parameters to restrict the returned values. For example:

  • If a sourceOfFunds.provided.card.prefix is passed in, only currencies applicable to the card brand identified based on this prefix are returned.
  • If an order.currency is passed in, only payment options applicable for that currency are returned.

Warning This operation must not be called directly from the browser, as it would expose your API integration password.

POST https://anzegate.gateway.mastercard.com/api/rest/version/70 / merchant / {merchantId} / paymentOptionsInquiry

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request

URL Parameters

{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: 40

Fields

To view the optional fields, please toggle on the "Show optional fields" setting.

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
gatewayEntryPoint Enumeration OPTIONAL

The interface through which the transaction is submitted to the gateway.

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

AUTO

The transaction was automatically generated by the gateway. For example, a Capture transaction for Auto-Capture or an order reversal transaction for risk rejected orders.

BATCH

The transaction was submitted as part of a merchant batch. Batches can either be uploaded via Batch or via Merchant Administration.

CHECKOUT_VIA_PAYMENT_LINK

The transaction was created via checkout. The payer was redirected to checkout by clicking on a payment link.

CHECKOUT_VIA_WEBSITE

The transaction was created via checkout. The payer was redirected from your website to checkout.

MERCHANT_ADMINISTRATION

The transaction was initiated in Merchant Administration.

MERCHANT_MANAGER

The transaction was initiated in Merchant Manager.

SERVICE_PROVIDER_API

The transaction was reported by an acquirer or alternate payment provider.

WEB_SERVICES_API

The transaction was submitted via Web Services API.

lineOfBusiness String OPTIONAL

Your payment service provider might have configured your merchant profile to support several lines of business.

Each line of business can have different payment parameters, such as bank account, supported cards or such.

For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.

Data can consist of any characters except space

Min length: 1 Max length: 100
locale String OPTIONAL

A language identifier or IETF language tag to control the language of the payment interaction with the payer (e.g. en_US, es, fr-CA).

By default, the language is determined from your configuration. Supply a value for this field only if you wish to override the default behavior. If the language you specify is not supported by the gateway, the payment is displayed in the best matching language.

See Dynamic Currency Conversion for more detail.

Data must be a language identifier or IETF language tag

Min length: 2 Max length: 5
paymentPlanProduct OPTIONAL

Information about the payment plan products for which payment plan offers are provided.

paymentPlanProduct.id Alphanumeric + additional characters OPTIONAL

An identifier to uniquely identify the payment plan product in the gateway.

The identifier for the payment plan.
See Payment Plans for the supported payment plans and their identifiers.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 60
session.id ASCII Text OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.

Values provided in the request will override values contained in the session.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version ASCII Text OPTIONAL

Use this field to implement optimistic locking of the session content.

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.

If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.

See Making Business Decisions Based on Session Content.

Data consists of ASCII characters

Min length: 10 Max length: 10
transactionSource Enumeration OPTIONAL

Indicates the channel through which you received authorization for the payment for this order from the payer.

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT. You only need to provide transaction.source if you want to override the default value configured for your acquirer link.

Note:

  • You can only override the default value if you have the requisite permission.
  • The value you provide must match one of those configured by your payment service provider.
  • You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.

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

CARD_PRESENT

Transaction where the card is presented to the merchant.

INTERNET

Transaction conducted over the Internet.

MOTO

Transaction received by mail or telephone.

Response

Fields

custom JSON Text CONDITIONAL

Provides additional data relevant to the options available for processing a payment.

If applicable, your payment service provider will describe how to use this data.

Data is valid Json Format

Min length: 1 Max length: 4000
gatewayEntryPoint Enumeration CONDITIONAL

The interface through which the transaction is submitted to the gateway.

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

AUTO

The transaction was automatically generated by the gateway. For example, a Capture transaction for Auto-Capture or an order reversal transaction for risk rejected orders.

BATCH

The transaction was submitted as part of a merchant batch. Batches can either be uploaded via Batch or via Merchant Administration.

CHECKOUT_VIA_PAYMENT_LINK

The transaction was created via checkout. The payer was redirected to checkout by clicking on a payment link.

CHECKOUT_VIA_WEBSITE

The transaction was created via checkout. The payer was redirected from your website to checkout.

MERCHANT_ADMINISTRATION

The transaction was initiated in Merchant Administration.

MERCHANT_MANAGER

The transaction was initiated in Merchant Manager.

SERVICE_PROVIDER_API

The transaction was reported by an acquirer or alternate payment provider.

WEB_SERVICES_API

The transaction was submitted via Web Services API.

merchant Alphanumeric + additional characters ALWAYS PROVIDED

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: 40
paymentPlanProduct CONDITIONAL

Information about the payment plan products for which payment plan offers are provided.

paymentPlanProduct.{paymentPlanProductId}.logoUrl URI CONDITIONAL

The URL of the logo for the payment plan product.

Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The following schemes are forbidden : javascript

paymentPlanProduct.{paymentPlanProductId}.name String CONDITIONAL

The display name of the payment plan product.

Data can consist of any characters

Min length: 1 Max length: 60
paymentPlanProduct.{paymentPlanProductId} Alphanumeric + additional characters CONDITIONAL

An identifier to uniquely identify the payment plan product in the gateway.

The identifier for the payment plan.
See Payment Plans for the supported payment plans and their identifiers.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 60
result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the transaction/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

supportedPaymentOperations[n] CONDITIONAL

Information on the supported payment operations available to the merchant.

supportedPaymentOperations[n].supportedPaymentOperation Enumeration ALWAYS PROVIDED

The list of supported payment operations available to the merchant.

For example, AUTHORIZE, PURCHASE.

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

AUTHORIZE

Merchant has privilege to perform Authorizations.

PURCHASE

Merchant has privilege to perform Purchases

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.