Get payment product group

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

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 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 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 of the transaction in cents and always having 2 decimals.
isRecurring	boolean	no	no	read close
close Description Toggles filtering on support for recurring payments. Default value is false. true - filter out groups that do not support recurring payments, where a group supports recurring payments if it has at least one payment product that supports recurring. false - do not filter
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: Node.js

This scenario you will probably use the most

var query = {
    "countryCode" : "US",
    "currencyCode" : "USD",
    "locale" : "en_US",
    "amount" : 1000,
    "isRecurring" : true,
    "isInstallments" : true,
    "hide" : [
        "fields"
    ]
};
const sdkResponse = await client.v1.productgroups.get("merchantId", "cards", query);
// sdkResponse has the following properties:
// - status: the HTTP status code
// - body: the response body
// - isSuccess: true if the call was successful,
//              or false if the Worldline Global Collect platform returned an error response

Responses

Please find below an overview of the possible responses.

Response 200 - OKPaymentProductGroupResponse

The response contains the details of just one payment product group

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
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.
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
deviceFingerprintEnabled	boolean	no	read close
close Description Indicates if device fingerprint is enabled for the product group 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 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.
id	string	yes	read close
close Description The ID of the payment product in our system

Response example

SDK: Node.js

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

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: Node.js

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.

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: Node.js

This scenario you will probably use the most

{
    "errorId" : "657b10da-d2f9-4088-a948-bf190ef516b1-00000213",
    "errors" : [
        {
            "code" : "1070",
            "message" : "UNKNOWN_PAYMENT_PRODUCT_GROUP_ID"
        }
    ]
}

Get payment product group

Product Groups

Request

Query parameters

Description

Description

Description

Description

Description

Description

Description

Request example

Responses

Response 200 - OKPaymentProductGroupResponse

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