Get payment products

GET https://{domainname}/v1/{merchantId}/products

Products

Products is your entry on all things related to payment products. You will be able to retrieve all relevant payment products, based on your configuration and provided filters, their associated fields and potential directories. You can retrieve all of the information in one call or do calls on individual payment products. The data returned is designed to give you all the required information to build up your interface towards your consumers in a dynamic fashion. By doing it like that you know that you will be ready for future changes and new payment products without much effort.

Request

By providing additional details on the transaction the list of payment products can be limited. This allows you to not have payment products returned that don't support recurring transactions when you are setting your user up for a recurring payment. To reduce the data that is returned even more you can have us hide certain elements from the response. This is done using the hide property and allows you to not have us return the list of fields associated with each of the payment products.

By submitting the locale you can benefit from the server side language packs if our application does not have this or if you are using the JavaScript SDK. Note however that the values returned will be based on our default language packs and not on any modifications that you might have made through the Configuration Center. Our iOS and Android SDKs have language packs included that allow you to manage them easily.

Query parameters

Query parameters for this method

Property	Type	Required	Repeat	Details
countryCode	string	yes	no	read close
close Description ISO 3166-1 alpha-2 country code
currencyCode	string	yes	no	read close
close Description Three-letter ISO currency code representing the currency for the amount
locale	string	no	no	read close
close Description Locale used in the GUI towards the consumer. Please make sure that a language pack is configured for the locale you are submitting. If you submit a locale that is not setup on your account we will use the default language pack for your account. You can easily upload additional language packs and set the default language pack in the Configuration Center.
amount	integer	no	no	read close
close Description Amount in cents and always having 2 decimals
isRecurring	boolean	no	no	read close
close Description This allows you to filter payment products based on their support for recurring or not true false If this is omitted all payment products are returned.
isInstallments	boolean	no	no	read close
close Description This allows you to filter payment products based on their support for installments or not true false If this is omitted all payment products are returned.
hide	string	no	yes	read close
close Description Allows you to hide elements from the response, reducing the amount of data that needs to be returned to your client. Possible options are: fields - Don't return any data on fields of the payment product accountsOnFile - Don't return any accounts on file data translations - Don't return any label texts associated with the payment products productsWithoutFields - Don't return products that require any additional data to be captured productsWithoutInstructions - Don't return products that show instructions productsWithRedirects - Don't return products that require a redirect to a 3rd party. Note that products that involve potential redirects related to 3D Secure authentication are not hidden

Request example

SDK: Ruby

This scenario you will probably use the most

query = Products::FindProductsParams.new
query.country_code = 'US'
query.currency_code = 'USD'
query.locale = 'en_US'
query.amount = 1000
query.is_recurring = true
query.is_installments = true
query.add_hide('fields')

response = client.v1.merchant('merchantId').products.find(query)

Responses

Please find below an overview of the possible responses.

Response 200 - OKPaymentProducts

