Get payment product group
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
Use this service if you are just interested in a particular payment product group. You can submit additional details on the transaction as filters. In that case, the group is returned only if it matches the filters, otherwise a 404 response is returned.
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 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
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:
|
||||
Property | Type | Required | Repeat | Details |
Request example
This scenario you will probably use the most
-
query = GetProductgroupParams() 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').productgroups().get('cards', query)
Responses
Please find below an overview of the possible responses.
Response 200 - OKPaymentProductGroupResponse
The response contains the details of just one payment product group
Properties
|
|||
Property | Type | Required | Details |
---|---|---|---|
array of object | no | read close | |
close
DescriptionList of tokens for that payment product
|
|||
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 in which the product should be shown, the name of the product and the logo
|
|||
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 field 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. 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. If you are not interested in the data on the fields you should have us filter them out (using filter=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 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
|
|||
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. 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
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 in our system
|
|||
Property | Type | Required | Details |
Response example
This scenario you will probably use the most
-
{ "displayHints" : { "displayOrder" : 20, "label" : "Cards", "logo" : "/templates/master/global/css/img/ppimages/group-card.png" }, "fields" : [ { "dataRestrictions" : { "isRequired" : true, "validators" : { "length" : { "maxLength" : 19, "minLength" : 12 } } }, "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" : "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
|
|||
Property | Type | Required | Details |
Response example
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" } ] }
Response 404 - Not foundErrorResponse
The paymentProductGroupId you submitted does not exist or does not match the filters you submitted.
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
|
|||
Property | Type | Required | Details |
Response example
This scenario you will probably use the most
-
{ "errorId" : "657b10da-d2f9-4088-a948-bf190ef516b1-00000213", "errors" : [ { "code" : "1070", "message" : "UNKNOWN_PAYMENT_PRODUCT_GROUP_ID" } ] }