Create the Checkout

To create your own checkout you need to combine the data from the service:getConfig API and the images & icons from the image repository. With some basic JavaScript or Server-Side Scripting you can show the different payment methods based on the order, the payer data and the settings.

Payment methods

In this list you can find all active payment methods with the preferences based on the Merchant and Sales Location. You can loop through this list and display the payment methods. If you have a multilingual checkout, you can show the name of the payment method based on the language of the payer. If the needed language does not exist in the Translations object, fallback to the 'name' object as default.

{
  "paymentMethods": [
    {
      "id": 10,
      "tag": "IDEAL",
      "name": "iDeal",
      "translations": {
        "name": {
          "nl_NL": "iDeal",
          "en_GB": "iDeal"
        }
      },
      "image": "/payment_methods/1.svg",
      "options": [
        {
          "id": "1",
          "name": "ABN Amro",
          "image": "/issuers/1.png"
        },
        {
          "id": "2",
          "name": "Rabobank",
          "image": "/issuers/2.png"
        },
        {
          "id": "4",
          "name": "ING",
          "image": "/issuers/4.png"
        },
        {
          "id": "5",
          "name": "SNS",
          "image": "/issuers/5.png"
        }
      ],
      "settings": {
        "ipFilter": {
          "type": "allow",
          "exceptionList": [
            "192.168.3.1"
          ]
        },
        "requiredFields": [
          {
            "fieldName": "customer.firstName",
            "mandatory": "recommended"
          },
          {
            "fieldName": "customer.lastName",
            "mandatory": "recommended"
          },
          {
            "fieldName": "customer.birthDate",
            "mandatory": "required"
          }
        ]
      }
    }
  }

Payment methods Options

If there is an options list, you can put the option list directly in the checkout. If there is only 1 item in the option list we recommend that you do not show the options in the checkout, but auto select it and send it to the Transaction Gateway Unit with the Transaction:Create API.

Settings: IP filtering

If you receive the IP-filter array for some payment methods you need to show or hide the payment method, based on the ipFilter.type. This feature is used for shared checkouts where a payer can make an eCom transaction (from home) and a POS (instore) transaction in the same software.

{
  "settings": {
    "ipFilter": {
      "type": "allow",
        "exceptionList": [
          "192.168.3.1"
          ]
    }
  }
}

The merchant has configured to show this payment methods for all users, but not for an user with the IP address 192.168.3.1. With this functionality you can also deny the display of a payment method, and put an IP address of your store in the ipFilter.exceptionList. So from a store (or employee) point of view the payment Method can be selected.

Sequence & Relevance

The paymentMethodsSequence object contains information about preferred display of payment methods per country. We suggest that you use the language locale (last 2 characters (e.g. locale: nl_BE, country: BE) or the country of delivery of the product as 'indicator' for the country.

First you check if the selected country is available. If you find the country, you can pick the sequence of the Payment Methods based on the data provided. If you do not find the right country, just fallback to the 'default' settings.

You are free to build the checkout in the look'n feel that you prefer, but we suggest that you show all payment methods with type "relevant" on the screen with icon and names, the payment methods with type "other" can be hidden under a 'Show all payment methods' options ('Toon alle betaalopties' in image below).

{
  "paymentMethodsSequence": {
    "default": [
      {
        "type": "relevant",
        "order": [
          "IDEAL",
          "BANCONTACT"
        ]
      },
      {
        "type": "other",
        "order": [
          "CNP",
          "VOUCHER"
        ]
      }
    ],
    "BE": [
      {
        "type": "relevant",
        "order": [
          "BANCONTACT",
          "IDEAL"
        ]
      },
      {
        "type": "other",
        "order": [
          "CNP",
          "VOUCHER"
        ]
      }
    ]
  }
}

Settings: RequiredFields

Some payment methods requires extra information to perform valid processing. Some fields are recommended, and some are required. If you start a payment without a required field, the transaction processing will fail. Starting a payment without a recommended field might impact the quality of processing or adds more friction to the checkout flow.

{
  "requiredFields": [
    {
      "fieldName": "customer.firstName",
      "mandatory": "recommended"
    },
    {
      "fieldName": "customer.lastName",
      "mandatory": "recommended"
    },
    {
      "fieldName": "customer.birthDate",
      "mandatory": "required"
    }
  ]
}

Object Translations

An object can have different names in different countries or languagea. 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.

{
      "tag": "CNP",
      "name": "Debit & Credit cards",
      "image": "/payment_method_groups/CNP.svg",
      "paymentMethods": [
        "VISA_MASTERCARD",
        "MAESTRO"
      ],
      "translations": {
        "name": {
          "nl_NL": "Kaartbetaling",
          "nl_BE": "Kaartbetaling",      // Flemish
          "fr_BE": "Paiement par carte", // Walloon
          "en_GB": "Debit- or Creditcard"
        }
      }
    }

The default name of this PaymentMethodGroup is "Debit & Credit cards", if the transactions.name.locale is set, than we suggest that you use the name based on that field.

If the user is from The Netherlands, we primary will show (and sort as defined) the Payment Methods that as type 'relevant' as payment methods that can be selected directly. The payment methods with type 'other' will be shown (and sorted as defined) under 'Toon alle betaalopties', if you click on 'Toon alle betaalopties' all Payment Methods will be shown.

Grouped payment methods

You can configure the grouping in the Pay. Admin. We suggest that you group all debit- and credit card payment methods into one group and all voucher and giftcard payment methods into one group. Payment methods that are available in the group 'GENERAL', should not be grouped and needs to be listed as separate payment methods in the checkout.

{
  "paymentMethodGroups": [
    {
      "tag": "GENERAL",
      "name": "General",
      "image": "",
      "paymentMethods": [
        "IDEAL",
        "BANCONTACT"
      ],
      "translations": null
    },
    {
      "tag": "CNP",
      "name": "Debit and Credit cards",
      "image": "/payment_method_groups/CNP.svg",
      "paymentMethods": [
        "VISA_MASTERCARD",
        "MAESTRO"
      ],
      "translations": {
        "name": {
          "nl_NL": "Credit- & Debitcards",
          "en_GB": "Debit and Credit cards"
        }
      }
    },
    {
      "tag": "VOUCHER",
      "name": "Cadeaukaarten",
      "image": "/payment_method_groups/VOUCHER.svg",
      "paymentMethods": [
        "GIFTCARD-YOURGIFT"
      ],
      "translations": {
        "name": {
          "nl_NL": "Cadeaukaarten",
          "de_DE": "Geschenkkärte"
        }
      }
    }
  ]
}

📘

Select the implementation on group level

For the Card not Present flow, that is used to process debit and creditcard payment, and the Voucher flow you can use the <<glossary:Hosted Payment Page>> or the <<glossary:Direct Payment Processing>> method, that is unified for all payment methods in that group.

If a Payment method is grouped, we suggest that you use the following formula to show the grouped payment methods. Use the sequence to show the most relevant first.

Smoother checkout via <<glossary:Direct Payment Processing>>

You can bypass the <<glossary:Hosted Payment Page>> on Card not Present and Voucher transactions. You can integration our API's via Client SIde Encryption via our SDK or use the plain API's if you have the right PCI compliance state.

🦉 Server2Server Card Payment With Tokenisation

🦉 Server2Server Card Payment With Tokenisation