API Reference

Server API version 1.0
Java

Results for

icon-search-large No search results yet
Enter your search query above

Get payment product

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

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

Use this API if you are just interested in one payment product or if you have filtered out the fields in the Get payment products call and you want to retrieve the field details on a single payment product. By doing it in this two-step process you will reduce the amount of data that needs to be transported back to your client, but you will have to make two calls. Usually the performance penalty is bigger when you need to do multiple calls with a small response package than one call with a bigger response package. You are however free to choose the best solution for your use case. You can submit additional details on the transaction as filters. In that case, the payment product is returned only if it matches the filters, otherwise a 400 response is returned.

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.
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
forceBasicFlow boolean no no read close
close

Description

Relevant only for payment product 3012 (Bancontact). A boolean that indicates if you want to force the response to return the fields of the basic flow. This can be useful in corner cases where you have enabled the enhanced flow which supports payment with the Bancontact app, but need access to the product fields without creating a payment first.

Request example

SDK: Java

This scenario you will probably use the most

  • GetProductParams query = new GetProductParams();
    query.setCountryCode("US");
    query.setCurrencyCode("USD");
    query.setLocale("en_US");
    query.setAmount(1000L);
    query.setIsRecurring(true);
    query.setForceBasicFlow(false);
    query.addHide("fields");
    
    PaymentProductResponse response = client.merchant("merchantId").products().get(1, query);
    

Responses

Please find below an overview of the possible responses.

Response 200 - OKPaymentProductResponse

The response contains the details of just one payment product

Property Type Required Details
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 field
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 field
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 consumer 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.
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 field is only relevant for payment products that use third party redirects. This field 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 on the fields you should have us filter them our (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
termsAndConditions object no read close
close

Description

Indicates that the content should be validated as such that the consumer 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 consumer.
  • 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 consumer 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 consumer a choice, like accepting the terms and conditions of a product.
  • date - let the consumer 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 displayElement with ID 'displayName' instead.

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 consumer
  • 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 consumer.
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 field stating why.
id integer yes read close
close

Description

The ID of the payment product in our system
maxAmount integer no read close
close

Description

Maximum amount in EUR 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 EUR 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 mobile devices
  • OPTIMISED_SUPPORT - The payment product offers a user experience that has been optimized for mobile devices
paymentMethod string no read close
close

Description

Payment method identifier used by the our payment engine with the following possible values:
  • bankRefund
  • bankTransfer
  • card
  • cash
  • directDebit
  • eInvoice
  • invoice
  • redirect
Group paymentProduct302SpecificData object no, one of group 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, one of group read close
close

Description

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

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, one of group 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 consumer opens the WeChat app by scanning a QR code.
  • urlIntent - used in mobile apps or on mobile web pages, the consumer 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
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: Java

This scenario you will probably use the most

  • {
        "allowsRecurring" : true,
        "allowsTokenization" : true,
        "displayHints" : {
            "displayOrder" : 20,
            "label" : "Visa",
            "logo" : "templates/master/global/css/img/ppimages/pp_logo_1_v1.png"
        },
        "fields" : [
            {
                "dataRestrictions" : {
                    "isRequired" : true,
                    "validators" : {
                        "length" : {
                            "maxLength" : 19,
                            "minLength" : 12
                        },
                        "luhn" : { }
                    }
                },
                "displayHints" : {
                    "displayOrder" : 10,
                    "formElement" : {
                        "type" : "text"
                    },
                    "label" : "Card number:",
                    "mask" : "{{9999}} {{9999}} {{9999}} {{9999}} {{999}}",
                    "obfuscate" : false,
                    "placeholderLabel" : "**** **** **** ****",
                    "preferredInputType" : "IntegerKeyboard"
                },
                "id" : "cardNumber",
                "type" : "numericstring"
            },
            {
                "dataRestrictions" : {
                    "isRequired" : true,
                    "validators" : {
                        "expirationDate" : { },
                        "length" : {
                            "maxLength" : 4,
                            "minLength" : 4
                        },
                        "regularExpression" : {
                            "regularExpression" : "(?:0[1-9]|1[0-2])[0-9]{2}"
                        }
                    }
                },
                "displayHints" : {
                    "displayOrder" : 20,
                    "formElement" : {
                        "type" : "text"
                    },
                    "label" : "Expiry date:",
                    "mask" : "{{99}}/{{99}}",
                    "obfuscate" : false,
                    "placeholderLabel" : "MM/YY",
                    "preferredInputType" : "IntegerKeyboard"
                },
                "id" : "expiryDate",
                "type" : "expirydate"
            },
            {
                "dataRestrictions" : {
                    "isRequired" : false,
                    "validators" : {
                        "length" : {
                            "maxLength" : 4,
                            "minLength" : 3
                        },
                        "regularExpression" : {
                            "regularExpression" : "^[0-9]{3}[0-9]?$"
                        }
                    }
                },
                "displayHints" : {
                    "displayOrder" : 24,
                    "formElement" : {
                        "type" : "text"
                    },
                    "label" : "CVV:",
                    "mask" : "{{9999}}",
                    "obfuscate" : false,
                    "placeholderLabel" : "123",
                    "preferredInputType" : "IntegerKeyboard",
                    "tooltip" : {
                        "image" : "templates/master/global/css/img/ppimages/ppf_cvv_v1.png",
                        "label" : "The CVV is a 3 or 4 digit code embossed or imprinted on your card."
                    }
                },
                "id" : "cvv",
                "type" : "numericstring"
            }
        ],
        "id" : 1,
        "maxAmount" : 1000000,
        "mobileIntegrationLevel" : "OPTIMISED_SUPPORT",
        "paymentMethod" : "card",
        "paymentProductGroup" : "cards"
    }
    

Response 400 - Bad requestErrorResponse

There was an error in the request, or the paymentProductId you submitted does not exist or does not meet the filters you submitted.

Property Type Required Details
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
  • 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 consumer 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: Java

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"
            }
        ]
    }
    
icon_top_1