Introduction

This guide provides steps to integrate Open Banking as a Nuvei APM (alternative payment method) into your payment flows, and how to accept payments (deposits) from your customers.

Nuvei Environments

You can process Open Banking APM deposit (payment) transactions using Nuvei server-to-server REST APIs or Nuvei Web SDK calls.

Prerequisites and Notes

• This guide assumes you have completed all account set up prerequisites, and are ready to integrate the Open Banking APM payment method into your payment flow.
• Nuvei handles Open Banking transactions in “redirection mode”.
• The system sends DMNs (direct merchant notifications) to ensure that you receive the results of transaction processing. You need to include a destination DMN notificationUrl in all /payment requests. You can either set the notification URL hard coded on the CPanel, or send it in each request.
• The scope of this guide describes accepting customer payments using customer payment methods, that are not initially stored as UPOs in our system. (A UPO (user payment option) is an encrypted customer payment method record stored in the Nuvei system, representing a customer bank account or other payment method.)
• Test credentials and testing scenarios can be provided by Nuvei if necessary. You can contact Nuvei support for assistance.

Supported Countries

• Austria
• Belgium
• Estonia
• France
• Germany
• Hungary
• Latvia
• Lithuania
• Netherlands
• Poland
• Portugal
• Spain
• United Kingdom

Supported Currencies

• EUR
• GBP
• PLN

Collecting Payment Details

1. Follow the instructions in these steps:
   Click a tab to open…
   • For REST API
   • For Web SDK
   • For Checkout

   Retrieve a dynamic list of banks and APMs linked to your merchant account, for that country:

   1. The payment flow begins when your customer enters the amount they wish to pay on your payment page, selects Open Banking and clicks the “Pay” button (or equivalent).
   2. Send a /getSessionToken request, which generates a sessionToken.
   3. Call the /getMerchantPaymentMethods method and include the relevant countryCode parameter to narrow down results returned.
      To narrow down the list of banks to display to the customer, first determine the country in which the customer may have their bank account, either by deciding for yourself, based on the available information, or by asking the customer.

      
      

      Example /getMerchantPaymentMethods Request

      {
        "sessionToken": "<sessionToken from getSessionToken>",
        "merchantId":"<your merchantId>",
        "merchantSiteId":"<your merchantSiteId>",
        "clientRequestId": "<unique request ID in merchant system>",
        "currencyCode":"USD",
        "countryCode":"BE",
        "type":"DEPOSIT",
        "languageCode":"eng",
        "timeStamp":"<YYYYMMDDHHmmss>",
        "checksum":"<calculated checksum>"
      }

   Retrieve a dynamic list of banks and APMs linked to your merchant account, for that country:

   1. The payment flow begins when your customer enters the amount they wish to pay on your payment page, selects Open Banking and clicks the “Pay” button (or equivalent).
   2. Send an /openOrder request, which generates a sessionToken.
   3. Instantiate a Web SDK session by sending a SafeCharge() request and include the sessionToken.
   4. Now you can call the getAPMs() Web SDK method, and include the relevant countryCode to narrow down results returned.
      To narrow down the list of banks to display to the customer, first determine the country in which the customer may have their bank account, either by deciding for yourself, based on the available information, or by asking the customer.

      
      

      Example getApms() Request

      sfc.getApms({
        "currencyCode": "USD",
        "countryCode": "BE",
        "languageCode": "en"
        }, 
      
      function (res) {
        console.log(res)
      })

      The response returns all the APMs linked to your merchant account, for that countryCode.

   1. Initiate a Session This authenticates and sets up an order in the Nuvei system, by sending an /openOrder request, and returns a sessionToken.
   2. Create an HTML Placeholder This instantiates the Web SDK with the sessionToken received from the server call to /openOrder.
   3. Collect the bank and transaction details by displaying a popup for the customer to select a bank, enter the IBAN (if mandatory for the bank), accept the Terms and Conditions, and enter the amount.
   4. Use an IFrame to redirect the customer to their selected bank, so they can enter their credentials and complete the payment transaction.
      (END OF CHECKOUT FLOW)

   For REST API

   Retrieve a dynamic list of banks and APMs linked to your merchant account, for that country:

   1. The payment flow begins when your customer enters the amount they wish to pay on your payment page, selects Open Banking and clicks the “Pay” button (or equivalent).
   2. Send a /getSessionToken request, which generates a sessionToken.
   3. Call the /getMerchantPaymentMethods method and include the relevant countryCode parameter to narrow down results returned.
      To narrow down the list of banks to display to the customer, first determine the country in which the customer may have their bank account, either by deciding for yourself, based on the available information, or by asking the customer.

      
      

      Example /getMerchantPaymentMethods Request

      {
        "sessionToken": "<sessionToken from getSessionToken>",
        "merchantId":"<your merchantId>",
        "merchantSiteId":"<your merchantSiteId>",
        "clientRequestId": "<unique request ID in merchant system>",
        "currencyCode":"USD",
        "countryCode":"BE",
        "type":"DEPOSIT",
        "languageCode":"eng",
        "timeStamp":"<YYYYMMDDHHmmss>",
        "checksum":"<calculated checksum>"
      }

   For Web SDK

   Retrieve a dynamic list of banks and APMs linked to your merchant account, for that country:

   1. The payment flow begins when your customer enters the amount they wish to pay on your payment page, selects Open Banking and clicks the “Pay” button (or equivalent).
   2. Send an /openOrder request, which generates a sessionToken.
   3. Instantiate a Web SDK session by sending a SafeCharge() request and include the sessionToken.
   4. Now you can call the getAPMs() Web SDK method, and include the relevant countryCode to narrow down results returned.
      To narrow down the list of banks to display to the customer, first determine the country in which the customer may have their bank account, either by deciding for yourself, based on the available information, or by asking the customer.

      
      

      Example getApms() Request

      sfc.getApms({
        "currencyCode": "USD",
        "countryCode": "BE",
        "languageCode": "en"
        }, 
      
      function (res) {
        console.log(res)
      })

      The response returns all the APMs linked to your merchant account, for that countryCode.

   For Checkout

   1. Initiate a Session This authenticates and sets up an order in the Nuvei system, by sending an /openOrder request, and returns a sessionToken.
   2. Create an HTML Placeholder This instantiates the Web SDK with the sessionToken received from the server call to /openOrder.
   3. Collect the bank and transaction details by displaying a popup for the customer to select a bank, enter the IBAN (if mandatory for the bank), accept the Terms and Conditions, and enter the amount.
   4. Use an IFrame to redirect the customer to their selected bank, so they can enter their credentials and complete the payment transaction.
      (END OF CHECKOUT FLOW)

   The response from the request returns a list of bank names (in the fields.listValues.caption value) for you to display to the customer:

   Example /getMerchantPaymentMethods (or getApms()) Response

   {
     "paymentMethod":"apmgw_Instant_Open_Banking",
     "paymentMethodDisplayName":[
       
     ],
     "isDirect":"false",
     "countries":[
       "BE"
     ],
     "currencies":[
       "USD"
     ],
     "fields":[
       {
         "name":"ob_account_number",
         "type":"text",
         "caption":[
           {
             "language":"eng",
             "message":"Account Number"
           }
         ]
       },
       {
         "name":"ob_sort_code",
         "type":"text",
         "caption":[
           {
             "language":"eng",
             "message":"Sort Code"
           }
         ]
       },
       {
         "name":"ob_iban",
         "type":"text",
         "caption":[
           {
             "language":"en",
             "message":"IBAN"
           }
         ]
       },
       {
         "name":"instantOb_bankId",
         "type":"text",
         "caption":[
           {
             "language":"eng",
             "message":"Bank ID"
           }
         ],
         "listValues":[
           {
             "code":"ngp-bbru",
             "caption":"NextGenPSD2",
             "mandatoryFields":[
               "ob_iban"
             ]
           },
           {
             "code":"ngp-ingba",
             "caption":"ING Austria",
             "mandatoryFields":[
               
             ]
           }
         ]
       }
     ]
   }

