Get payment product
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
DescriptionISO 3166-1 alpha-2 country code
|
||||
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 in cents and always having 2 decimals
|
||||
isRecurring | boolean | no | no | read close |
close
DescriptionThis allows you to filter payment products based on their support for recurring or not
|
||||
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:
|
||||
forceBasicFlow | boolean | no | no | read close |
close
DescriptionRelevant 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
This scenario you will probably use the most
-
query = GetProductParams() query.country_code = 'US' query.currency_code = 'USD' query.locale = 'en_US' query.amount = 1000 query.is_recurring = True query.is_installments = True query.force_basic_flow = False query.add_hide('fields') response = client.v1().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
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. |
|||
acquirerCountry | string | no | read close |
close
DescriptionISO 3166-1 alpha-2 country code which indicates the most likely country code of the acquirer that will process the transaction. For Google Pay (paymentProductId 320) transactions this acquirerCountry is should be provided in the transactionInfo.countryCode for merchants that use an acquirer that is based in one of the European Economic Area (EEA) countries to make sure the transaction is compliant with the PSD2 Strong Customer Authentication (SCA) requirements. More information on Strong Customer Authentication compliance for Google Pay can be found at https://developers.google.com/pay/api/web/guides/resources/sca
|
|||
allowsInstallments | boolean | no | read close |
close
DescriptionIndicates if the product supports installments
|
|||
allowsRecurring | boolean | no | read close |
close
DescriptionIndicates if the product supports recurring payments
|
|||
allowsTokenization | boolean | no | read close |
close
DescriptionIndicates if the payment details can be tokenized for future re-use
|
|||
object | no | read close | |
close
DescriptionIndicates if the payment product supports 3D Security (mandatory, optional or not needed).
|
|||
name | string | no | read close |
close
DescriptionThe name of the indicator as to how it is mapped in the response.
|
|||
value | string | no | read close |
close
DescriptionThe value of the indicator as to how it is mapped in the response.
|
|||
autoTokenized | boolean | no | read close |
close
DescriptionIndicates if the payment details can be automatically tokenized for future re-use
|
|||
canBeIframed | boolean | no | read close |
close
DescriptionThis property is only relevant for payment products that use third party redirects. This property indicates if the third party disallows their payment pages to be embedded in an iframe using the X-Frame-Options header.
|
|||
deviceFingerprintEnabled | boolean | no | read close |
close
DescriptionIndicates if device fingerprint is enabled for the product
|
|||
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.
|
|||
fieldsWarning | string | no | read close |
close
DescriptionIf 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 property stating why.
|
|||
id | integer | yes | read close |
close
DescriptionThe ID of the payment product in our system
|
|||
isAuthenticationSupported | boolean | no | read close |
close
DescriptionIndicates if the payment product supports 3D-Secure.
|
|||
isJavaScriptRequired | boolean | no | read close |
close
DescriptionThis property indicates if the payment product requires JavaScript to be enabled on the customer's browser. This is usually only true if the payment product depends on a third party JavaScript integration.
|
|||
maxAmount | integer | no | read close |
close
DescriptionMaximum amount in cents (using 2 decimals, so 1 EUR becomes 100 cents) for transactions done with this payment product
|
|||
minAmount | integer | no | read close |
close
DescriptionMinimum amount in cents (using 2 decimals, so 1 EUR becomes 100 cents) for transactions done with this payment product
|
|||
mobileIntegrationLevel | string | no | read close |
close
DescriptionThis 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:
|
|||
paymentMethod | string | no | read close |
close
DescriptionPayment method identifier used by the our payment engine with the following possible values:
|
|||
object | no | read close | |
close
DescriptionApple Pay (payment product 302) specific details.
|
|||
networks | array | no | read close |
close
DescriptionThe 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".
|
|||
object | no | read close | |
close
DescriptionGoogle Pay (payment product 320) specific details.
|
|||
gateway | string | no | read close |
close
DescriptionThe GlobalCollect gateway identifier. You should use this when creating a tokenization specification.
|
|||
networks | array | no | read close |
close
DescriptionThe 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".
|
|||
object | no | read close | |
close
DescriptionWeChat Pay (payment product 863) specific details.
|
|||
integrationTypes | array | no | read close |
close
DescriptionThe WeChat Pay integration types that can be used in the current payment context. Possible values:
|
|||
paymentProductGroup | string | no | read close |
close
DescriptionThe payment product group that has this payment product, if there is any. Not populated otherwise. Currently only one payment product group is supported:
|
|||
supportsMandates | boolean | no | read close |
close
DescriptionIndicates whether the payment product supports mandates.
|
|||
usesRedirectionTo3rdParty | boolean | no | read close |
close
DescriptionIndicates 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.
|
Response example
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.
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
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" } ] }