Attributes

• METHOD TYPEReal-Time Bank Transfer
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

Introduction

The Open Banking and Instant Open Banking APMs enable customers of participating banks in the EU and in certain other European countries to make payments using their bank accounts.

Supported Countries

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

Supported Currencies

• EUR
• GBP
• PLN

Collecting Payment Details

1. Follow the instructions in these steps:
   Press tab to open…
   • REST API
   • Web SDK
   • Simply Connect

   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 “Online Bank Transfer” or “Instant Bank Transfer” and presses Pay (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 “Online Bank Transfer” or “Instant Bank Transfer”, and presses Pay (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 the 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 pop-up 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.
      
      Simply Connect allows the customer to enter the bank name directly; the search is triggered once you start to enter characters.

      
      
      (END OF SIMPLY CONNECT FLOW)

   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 “Online Bank Transfer” or “Instant Bank Transfer” and presses Pay (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>"
      }

   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 “Online Bank Transfer” or “Instant Bank Transfer”, and presses Pay (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 the 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.

   Simply Connect

   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 pop-up 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.
      
      Simply Connect allows the customer to enter the bank name directly; the search is triggered once you start to enter characters.

      
      
      (END OF SIMPLY CONNECT 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":"en",
             "message":"Account Number"
           }
         ]
       },
       {
         "name":"ob_sort_code",
         "type":"text",
         "caption":[
           {
             "language":"en",
             "message":"Sort Code"
           }
         ]
       },
       {
         "name":"ob_iban",
         "type":"text",
         "caption":[
           {
             "language":"en",
             "message":"IBAN"
           }
         ]
       },
       {
         "name":"instantOb_bankId",
         "type":"text",
         "caption":[
           {
             "language":"en",
             "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
   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
   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_online_bank_transfer" 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 the amount, currency, and the 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

Press a tab to open…

Sending the Payout Request

To perform a payout, you have the following options:

• Send a /payout request and include the userPaymentOptionId from the payment transaction. Press here for an example.
• Collect account details from the deposit and use your logic to use them via another payment method such as SEPA Payouts. For example, take the IBAN from the DMN and create a SEPA Payouts /payout request.
  
  Some banks do not send the IBAN in the response.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

Testing

Merchants can test these APMs using the following banks and test data.

Commerzbank (DE)

• SEPA and SEPA Instant
• Does not return refund account

KD bank (DE – embedded flow)

Credentials:

• psuId: VRK1234567890ALL
• password: password
• SCA: 942: mobile TAN
• pin: 123456

Natwest (UK)

• FPS
• Returns refund account and name

Credentials: 123456789012

Alior (PL)

• Elixir & SEPA
• Does not return refund account

Credentials:

• 60370698
• 12345678

BBVA (ES)

Credentials:

• user1
• 1234
• 123456