2. Extract a list of all the banks returned for these APMs: apmgw_Open_Banking and apmgw_Instant_Open_Banking.
   /getMerchantPaymentMethods (or getApms()) Output Parameters

   Parameter	Description	Examples
   paymentMethod	Identifier of a Payment Method.	apmgw_Open_Banking apmgw_Instant_Open_Banking
   fields	A list of possible input fields required by a payment method provider for this Payment Method, as well as a list of mandatory input fields per fields.listValues value (in the form of a key-value pairs to be used to populate a dropdown input field).	-
   fields.name	Identifier of the field.	ob_account_number ob_sort_code ob_iban ob_bank_id instantOb_bankId
   fields.listValues	A list of values of the fields.name (to be used to populate a dropdown input field).	-
   fields.listValues .code	Bank code used for sending the payment request. Note: For the "apmgw_Instant_Open_Banking" APM the bank id parameter must be: "instantOb_bankId" For the "apmgw_Open_Banking" APM the bank id parameter must be: "ob_bank_id"	ngp-bbru ngp-ingba
   fields.listValues .caption	Bank name for display on the UI.	NextGenPSD2 ING Austria
   fields.listValues .mandatoryFields	A list of fields.names, which are mandatory for this fields.listValues value (to be used to populate a dropdown input field).	ob_account_number ob_sort_code ob_iban

3. Display this list of banks, for the customer to choose the bank that holds the account they wish to pay from. The names of the banks are contained in the fields.listValues.caption value, contained in the fields.listValues array output parameter.
4. After the customer selects a bank, retrieve the list of mandatory fields that customer must enter. The mandatory fields required for the selected bank are contained in the fields.listValues.mandatoryFields value of this array. The values in this array correspond to the values in the fields.name output parameter.
   
   

   fields array structure with mandatoryFields from the /getMerchantPaymentMethods (or getApms()) Response

   "fields"[
     "name" (String, 45),
     "type" (String, 45),
     "validationMessage" 
       ["language" (String, 2), "message" (String, 400)],
     "caption" 
       ["language" (String, 2), "message" (String, 400)],
     "listValues" [
       "code" (String, 255),
       "caption" (String),
       "mandatoryFields" 
         [(String, 45)]
     ]
   ]

5. After the customer enters the information required by their bank, display this following important checkbox for the customer to approve before allowing them to continue:
   

   “By continuing, you agree to the Privacy Policy and the Terms of Nuvei’s bank connectivity provider. You will be asked by your bank to share your account details, these will only be used when necessary such as processing a refund.“

   “Privacy Policy and the Terms” must be a hyperlink to this URL: https://token.io/web-app-terms.

Sending the Payment Request

Click a tab to open…