Load the configuration
Load the enabled payment methods, other settings and build the UI
To create your own checkout you need to load the configuration of your sales location with the Service:GetConfig endpoint trough the GMS and the images & icons from our image repositories.
GMS MaintenanceDuring GMS maintenance, no changes can be made in your sales location. All our scheduled maintenance will be published on https://status.pay.nl>
The Service:GetConfig response returns all information in one response to build your checkout screens. Simply combine the output and the images & icons from our image repository to build your UI.
The response is organised in three main sections:
- Generic sales location info: Contains details about your sales location, merchant names to show in the checkout process and layout properties to maintain a consistent branding across your checkout pages.
- Checkout options with their options, settings and sequence: List the available payment methods that can be offered to the payer.
- Other settings: The TGU list returns the cores on which the transaction can be processed and the encryptionKeys are used for the embedded payment flow.
Generic sales location info
The response contains generic data regarding your sales location.
{
"code": "SL-2214-1473",
"secret": "e5296c**********8cc8",
"testMode": true,
"name": "Store",
"translations": {
"name": {
"en_GB": "Store",
"nl_NL": "Store"
}
},
"status": "ACTIVE",
"merchant": {
"code": "M-9284-9012",
"name": "Company name",
"status": "ACTIVE"
},
"category": {
"code": "CY-5170-7070",
"name": "Shoes & Sneakers"
},
"mcc": 7999,
"turnoverGroup": {
"code": "CT-0013-7232",
"name": "Default"
},
"layout": {
"code": "LY-1321-4070",
"name": "MyCustomLayout",
"cssUrl": "https://static.pay.nl/layout/LY-1321-4070/cssfile.css",
"icon": null,
"supportingColor": "",
"headerTextColor": "000000",
"buttonColor": "000000",
"buttonTextColor": "FFFFFF"
},
"tradeName": {
"code": "TM-2286-2065",
"name": "My trade name"
},
"contactPhone": "+312012345678",
"contactEmail": "[email protected]",
"address": {
"code": "CA-1234-1234",
"streetName": "My street",
"streetNumber": "1",
"zipCode": "1234AA",
"city": "Amsterdam",
"countryCode": "NL"
},
"createdAt": "2022-02-14T11:41:36+01:00",
"createdBy": "A-5390-2487",
"modifiedAt": "2024-12-03T14:53:30+01:00",
"modifiedBy": "A-5390-2487",
"deletedAt": null,
"deletedBy": null,
"checkoutOptions": [..],
"checkoutSequence": {..},
"checkoutTexts": [..],
"encryptionKeys": [..],
"tguList": [..],
"_links": [
{
"href": "/services/config",
"rel": "self",
"type": "GET"
}
]
}Checkout options with their options, settings and sequence
In the response the checkoutOptions are returned. A checkoutOption can be a single payment method e.g. iDEAL or Bancontact. It can also reflect a group of payment methods like the card not present payment methods (e.g. Visa or Mastercard) those can be combined into on checkoutOptions 'Creditcard'.
In the above screenshot you can see an example that the card not present payment methods are visualized as one checkoutOption called 'Creditcard / Kaartbetaling'.
Note; only active and fully boarded payment methods are returned as checkout options. If the boarding for a certain payment method is not completed or the payment method is boarded but not activated, it will not be returned. You can view the status of the payment methods in the https://my.pay.nl environment. Navigate to Settings > Sales locations and click on your SL-code.
Single payment method
When a checkoutOption is returned as a single payment method, the following data is returned in the checkoutOptionsobject.
{
"checkoutOptions": [
{
"tag": "PM_10",
"id": 10,
"name": "iDEAL",
"translations": {
"name": {
"nl_NL": "iDEAL"
}
},
"image": "/payment_methods/1.svg",
"paymentMethods": [
{
"id": 10,
"name": "iDEAL",
"description": "Met iDEAL kunt u met een Nederlandse bankrekening vertrouwd, veilig en gemakkelijk betalen via internetbankieren van uw eigen bank.",
"translations": {
"name": {
"nl_NL": "iDEAL"
},
"description": {
"nl_NL": "Met iDEAL kunt u met een Nederlandse bankrekening vertrouwd, veilig en gemakkelijk betalen via internetbankieren van uw eigen bank.",
"en_GB": "With iDEAL you can pay with a Dutch bank account in a familiar, safe and easy way via internet banking with your own bank."
}
},
"image": "/payment_methods/1.svg",
"targetCountries": [ "NL" ],
"options": [
{
"id": "1",
"name": "ABN Amro",
"image": "/issuers/1.svg"
},
{
"id": "2",
"name": "Rabobank",
"image": "/issuers/2.svg"
},
{
"id": "4",
"name": "ING",
"image": "/issuers/4.svg"
},
{
}
],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
}
],
"requiredFields": null
}
]
}We return a checkoutOption with the name 'iDEAL'. This checkout option has one paymentMethod with "id": 10 and with the name 'iDEAL'. In the paymentMethods[].optionsobject we return (if applicable) the options that are available for that specific payment method.
Use this data to collect the information needed to start an order.
If you e.g. want to start an order in the Gateway Redirect Flow and redirect the payer directly to iDEAL's hosted payment page, use the following example in the Order:Create:
{
"amount": {
"value": 2350
},
"paymentMethod": {
"id": 10
},
"serviceId": "SL-2214-1473",
"description": "iDEAL Order",
"reference": "REF1234"
}You can also show a list of issuers (see the data in the paymentMethods[].options object) so that the payer can directly select the right issuer and you can submit the selected issuer during the creation of an order.
Use the id from the paymentMethods[].options object to sent in a direct issuer request with the Order:Create API.
This example shows how to start an order in the Gateway Redirect flow and redirect the payer directly to the ING bank environment.
{
"amount": {
"value": 2350
},
"paymentMethod": {
"id": 10,
"input": {
"issuerId": "4"
}
},
"serviceId": "SL-1234-1234",
"description": "iDEAL + ING Order",
"reference": "REF1234"
}
iDEAL direct issuer requestThe direct issuer request is currently still supported by Currence in iDEAL 2.0, but will be removed in the near future.
Grouped payment methods
When in https://my.pay.nl the payment methods are configured as 'group all to a single card selector' then the following data in the checkoutOptions object is returned.
{
"checkoutOptions": [
{
"tag": "PG_2",
"id": 706,
"name": "Credit- & Debitcards",
"translations": {
"name": {
"de_DE": "Kredit- und Debitkarten",
"en_GB": "Credit- & Debitcards",
"fr_FR": "Cartes de credit",
"nl_NL": "Credit- & Debitcards"
}
},
"image": "/payment_method_groups/CNP.svg",
"paymentMethods": [
{
"id": 706,
"name": "Visa Mastercard",
"description": "Make a secure payment by Creditcard",
"translations": {
"name": {
"nl_NL": "Visa Mastercard"
},
"description": {
"en_GB": "Make a secure payment by Creditcard",
"nl_NL": "Betaal veilig met uw creditcard."
}
},
"image": "/payment_methods/7.svg",
"targetCountries": [],
"options": [],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
},
{
"id": 1705,
"name": "AMEX",
"description": "American Express",
"translations": {
"name": {
"en_GB": "AMEX",
"fr_FR": "AMEX",
"it_IT": "AMEX",
"nl_NL": "AMEX"
},
"description": {
"en_GB": "American Express"
}
},
"image": "/payment_methods/9.svg",
"options": [],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
},
{
"id": 2277,
"name": "Apple Pay",
"description": "With Apple Pay you can safely, easily and privately make purchases in hundreds of thousands of stores, popular apps and online via Safari",
"translations": {
"name": {
"nl_NL": "Apple Pay"
},
"description": {
"en_GB": "With Apple Pay you can safely, easily and privately make purchases in hundreds of thousands of stores, popular apps and online via Safari",
"nl_NL": "Met Apple Pay kun je veilig, eenvoudig en privacyvriendelijk aankopen doen."
}
},
"image": "/payment_methods/114.svg",
"options": [],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
},
{
"id": 2558,
"name": "Google Wallet",
"description": "Google Wallet",
"translations": {
"name": {
"nl_NL": "Google Wallet"
},
"description": {
"en_GB": "Google Wallet",
"nl_NL": "Google Wallet"
}
},
"image": "/payment_methods/176.svg",
"options": [],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
}
],
"requiredFields": []
}
]
}We return a checkoutOption with the name 'Credit- & Debitcards'. In the paymentmethods object the several creditcard options are returned.
Use this data to collect the information needed to start an order. The checkoutOption also has an ID (706), with this ID you can start a generic Credit- & Debitcard transaction. You will be redirected to our hosted payment page.
Terminal List
If you have enabled Card Present and assigned one or more terminals to a sales location, you can show the terminals in the checkout. If there is only one terminal, you can remove the selection or auto select this one. If there are more terminals, you can show a dropdown or terminal selector.
{
"paymentMethods": [
{"id": 1927,
"name": "Terminal Payments",
"description": "Card Present transaction via a POS or Terminal",
"translations": {
"name": {
"en_GB": "Terminal Payments",
"nl_NL": "PIN"
},
"description": {
"en_GB": "Card Present transaction via a POS or Terminal",
"nl_NL": "Pin transacties per betaalterminal"
}
},
"image": "\/payment_methods\/164.svg",
"options": [
{
"code": "TH-####-####",
"name": "Terminal one",
"contractStartDate": "2024-01-01",
"contractEndDate": null,
"paymentTypes": [
"SALE"
],
"terminalBrands": [
{
"id": "2003",
"name": "MasterCard",
"image": "\/terminal_brands\/35.svg"
},
{
...
}
]
},
{
"code": "TH-2457-6241",
"name": "Terminal two",
"contractStartDate": "2025-01-01",
"contractEndDate": null,
"paymentTypes": [
"SALE"
],
"terminalBrands": [
{
"id": "1002",
"name": "Visa Electron",
"image": "\/terminal_brands\/0.svg"
},
{
...
}
]
}
],
"settings": null,
"minAmount": 1,
"maxAmount": 500000
}
],
"requiredFields": null
}
}Settings
For each paymentMethod we return minAmount and maxAmount values. With these values you can validate if the transaction amount exceeds the maxAmount, so that you can give the payer early feedback if the selected paymentMethod is applicable or not.
In the settings object we can also return an ipFilter, with this ipFilter you can filter paymentMethods if your website / app runs on a location where a certain paymentMethod is not applicable.
The following example shows how the ipFilter is returend
{
"checkoutOptions": [
{
"...",
"paymentMethods": [
{
"...",
"settings": {
"ipFilter": {
"type": "deny",
"exceptionList": ["213.215.50.11"]
}
}
}
]
}
]
}
Contact your integration manager if you want to use these ipFilters
RequiredFields
For each checkoutOption we can return requiredFields. Required fields indicates which extra data objects are required (or recommended or optional) to request during the checkout if the payer selects that checkoutOptions.
The following example shows how the required fields are returned.
{
"checkoutOptions": [
{
"...",
"paymentMethods": [
{
"...",
}
],
"requiredFields": [
{
"fieldName": "cardholderName",
"mandatory": "required"
},
{
"fieldName": "cardNumber",
"mandatory": "required"
},
{
"fieldName": "expiryDate",
"mandatory": "required"
},
{
"fieldName": "CVC",
"mandatory": "required"
}
]
}
]
}CheckoutSequence
In the checkoutSequence we return the sequence in which you should display the checkout options. We return a default sequence, and if needed we can return a sequence per country (e.g. in Belgium you may want to show Bancontact as first checkout option, while in the Netherlands you may want to show iDEAL as first checkout option).
The following example shows how the sequence is returned.
{
"checkoutSequence": {
"default": {
"primary": ["PG_2", "PM_10", "PM_436", "PM_136", "PM_1927"],
"secondary": ["PG_4"]
},
"NL": {
"primary": ["PM_10", "PM_436", "PG_2","PM_136", "PM_1927"],
"secondary": ["PG_4"]
},
"BE": {
"primary": ["PM_436", "PM_10", "PG_2","PM_136", "PM_1927"],
"secondary": ["PG_4"]
}
}
Contact your integration manager if you want to use a specific sequence
As can be seen in the example we return in the sequence the checkoutOptions. The checkoutOptions can be identified with their tag. Each tag is unique and refers to a checkoutOption (independed if the paymentMethods in that checkoutOption are returned as single or as grouped).
With primaryand secondarywe indicate if the checkoutOption is a primary checkoutOption or a secondary. Secondary checkoutOptions can be hidden under a 'Show al payment methods' toggle. See screenshot
Translations
An object can have different names in different countries or languages. Based on the language of the payer you can use the right name of the object. You can use the table below to determine the right language of the payer.
| Determination | Description | |
|---|---|---|
| Best | Payer selection | You create an option so that the payer can select the right language, based on the locales. |
| Second | Browser language | Use the locale of the browser |
| Fallback | IP address used by the payer | You can fetch the location of the IP and select the right locale based on the location |
| Fallback | Delivery address | Base the language on the delivery address |
{
"tag": "CNP",
"name": "Debit & Credit cards",
"image": "/payment_method_groups/CNP.svg",
"translations": {
"name": {
"nl_NL": "Kaartbetaling",
"nl_BE": "Kaartbetaling",
"fr_BE": "Paiement par carte",
"en_GB": "Debit- or Creditcard"
}
},
"paymentMethods": [
{
"id": 706,
"name": "Visa Mastercard",
"description": "Make a secure payment by Creditcard",
"translations": {
"name": {
"nl_NL": "Visa Mastercard"
},
"description": {
"en_GB": "Make a secure payment by Creditcard",
"nl_NL": "Betaal veilig met uw creditcard."
}
},
"image": "/payment_methods/7.svg",
"options": [],
"settings": null,
"minAmount": 1,
"maxAmount": 1000000
},
]
}
The default name of this PaymentMethodGroup is "Debit & Credit cards", if the translations.name.locale is set, than we suggest that you use the name based on that field.
Other settings
Encryption keys
TGU list
The TGU List section provides information on Transaction Gateway Units (TGUs) that your payment system can use to process transactions. Here’s how to use this data effectively:
- Primary and Secondary TGUs: Each TGU is listed with an ID, domain, and share. The share value indicates the distribution of transaction traffic across TGUs. Higher share values mean that more transactions will be directed to that TGU. Ensure that your integration prioritizes TGUs with higher shares (e.g., ID 2 with 90% share) for optimal performance.
- Domain Names: The domain field specifies the domain associated with each TGU. Use this domain to direct transaction requests to the appropriate gateway. This helps ensure that your payment processing is routed correctly.
- Fallback Mechanism: Some TGUs may have a status of FALLBACK. These TGUs, like ID 51, should be configured as backup gateways in case the primary and secondary TGUs are unavailable. This redundancy ensures that transactions can still be processed even during outages or maintenance.
- TGU Status Monitoring: The status field indicates whether a TGU is ACTIVE or in FALLBACK mode. Regularly monitor these statuses to dynamically adjust your routing and ensure uninterrupted service.
By properly utilizing the TGU List, you can enhance the reliability and efficiency of your payment processing, ensuring that transactions are handled smoothly across different gateways.
{
"tguList": [
{
"ID": 2,
"share": 90,
"domain": "pay.nl",
"status": "ACTIVE"
},
{
"ID": 52,
"share": 10,
"domain": "payments.nl",
"status": "ACTIVE"
},
{
"ID": 51,
"share": 0,
"domain": "achterelkebetaling.nl",
"status": "FALLBACK"
}
]
}Saving the configuration
To ensure the stability of your service, it's recommended that you store the JSON response of your service location in your database or caching engine. In the event that you lose your configuration setup, you can always retrieve this information again from the TGU or GMS.
Updated about 2 months ago