The response contains an array of payment products that match the filters supplied in the request.

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
paymentProducts	array of object	no	read close
close Description Array containing payment products and their characteristics
items	object	no	read close
close SDK Object type PaymentProduct
accountsOnFile	array of object	no	read close
close Description List of tokens for that payment product
items	object	no	read close
close SDK Object type AccountOnFile
attributes	array of object	no	read close
close Description Array containing the details of the stored token
items	object	no	read close
close SDK Object type AccountOnFileAttribute
key	string	no	read close
close Description Name of the key or property
mustWriteReason	enum	no	read close
close Description The reason why the status is MUST_WRITE. Currently only "IN_THE_PAST" is possible as value (for expiry date), but this can be extended with new values in the future.
status	enum	no	read close
close Description Possible values: READ_ONLY - attribute cannot be updated and should be presented in that way to the user CAN_WRITE - attribute can be updated and should be presented as an editable field, for example an expiration date that will expire very soon MUST_WRITE - attribute should be updated and must be presented as an editable field, for example an expiration date that has already expired Any updated values that are entered for CAN_WRITE or MUST_WRITE will be used to update the values stored in the token.
value	string	no	read close
close Description Value of the key or property
displayHints	object	no	read close
close Description Object containing information for the client on how best to display this field SDK Object type AccountOnFileDisplayHints
labelTemplate	array of object	no	read close
close Description Array of attribute keys and their mask
items	object	no	read close
close SDK Object type LabelTemplateElement
attributeKey	string	no	read close
close Description Name of the attribute that is shown to the customer on selection pages or screens
mask	string	no	read close
close Description Regular mask for the attributeKey Note: The mask is optional as not every field has a mask
logo	string	no	read close
close Description Partial URL that you can reference for the image of this payment product. You can use our server-side resize functionality by appending '?size={{width}}x{{height}}' to the full URL, where width and height are specified in pixels. The resized image will always keep its correct aspect ratio.
id	integer	no	read close
close Description ID of the account on file record
paymentProductId	integer	no	read close
close Description Payment product identifier Please see payment products for a full overview of possible values.
acquirerCountry	string	no	read close
close Description ISO 3166-1 alpha-2 country code which indicates the most likely country code of the acquirer that will process the transaction. For Google Pay (paymentProductId 320) transactions this acquirerCountry is should be provided in the transactionInfo.countryCode for merchants that use an acquirer that is based in one of the European Economic Area (EEA) countries to make sure the transaction is compliant with the PSD2 Strong Customer Authentication (SCA) requirements. More information on Strong Customer Authentication compliance for Google Pay can be found at https://developers.google.com/pay/api/web/guides/resources/sca
allowsInstallments	boolean	no	read close
close Description Indicates if the product supports installments true - This payment supports installments false - This payment does not support installments
allowsRecurring	boolean	no	read close
close Description Indicates if the product supports recurring payments true - This payment product supports recurring payments false - This payment product does not support recurring transactions and can only be used for one-off payments
allowsTokenization	boolean	no	read close
close Description Indicates if the payment details can be tokenized for future re-use true - Payment details from payments done with this payment product can be tokenized for future re-use false - Payment details from payments done with this payment product can not be tokenized
authenticationIndicator	object	no	read close
close Description Indicates if the payment product supports 3D Security (mandatory, optional or not needed). SDK Object type AuthenticationIndicator
name	string	no	read close
close Description The name of the indicator as to how it is mapped in the response.
value	string	no	read close
close Description The value of the indicator as to how it is mapped in the response.
autoTokenized	boolean	no	read close
close Description Indicates if the payment details can be automatically tokenized for future re-use true - Payment details from payments done with this payment product can be automatically tokenized for future re-use false - Payment details from payments done with this payment product can not be automatically tokenized
canBeIframed	boolean	no	read close
close Description This property is only relevant for payment products that use third party redirects. This property indicates if the third party disallows their payment pages to be embedded in an iframe using the X-Frame-Options header. true - the third party allows their payment pages to be embedded in an iframe. false - the third party disallows their payment pages to be embedded in an iframe.
deviceFingerprintEnabled	boolean	no	read close
close Description Indicates if device fingerprint is enabled for the product true false
displayHints	object	no	read close
close Description Object containing display hints like the order in which the product should be shown, the name of the product and the logo SDK Object type PaymentProductDisplayHints
displayOrder	integer	no	read close
close Description Determines the order in which the payment products and groups should be shown (sorted ascending)
label	string	no	read close
close Description Name of the field based on the locale that was included in the request
logo	string	no	read close
close Description Partial URL that you can reference for the image of this payment product. You can use our server-side resize functionality by appending '?size={{width}}x{{height}}' to the full URL, where width and height are specified in pixels. The resized image will always keep its correct aspect ratio.
fields	array of object	no	read close
close Description Object containing all the fields and their details that are associated with this payment product. If you are not interested in the data in the fields you should have us filter them out (using filter=fields in the query-string)
items	object	no	read close
close SDK Object type PaymentProductField
dataRestrictions	object	no	read close
close Description Object containing data restrictions that apply to this field, like minimum and/or maximum length SDK Object type PaymentProductFieldDataRestrictions
isRequired	boolean	no	read close
close Description true - Indicates that this field is required false - Indicates that this field is optional
validators	object	no	read close
close Description Object containing the details of the validations on the field SDK Object type PaymentProductFieldValidators
boletoBancarioRequiredness	object	no	read close
close Description Indicates the requiredness of the field based on the fiscalnumber for Boleto Bancario SDK Object type BoletoBancarioRequirednessValidator
fiscalNumberLength	integer	no	read close
close Description When performing a payment with Boleto Bancario, some values are only required when the fiscalnumber has a specific length. The length the fiscalnumber has to have to make the field required is defined here. For example the CompanyName is required when the fiscalnumber is a CNPJ. The firstname and surname are required when the fiscalnumber is a CPF.
emailAddress	object	no	read close
close Description Indicates that the content should be validated against the rules for an email address SDK Object type EmptyValidator
expirationDate	object	no	read close
close Description Indicates that the content should be validated against the rules for an expiration date (it should be in the future) SDK Object type EmptyValidator
fixedList	object	no	read close
close Description Indicates that content should be one of the, in this object, listed items SDK Object type FixedListValidator
allowedValues	array	no	read close
close Description List of the allowed values that the field will be validated against
iban	object	no	read close
close Description Indicates that the content of this (iban) field needs to validated against format checks and modulo check (as described in ISO 7064) SDK Object type EmptyValidator
length	object	no	read close
close Description Indicates that the content needs to be validated against length criteria defined in this object SDK Object type LengthValidator
maxLength	integer	no	read close
close Description The maximum allowed length
minLength	integer	no	read close
close Description The minimum allowed length
luhn	object	no	read close
close Description Indicates that the content needs to be validated using a LUHN check SDK Object type EmptyValidator
range	object	no	read close
close Description Indicates that the content needs to be validated against a, in this object, defined range SDK Object type RangeValidator
maxValue	integer	no	read close
close Description Upper value of the range that is still valid
minValue	integer	no	read close
close Description Lower value of the range that is still valid
regularExpression	object	no	read close
close Description A string representing the regular expression to check SDK Object type RegularExpressionValidator
regularExpression	string	no	read close
close Description Contains the regular expression that the value of the field needs to be validated against
residentIdNumber	object	no	read close
close Description Indicates that the content needs to be validated as per the Chinese resident identity number format SDK Object type EmptyValidator
termsAndConditions	object	no	read close
close Description Indicates that the content should be validated as such that the customer has accepted the field as if they were terms and conditions of a service SDK Object type EmptyValidator
displayHints	object	no	read close
close Description Object containing display hints for this field, like the order, mask, preferred keyboard SDK Object type PaymentProductFieldDisplayHints
alwaysShow	boolean	no	read close
close Description true - Indicates that this field is advised to be captured to increase the success rates even though it isn't marked as required. Please note that making the field required could hurt the success rates negatively. This boolean only indicates our advise to always show this field to the customer. false - Indicates that this field is not to be shown unless it is a required field.
displayOrder	integer	no	read close
close Description The order in which the fields should be shown (ascending)
formElement	object	no	read close
close Description Object detailing the type of form element that should be used to present the field SDK Object type PaymentProductFieldFormElement
type	string	no	read close
close Description Type of form element to be used. The following types can be returned: text - A normal text input field list - A list of values that the customer needs to choose from, is detailed in the valueMapping array currency - Currency fields should be split into two fields, with the second one being specifically for the cents boolean - Boolean fields should offer the customer a choice, like accepting the terms and conditions of a product. date - let the customer pick a date.
valueMapping	array of object	no	read close
close Description An array of values and displayNames that should be used to populate the list object in the GUI
items	object	no	read close
close SDK Object type ValueMappingElement
displayElements	array of object	no	read close
close Description List of extra data of the value.
items	object	no	read close
close SDK Object type PaymentProductFieldDisplayElement
id	string	no	read close
close Description The ID of the display element.
label	string	no	read close
close Description The label of the display element.
type	enum	no	read close
close Description The type of the display element. Indicates how the value should be presented. Possible values are: STRING - as plain text CURRENCY - as an amount in cents displayed with a decimal separator and the currency of the payment PERCENTAGE - as a number with a percentage sign INTEGER - as an integer URI - as a link
value	string	no	read close
close Description the value of the display element.
displayName	string	no	read close
close Deprecated: Use displayElements instead with ID 'displayName' Description Key name
value	string	no	read close
close Description Value corresponding to the key
label	string	no	read close
close Description Label/Name of the field to be used in the user interface
link	string	no	read close
close Description Link that should be used to replace the '{link}' variable in the label.
mask	string	no	read close
close Description A mask that can be used in the input field. You can use it to inject additional characters to provide a better user experience and to restrict the accepted character set (illegal characters to be ignored during typing). * is used for wildcards (and also chars) 9 is used for numbers Everything outside {{ and }} is used as-is.
obfuscate	boolean	no	read close
close Description true - The data in this field should be obfuscated as it is entered, just like a password field false - The data in this field does not need to be obfuscated
placeholderLabel	string	no	read close
close Description A placeholder value for the form element
preferredInputType	string	no	read close
close Description The type of keyboard that can best be used to fill out the value of this field. Possible values are: PhoneNumberKeyboard - Keyboard that is normally used to enter phone numbers StringKeyboard - Keyboard that is used to enter strings IntegerKeyboard - Keyboard that is used to enter only numerical values EmailAddressKeyboard - Keyboard that allows easier entry of email addresses
tooltip	object	no	read close
close Description Object that contains an optional tooltip to assist the customer SDK Object type PaymentProductFieldTooltip
image	string	no	read close
close Description Relative URL that can be used to retrieve an image for the tooltip image. You can use our server-side resize functionality by appending '?size={{width}}x{{height}}' to the full URL, where width and height are specified in pixels. The resized image will always keep its correct aspect ratio.
label	string	no	read close
close Description A text explaining the field in more detail. This is meant to be used for displaying to the customer.
id	string	no	read close
close Description The ID of the field
type	enum	no	read close
close Description The type of field, possible values are: string - Any UTF-8 chracters numericstring - A string that consisting only of numbers. Note that you should strip out anything that is not a digit, but leading zeros are allowed date - Date in the format DDMMYYYY expirydate - Expiration date in the format MMYY integer - An integer boolean - A boolean
usedForLookup	boolean	no	read close
close Description Indicates that the product can be used in a get customer details call and that when that call is done the field should be supplied as (one of the) key(s) with a valid value.
fieldsWarning	string	no	read close
close Description If one or more of the payment product fields could not be constructed, no payment product fields will be returned and a message will be present in this property stating why.
id	integer	yes	read close
close Description The ID of the payment product in our system
isAuthenticationSupported	boolean	no	read close
close Description Indicates if the payment product supports 3D-Secure.
isJavaScriptRequired	boolean	no	read close
close Description This property indicates if the payment product requires JavaScript to be enabled on the customer's browser. This is usually only true if the payment product depends on a third party JavaScript integration. true - the payment product requires JavaScript to be enabled. false - the payment product does not require JavaScript to be enabled. This is the default value if the property is not present.
maxAmount	integer	no	read close
close Description Maximum amount in cents (using 2 decimals, so 1 EUR becomes 100 cents) for transactions done with this payment product
minAmount	integer	no	read close
close Description Minimum amount in cents (using 2 decimals, so 1 EUR becomes 100 cents) for transactions done with this payment product
mobileIntegrationLevel	string	no	read close
close Description This provides insight into the level of support for payments using a device with a smaller screen size. You can for instance use this to rank payment products differently on devices with a smaller screen. Possible values are: NO_SUPPORT - The payment product does not work at all on a mobile device BASIC_SUPPORT - The payment product has not optimized its user experience for devices with smaller screens OPTIMISED_SUPPORT - The payment product offers a user experience that has been optimized for devices with smaller screens
paymentMethod	string	no	read close
close Description Indicates which payment method will be used for this payment product. Payment method is one of: bankTransfer card cash directDebit eInvoice invoice redirect
Group paymentProduct302SpecificData	object	no	read close
close Description Apple Pay (payment product 302) specific details. SDK Object type PaymentProduct302SpecificData Property is part of a group Learn more Properties that make up a group are mutually exclusive, which means you can only include one of each group in any given call. If there are multiple groups at one level in the object hierarchy we use numbers to distinguish groups from one another.
networks	array	no	read close
close Description The networks that can be used in the current payment context. The strings that represent the networks in the array are identical to the strings that Apple uses in their documentation. For instance: "Visa".
Group paymentProduct320SpecificData	object	no	read close
close Description Google Pay (payment product 320) specific details. SDK Object type PaymentProduct320SpecificData Property is part of a group Learn more Properties that make up a group are mutually exclusive, which means you can only include one of each group in any given call. If there are multiple groups at one level in the object hierarchy we use numbers to distinguish groups from one another.
gateway	string	no	read close
close Description The GlobalCollect gateway identifier. You should use this when creating a tokenization specification.
networks	array	no	read close
close Description The networks that can be used in the current payment context. The strings that represent the networks in the array are identical to the strings that Google uses in their documentation. For instance: "VISA".
Group paymentProduct863SpecificData	object	no	read close
close Description WeChat Pay (payment product 863) specific details. SDK Object type PaymentProduct863SpecificData Property is part of a group Learn more Properties that make up a group are mutually exclusive, which means you can only include one of each group in any given call. If there are multiple groups at one level in the object hierarchy we use numbers to distinguish groups from one another.
integrationTypes	array	no	read close
close Description The WeChat Pay integration types that can be used in the current payment context. Possible values: desktopQRCode - used on desktops, the customer opens the WeChat app by scanning a QR code. urlIntent - used in mobile apps or on mobile web pages, the customer opens the WeChat app using a URL intent. nativeInApp - used in mobile apps that use the WeChat Pay SDK.
paymentProductGroup	string	no	read close
close Description The payment product group that has this payment product, if there is any. Not populated otherwise. Currently only one payment product group is supported: cards
supportsMandates	boolean	no	read close
close Description Indicates whether the payment product supports mandates.
usesRedirectionTo3rdParty	boolean	no	read close
close Description Indicates whether the payment product requires redirection to a third party to complete the payment. You can use this to filter out products that require a redirect if you don't want to support that. true - Redirection is required false - No redirection is required

