Get payment product groups
GET https://{domainname}/client/v1/{customerId}/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 field allows you to not have us return token details and/or 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
DescriptionISO 3166-1 alpha-2 country code of the transaction
|
||||
| currencyCode | string | yes | no | read close |
|
close
DescriptionThree-letter ISO currency code representing the currency for the amount
|
||||
| locale | string | no | no | read close |
|
close
DescriptionLocale 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
DescriptionAmount of the transaction in cents and always having 2 decimals
|
||||
| isRecurring | boolean | no | no | read close |
|
close
DescriptionToggles filtering on support for recurring payments. Default value is false.
|
||||
| isInstallments | boolean | no | no | read close |
|
close
DescriptionThis allows you to filter payment products based on their support for installments or not
|
||||
| hide | string | no | yes | read close |
|
close
DescriptionAllows you to hide elements from the response, reducing the amount of data that needs to be returned to your client. Possible options are:
|
||||
Request example
SDK: JSON
This scenario you will probably use the most
-
countryCode=NL¤cyCode=EUR&locale=en_US&amount=1000&isRecurring=true&isInstallments=true&hide=accountsOnFile
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 |
|---|---|---|---|
| array of object | no | read close | |
|
close
DescriptionArray containing payment product groups and their characteristics
|
|||
| object | no | read close | |
| array of object | no | read close | |
|
close
DescriptionList of every account on file of every payment product that belongs to the group.
If you are not interested in these accountsOnFile you can have us filter them our (using hide=accountsOnFile in the query-string)
|
|||
| object | no | read close | |
| array of object | no | read close | |
|
close
DescriptionArray containing the details of the stored token
|
|||
| object | no | read close | |
| key | string | no | read close |
|
close
DescriptionName of the key or property
|
|||
| mustWriteReason | enum | no | read close |
|
close
DescriptionThe 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
DescriptionPossible values:
|
|||
| value | string | no | read close |
|
close
DescriptionValue of the key or property
|
|||
| object | no | read close | |
|
close
DescriptionObject containing information for the client on how best to display this field
|
|||
| array of object | no | read close | |
|
close
DescriptionArray of attribute keys and their mask
|
|||
| object | no | read close | |
| attributeKey | string | no | read close |
|
close
DescriptionName of the attribute that is shown to the customer on selection pages or screens
|
|||
| mask | string | no | read close |
|
close
DescriptionRegular mask for the attributeKey
Note: The mask is optional as not every field has a mask |
|||
| logo | string | no | read close |
|
close
DescriptionPartial 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
DescriptionID of the account on file record
|
|||
| paymentProductId | integer | no | read close |
|
close
DescriptionPayment product identifier
Please see payment products for a full overview of possible values. |
|||
| allowsInstallments | boolean | no | read close |
|
close
DescriptionIndicates if the product supports installments
|
|||
| deviceFingerprintEnabled | boolean | no | read close |
|
close
DescriptionIndicates if device fingerprint is enabled for the product group
|
|||
| object | no | read close | |
|
close
DescriptionObject 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.
|
|||
| displayOrder | integer | no | read close |
|
close
DescriptionDetermines the order in which the payment products and groups should be shown (sorted ascending)
|
|||
| label | string | no | read close |
|
close
DescriptionName of the payment product or group based on the locale that was included in the request
|
|||
| logo | string | no | read close |
|
close
DescriptionPartial URL that you can reference for the image of this payment product or group. 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.
|
|||
| array of object | no | read close | |
|
close
DescriptionObject 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 our (using hide=fields in the query-string)
|
|||
| object | no | read close | |
| object | no | read close | |
|
close
DescriptionObject containing data restrictions that apply to this field, like minimum and/or maximum length
|
|||
| isRequired | boolean | no | read close |
|
close
Description
|
|||
| object | no | read close | |
|
close
DescriptionObject containing the details of the validations on the field
|
|||
| object | no | read close | |
|
close
DescriptionIndicates the requiredness of the field based on the fiscalnumber for Boleto Bancario
|
|||
| fiscalNumberLength | integer | no | read close |
|
close
DescriptionWhen 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
DescriptionIndicates that the content should be validated against the rules for an email address
|
|||
| expirationDate | object | no | read close |
|
close
DescriptionIndicates that the content should be validated against the rules for an expiration date (it should be in the future)
|
|||
| object | no | read close | |
|
close
DescriptionIndicates that content should be one of the, in this object, listed items
|
|||
| allowedValues | array | no | read close |
|
close
DescriptionList of the allowed values that the field will be validated against
|
|||
| iban | object | no | read close |
|
close
DescriptionIndicates that the content of this (iban) field needs to validated against format checks and modulo check (as described in ISO 7064)
|
|||
| object | no | read close | |
|
close
DescriptionIndicates that the content needs to be validated against length criteria defined in this object
|
|||
| maxLength | integer | no | read close |
|
close
DescriptionThe maximum allowed length
|
|||
| minLength | integer | no | read close |
|
close
DescriptionThe minimum allowed length
|
|||
| luhn | object | no | read close |
|
close
DescriptionIndicates that the content needs to be validated using a LUHN check
|
|||
| object | no | read close | |
|
close
DescriptionIndicates that the content needs to be validated against a, in this object, defined range
|
|||
| maxValue | integer | no | read close |
|
close
DescriptionUpper value of the range that is still valid
|
|||
| minValue | integer | no | read close |
|
close
DescriptionLower value of the range that is still valid
|
|||
| object | no | read close | |
|
close
DescriptionA string representing the regular expression to check
|
|||
| regularExpression | string | no | read close |
|
close
DescriptionContains the regular expression that the value of the field needs to be validated against
|
|||
| residentIdNumber | object | no | read close |
|
close
DescriptionIndicates that the content needs to be validated as per the Chinese resident identity number format
|
|||
| termsAndConditions | object | no | read close |
|
close
DescriptionIndicates 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
|
|||
| object | no | read close | |
|
close
DescriptionObject containing display hints for this field, like the order, mask, preferred keyboard
|
|||
| alwaysShow | boolean | no | read close |
|
close
Description
|
|||
| displayOrder | integer | no | read close |
|
close
DescriptionThe order in which the fields should be shown (ascending)
|
|||
| object | no | read close | |
|
close
DescriptionObject detailing the type of form element that should be used to present the field
|
|||
| type | string | no | read close |
|
close
DescriptionType of form element to be used. The following types can be returned:
|
|||
| array of object | no | read close | |
|
close
DescriptionAn array of values and displayNames that should be used to populate the list object in the GUI
|
|||
| object | no | read close | |
| array of object | no | read close | |
|
close
DescriptionList of extra data of the value.
|
|||
| object | no | read close | |
| id | string | no | read close |
|
close
DescriptionThe ID of the display element.
|
|||
| label | string | no | read close |
|
close
DescriptionThe label of the display element.
|
|||
| type | enum | no | read close |
|
close
DescriptionThe type of the display element. Indicates how the value should be presented. Possible values are:
|
|||
| value | string | no | read close |
|
close
Descriptionthe value of the display element.
|
|||
| displayName | string | no | read close |
|
close
Deprecated:
Use displayElements instead with ID 'displayName'
DescriptionKey name
|
|||
| value | string | no | read close |
|
close
DescriptionValue corresponding to the key
|
|||
| label | string | no | read close |
|
close
DescriptionLabel/Name of the field to be used in the user interface
|
|||
| link | string | no | read close |
|
close
DescriptionLink that should be used to replace the '{link}' variable in the label.
|
|||
| mask | string | no | read close |
|
close
DescriptionA 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 will 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
|
|||
| placeholderLabel | string | no | read close |
|
close
DescriptionA placeholder value for the form element
|
|||
| preferredInputType | string | no | read close |
|
close
DescriptionThe type of keyboard that can best be used to fill out the value of this field. Possible values are:
|
|||
| object | no | read close | |
|
close
DescriptionObject that contains an optional tooltip to assist the customer
|
|||
| image | string | no | read close |
|
close
DescriptionRelative URL that can be used to retrieve an image for the tooltip image.
|
|||
| label | string | no | read close |
|
close
DescriptionA text explaining the field in more detail. This is meant to be used for displaying to the customer.
|
|||
| id | string | no | read close |
|
close
DescriptionThe ID of the field
|
|||
| type | enum | no | read close |
|
close
DescriptionThe type of field, possible values are:
|
|||
| usedForLookup | boolean | no | read close |
|
close
DescriptionIndicates 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.
|
|||
| id | string | yes | read close |
|
close
DescriptionThe ID of the payment product group in our system
|
|||
Response example
SDK: JSON
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 |
|---|---|---|---|
| errorId | string | yes | read close |
|
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
| array of object | yes | read close | |
|
close
DescriptionList of one or more errors
|
|||
| object | no | read close | |
| category | string | no | read close |
|
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
| code | string | yes | read close |
|
close
DescriptionError code
|
|||
| httpStatusCode | integer | no | read close |
|
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
| id | string | no | read close |
|
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
| message | string | no | read close |
|
close
DescriptionHuman-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
DescriptionReturned 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:
|
|||
| requestId | string | no | read close |
|
close
DescriptionID of the request that can be used for debugging purposes
|
|||
Response example
SDK: JSON
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" } ] }