Shopping Options Inquiry
Request to retrieve shopping options available to the payer.
Multi-Currency Pricing
If you are configured with a Multi-Currency Pricing (MCP) service provider, the response includes the foreign exchange rate quotes.
This allows you to display prices in your online store and process payments in the payer's preferred currency using guaranteed rates.
Rate quotes are provided for all payer currencies you are configured for at your MCP service provider.
Payment Plan Offers
If you are configured with a payment plan service provider, the response includes all payment plan offers. Only generic offers, i.e. offers that are not specific to an item or the content of a cart, are provided.
Authentication Copied to clipboard
This operation requires authentication via one of the following methods:
- Certificate authentication.
-
To authenticate to the API two additional NVP parameters must be supplied in the request.
Provide 'merchant.
<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.
Request Copied to clipboard
Fields Copied to clipboard
String
= SHOPPING_OPTIONS_INQUIRY
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
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, '-', '_'
Upper case alphabetic text
REQUIRED
The currency that your Multi-Currency Pricing service provider will use for settlement to your account.
This is also the currency in which you price your inventory, expressed as an ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
Upper case alphabetic text
OPTIONAL
The currency in which you are displaying prices to your payer.
If not provided, the value is defaulted to the currency provided in field merchantCurrency.
Payment plan offers will be provided in this currency.
Provide the ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
Container for fields that control the response returned for the request.
Enumeration
OPTIONAL
Indicates if you wish the gateway to return details of Foreign Exchange (FX) rate quotes from your Multi-Currency Pricing service provider in the service provider's format.
If you set this value to INCLUDE, the full response data from the service provider will be returned in multiCurrencyPricing.providerResponseData.
If you do not specify this value it will be set to EXCLUDE.
Value must be a member of the following list. The values are case sensitive.
EXCLUDE
Exclude the full response data from the service provider.
INCLUDE
Include the full response data from the service provider.
Response Copied to clipboard
Fields Copied to clipboard
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
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, '-', '_'
Upper case alphabetic text
ALWAYS PROVIDED
The currency that your Multi-Currency Pricing service provider will use for settlement to your account.
This is also the currency in which you price your inventory, expressed as an ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
Information about Foreign Exchange (FX) rates provided by your Multi-Currency Pricing service provider.
Upper case alphabetic text
ALWAYS PROVIDED
The currency that your Multi-Currency Pricing service provider will use for settlement to your account.
This is also the currency in which you price your inventory, expressed as an ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
Alphanumeric
ALWAYS PROVIDED
The Multi-Currency Pricing service provider's unique reference for a set of Foreign Exchange (FX) rate quotes.
You can use this value if you are talking to your provider about a rate quote.
When submitting a SHOPPING_OPTIONS_INQUIRY request, you can get the full rate quote response data returned by the MCP service provider by setting the responseControls.mcpSourceData to INCLUDE.
Data may consist of the characters 0-9, a-z, A-Z
JSON Text
CONDITIONAL
The full rate quote response data returned by your Multi-Currency Pricing service provider.
If you wish to return this data, then set responseControls.mcpResponseData to INCLUDE.
Data is valid Json Format
Details of the Foreign Exchange (FX) currencies and rates available for your specified multiCurrencyPricing.merchantCurrency.
A rate will be provided for each payer currency and tenor for which you have been configured by your Multi-Currency Pricing service provider.
For example, if your merchant currency is USD, and you are configured for GBP and AUD payer currencies for both SP (spot) and 1W (1 week) tenors, then you will receive four quotes: GBP/SP, GBP/1W, AUD/SP, AUD/1W.
Decimal
ALWAYS PROVIDED
The Foreign Exchange (FX) rate quoted.
To convert amounts in your merchant currency to an amount in the payer's currency, multiply by this rate.
For example, if multiCurrencyPricing.merchantCurrency is USD, multiCurrencyPricing.quote[[n].payerCurrency is GBP, and the fxRate is 0.7743, then 100 USD =77.43 GBP.
Note: it is your responsibility to round or truncate the foreign amount you calculate as appropriate for the currency and your needs. For example, if you calculated a payer amount for GBP of 77.4356, then you round it to no more than two decimal places (77.44). You could also choose to round it to say 77.50.
Whatever rule you chose, the amount that goes into your account will be determined by the payer amount that you provide in the payment transaction request.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Upper case alphabetic text
ALWAYS PROVIDED
A foreign currency you can present to the payer on your website.
If you use this quote, then it is also the currency you use for the payment transaction.
The currency is expressed as an ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
String
ALWAYS PROVIDED
Unique identifier for the Foreign Exchange (FX) rate quote for this payer currency and tenor.
You must provide this identifier in a payment transaction request (for example, AUTHORIZE or PAY) when you used this FX rate quote to calculate the payment amount.
Data can consist of any characters
Alphanumeric
ALWAYS PROVIDED
The period of time from the date of the deal (payment transaction) until the date it settles (value date).
For example, spot (SP), one week (1W), one month (1M).
These values are expressed in industry standard terms. For the majority of Multi-Currency Pricing cases, Spot (SP) tenor is used.
Data may consist of the characters 0-9, a-z, A-Z
DateTime
ALWAYS PROVIDED
The date and time when the Foreign Exchange (FX) rate quote expires.
After this time, your Multi-Currency Pricing (MCP) service provider might not guarantee the rate.
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
Upper case alphabetic text
CONDITIONAL
The currency in which you are displaying prices to your payer.
If not provided, the value is defaulted to the currency provided in field merchantCurrency.
Payment plan offers will be provided in this currency.
Provide the ISO 4217 alpha code, e.g. USD.
Data must consist of the characters A-Z
Details about the merchant payment plan offers that may be applicable to the merchant store.
Alphanumeric + additional characters
CONDITIONAL
The unique identifier for this payment plan offer.
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
If a cash award is offered, this parameter group contains the cash award amount and instructions on how the payer can claim the amount.
Decimal
CONDITIONAL
An amount offered to the payer if they accept this payment plan offer.
For example, the payer may receive a $50 cash award for accepting a payment plan offer that results in the payer paying a total of $1000 over 5 payments (including interest and fees), meaning that the total cost to the payer is actually $950.
Details about how the payer can claim this amount are provided in the paymentPlanOffer{id}.cashAward.payerInstructionText field.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
String
CONDITIONAL
Text that advises the payer how they can claim the reclaim amount.
You must display this text to the payer when presenting this payment plan offer.
The text may include a link to the payment plan service provider's website.
Data can consist of any characters
Upper case alphabetic text
ALWAYS PROVIDED
The currency the amounts for this payment plan offer are provided in.
Data must consist of the characters A-Z
Integer
CONDITIONAL
If the first payment for this payment plan offer is deferred, the field contains the number of months until the first payment is due.
A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)
Decimal
CONDITIONAL
The total amount of all fees that apply for this payment plan offer.
The fee amount is charged to the payer in addition to the interest rate.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Decimal
CONDITIONAL
The amount of the first payment for this payment plan offer.
The amount for all subsequent payments is provided in paymentPlanOffer{id}.subsequentPaymentAmount.
The amount is expressed as a decimal number in the units of the currency. For example 12.34 in USD is the amount 12 dollars and 34 cents.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Information about the interest that applies for this payment plan offer.
Decimal
CONDITIONAL
The discount amount applied to the interest amount.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Decimal
CONDITIONAL
The interest rate.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Decimal
CONDITIONAL
The payment plan offer is only applicable to orders with an amount below this amount.
Where the payment plan offer is only applicable if the order amount is within a defined range, the minimum amount is provided in field paymentPlanOffer{id}.minimumAmount.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Decimal
CONDITIONAL
The payment plan offer is only applicable to orders with an amount equal to or above this amount.
Where the payment plan offer is only applicable if the order amount is within a defined range, the maximum amount is provided in field paymentPlanOffer{id}.maximumAmount.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Integer
CONDITIONAL
The number of monthly payments to be made by the payer for this payment plan offer.
A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)
Alphanumeric + additional characters
ALWAYS PROVIDED
The unique identifier of the payment plan product for this payment plan offer.
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
Information about qualifiers for this payment plan offer.
For example, a qualifier can be
- • an issuing bank. In this case the offer is only applicable if the payer makes the payment with a card issued by this bank.
- • a membership type that the payer has with you. In this case the offer is only available if the payer has this type of membership with you.
You must display this information to the payer to help them understand if the payment plan offer is applicable to them.
String
CONDITIONAL
A short textual description of the qualifier.
Data can consist of any characters
URI
CONDITIONAL
The URL of the logo of the qualifier.
Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The URI must be one of the following schemes : https
Decimal
CONDITIONAL
The amount of each payment for this payment plan offer.
If the amount for the first payment differs, then the amount for the first payment is provided in paymentPlanOffer{id}.firstPaymentAmount.
The amount is expressed as a decimal number in the units of the currency. For example 12.34 in USD is the amount 12 dollars and 34 cents.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Decimal
CONDITIONAL
The total amount payable by the payer, including interest and any fees for this payment plan offer.
The amount is expressed as a decimal number in the units of the currency. For example 12.34 in USD is the amount 12 dollars and 34 cents.
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
Information about the payment plan products for which payment plan offers are provided.
URI
ALWAYS PROVIDED
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
String
ALWAYS PROVIDED
The display name of the payment plan product.
Data can consist of any characters
Alphanumeric + additional characters
ALWAYS PROVIDED
An identifier to uniquely identify the payment plan product in the gateway.
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
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, issuer or service provider.
SUCCESS
The operation was successfully processed
Errors Copied to clipboard
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.