Response example

SDK: Ruby

This scenario you will probably use the most

{
    "paymentProducts" : [
        {
            "allowsRecurring" : true,
            "allowsTokenization" : true,
            "displayHints" : {
                "displayOrder" : 20,
                "label" : "Visa",
                "logo" : "templates/master/global/css/img/ppimages/pp_logo_1_v1.png"
            },
            "id" : 1,
            "maxAmount" : 1000000,
            "mobileIntegrationLevel" : "OPTIMISED_SUPPORT",
            "paymentMethod" : "card",
            "paymentProductGroup" : "cards"
        },
        {
            "allowsRecurring" : true,
            "allowsTokenization" : true,
            "displayHints" : {
                "displayOrder" : 19,
                "label" : "American Express",
                "logo" : "templates/master/global/css/img/ppimages/pp_logo_2_v1.png"
            },
            "id" : 2,
            "maxAmount" : 1000000,
            "mobileIntegrationLevel" : "OPTIMISED_SUPPORT",
            "paymentMethod" : "card",
            "paymentProductGroup" : "cards"
        },
        {
            "allowsRecurring" : true,
            "allowsTokenization" : true,
            "displayHints" : {
                "displayOrder" : 18,
                "label" : "MasterCard",
                "logo" : "templates/master/global/css/img/ppimages/pp_logo_3_v1.png"
            },
            "id" : 3,
            "maxAmount" : 1000000,
            "mobileIntegrationLevel" : "OPTIMISED_SUPPORT",
            "paymentMethod" : "card",
            "paymentProductGroup" : "cards"
        }
    ]
}

Response 400 - Bad requestErrorResponse

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close Description Contains detailed information on one single error. SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT_PLATFORM_ERROR - indicating that a functional error has occurred in the Connect platform. PAYMENT_PLATFORM_ERROR - indicating that a functional error has occurred in the Payment platform. IO_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
propertyName	string	no	read close
close Description Returned only if the error relates to a value that was missing or incorrect. Contains a location path to the value as a JSonata query. Some common examples: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
requestId	string	no	read close
close Description ID of the request that can be used for debugging purposes

Response example

SDK: Ruby

This scenario you will probably use the most

{
    "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092",
    "errors" : [
        {
            "code" : "20000000",
            "propertyName" : "bankAccountBban.accountNumber",
            "message" : "PARAMETER_NOT_FOUND_IN_REQUEST"
        }
    ]
}

Get payment products

Products

Request

Query parameters

Description

Description

Description

Description

Description

Description

Description

Request example

Responses

Response 200 - OKPaymentProducts

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description