This site requires javascript to be enabled.

  • Search AI-powered
    Search results are AI-generated and are not guaranteed to be accurate, complete, or up-to-date. They are not a substitute for legal or professional advice. Refer to our terms of use for more details.
    Search AI-powered

Results for

xxx

Get payment product groups

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

Product Groups

Through this API you can retrieve payment product groups. A payment product group has a collection of payment products that can be grouped together on a payment product selection page, and a set of fields to render on the payment product details page that allow to determine which payment product of the group the consumer wants to select. We currently support one payment product group named cards that has every credit card we support (and every debit card that behaves like a credit card). Its cardNumber field allows to determine the right payment product through a Get IIN details call.

Request

This service allows you to retrieve a list of every payment product group. You can submit additional details on the transaction as filters. In that case, a group is included in the response only if it has at least one payment product that matches those filters. For example, when you are setting your user up for a recurring payment, this allows you to only have groups returned that have at least one payment product that supports recurring transactions. The hide property allows you to not have us the list of fields associated with each of the payment product groups.

By submitting the locale you can benefit from the server side language packs if your 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 of the transaction
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 set up 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 of the transaction in cents and always having 2 decimals
isRecurring boolean no no read close
close

Description

This allows you to filter groups based on their support for recurring, where a group supports recurring if it has at least one payment product that supports recurring
  • true
  • false
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

Request example

SDK: PHP

This scenario you will probably use the most

  • $query = new FindProductgroupsParams();
$query->countryCode = 'US';
$query->currencyCode = 'USD';
$query->locale = 'en_US';
$query->amount = 1000;
$query->isRecurring = true;
$query->isInstallments = true;
$query->hide = array('fields');

$response = $client->v1()->merchant('merchantId')->productgroups()->find($query);

Responses

Please find below an overview of the possible responses.

Response 200 - OKPaymentProductGroups

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

Properties
Property Type Required Details
close

Description

Array containing payment product groups and their characteristics
close
  • SDK Object type
    PaymentProductGroup
close

Description

Only populated in the Client API
close
  • SDK Object type
    AccountOnFile
close

Description

Array containing the details of the stored token
close
  • SDK Object type
    AccountOnFileAttribute
close

Description

Name of the key or property
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.
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.
close

Description

Value of the key or property
close

Description

Object containing information for the client on how best to display this field
  • SDK Object type
    AccountOnFileDisplayHints
close

Description

Array of attribute keys and their mask
close
  • SDK Object type
    LabelTemplateElement
close

Description

Name of the attribute that is shown to the customer on selection pages or screens
close

Description

Regular mask for the attributeKey
Note: The mask is optional as not every field has a mask
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.
close

Description

ID of the account on file record
close

Description

Payment product identifier
Please see payment products for a full overview of possible values.
close

Description

Indicates if the product supports installments
  • true - This payment supports installments
  • false - This payment does not support installments
close

Description

Indicates if device fingerprint is enabled for the product group
  • true
  • false
close

Description

Object containing display hints like the order of the group when shown in a list, the name of the group and the logo. Note that the order of the group is the lowest order among the payment products that belong to the group.
  • SDK Object type
    PaymentProductDisplayHints
close

Description

Determines the order in which the payment products and groups should be shown (sorted ascending)
close

Description

Name of the field based on the locale that was included in the request
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.
close

Description

Object containing all the fields and their details that are associated with this payment product group. If you are not interested in the these fields you can have us filter them out (using hide=fields in the query-string)
close
  • SDK Object type
    PaymentProductField
close

Description

Object containing data restrictions that apply to this field, like minimum and/or maximum length
  • SDK Object type
    PaymentProductFieldDataRestrictions
close

Description

  • true - Indicates that this field is required
  • false - Indicates that this field is optional
close

Description

Object containing the details of the validations on the field
  • SDK Object type
    PaymentProductFieldValidators
close

Description

Indicates the requiredness of the field based on the fiscalnumber for Boleto Bancario
  • SDK Object type
    BoletoBancarioRequirednessValidator
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.
close

Description

Indicates that the content should be validated against the rules for an email address
  • SDK Object type
    EmptyValidator
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
close

Description

Indicates that content should be one of the, in this object, listed items
  • SDK Object type
    FixedListValidator
close

Description

List of the allowed values that the field will be validated against
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
close

Description

Indicates that the content needs to be validated against length criteria defined in this object
  • SDK Object type
    LengthValidator
close

Description

The maximum allowed length
close

Description

The minimum allowed length
close

Description

Indicates that the content needs to be validated using a LUHN check
  • SDK Object type
    EmptyValidator
close

Description

Indicates that the content needs to be validated against a, in this object, defined range
  • SDK Object type
    RangeValidator
close

Description

Upper value of the range that is still valid
close

Description

Lower value of the range that is still valid
close

Description

A string representing the regular expression to check
  • SDK Object type
    RegularExpressionValidator
close

Description

Contains the regular expression that the value of the field needs to be validated against
close

Description

Indicates that the content needs to be validated as per the Chinese resident identity number format
  • SDK Object type
    EmptyValidator
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
close

Description

Object containing display hints for this field, like the order, mask, preferred keyboard
  • SDK Object type
    PaymentProductFieldDisplayHints
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.
close

Description

The order in which the fields should be shown (ascending)
close

Description

Object detailing the type of form element that should be used to present the field
  • SDK Object type
    PaymentProductFieldFormElement
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.
close

Description

An array of values and displayNames that should be used to populate the list object in the GUI
close
  • SDK Object type
    ValueMappingElement
close

Description

List of extra data of the value.
close
  • SDK Object type
    PaymentProductFieldDisplayElement
close

Description

The ID of the display element.
close

Description

The label of the display element.
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
close

Description

the value of the display element.
close
Deprecated: Use displayElements instead with ID 'displayName'

Description

Key name
close

Description

Value corresponding to the key
close

Description

Label/Name of the field to be used in the user interface
close

Description

Link that should be used to replace the '{link}' variable in the label.
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.
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
close

Description

A placeholder value for the form element
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
close

Description

Object that contains an optional tooltip to assist the customer
  • SDK Object type
    PaymentProductFieldTooltip
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.
close

Description

A text explaining the field in more detail. This is meant to be used for displaying to the customer.
close

Description

The ID of the field
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
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.
close

Description

The ID of the payment product group in our system

Response example

SDK: PHP

This scenario you will probably use the most

  • {
    "paymentProductGroups" : [
        {
            "displayHints" : {
                "displayOrder" : 20,
                "label" : "Cards",
                "logo" : "/templates/master/global/css/img/ppimages/group-card.png"
            },
            "id" : "cards"
        }
    ]
}

Response 400 - Bad requestErrorResponse

Properties
Property Type Required Details
close

Description

Unique reference, for debugging purposes, of this error response
close

Description

List of one or more errors
close

Description

Contains detailed information on one single error.
  • SDK Object type
    APIError
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.
close

Description

Error code
close

Description

HTTP status code for this error that can be used to determine the type of error
close

Description

ID of the error. This is a short human-readable message that briefly describes the error.
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
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'.
close

Description

ID of the request that can be used for debugging purposes

Response example

SDK: PHP

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