Home    _TEMP_    Open Banking and Instant Open Banking

Tell us about your experience

Open Banking and Instant Open Banking

On this page:
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 certain other European countries to make payments using their bank accounts.

Supported Countries

  • Austria
  • Belgium
  • Denmark
  • Estonia
  • Finland
  • France
  • Germany
  • Hungary
  • Ireland
  • Italy
  • Latvia
  • Lithuania
  • Luxembourg
  • Netherlands
  • Norway
  • Poland
  • Portugal
  • Romania
  • Spain
  • Sweden
  • United Kingdom

Supported Currencies

  • EUR
  • GBP
  • PLN

Integrations

REST API 1.0

Collecting Payment Details

To retrieve a dynamic list of banks and APMs linked to the merchant account for a country:

  1. The customer enters the amount the customer wants to pay on the merchant payment page, selects ‘Online Bank Transfer‘ or ‘Instant Bank Transfer’, and then selects ‘Pay’ or the equivalent option.
  2. Send a ‘/getSessionToken‘ request to generate a 'sessionToken'.
  3. Send a /getMerchantPaymentMethods' request, including the relevant 'countryCode' to narrow the results.

To narrow the list of banks displayed to the customer, first determine the country in which the customer may have a bank account, then use the available information or ask the customer to select a country.

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>"
}

A successful request returns the APMs and banks linked to the merchant account for the specified country.

Example '/getMerchantPaymentMethods' 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": []
        }
      ]
    }
  ]
}
  1. Extract the banks returned for:
    • 'apmgw_Open_Banking'
    • 'apmgw_Instant_Open_Banking'
  2. Display the list of banks for the customer to select the bank that holds the account from which they want to pay.
    The bank names are returned in 'fields.listValues.caption'.
  3. After the customer selects a bank, retrieve the fields that the customer must provide.
    The required fields are returned in 'fields.listValues.mandatoryFields'. The values in this array correspond to the values in 'fields.name'.
  4. After the customer enters the information required by the bank, display the amount, currency, and the following message for the customer to approve:

    By pressing the deposit button, 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 details will be used only when necessary, such as when processing a refund.

Privacy Policy and the Terms must link to https://token.io/web-app-terms.

Output Parameters

'/getMerchantPaymentMethods' Output Parameters
ParameterDescriptionExamples
paymentMethodIdentifier of a Payment Method.apmgw_Open_Banking
fieldsA 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.nameIdentifier of the field.ob_account_number
ob_sort_code
ob_iban
ob_bank_id
fields.listValuesA 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
Example 'fields' Array Structure with 'mandatoryFields'
"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)]
  ]
]

Sending a Payment Request

To perform a future payout, use the same 'userTokenId' generated during the payment transaction.

  1. Use the data entered by the customer to send a ‘/payment‘ request. Include the 'alternativePaymentMethod' class containing the relevant Open Banking parameters.
    • For 'paymentMethod' set to 'apmgw_Instant_Open_Banking', the bank ID parameter must be 'instantOb_bankId'.
    • For 'paymentMethod' set to 'apmgw_Open_Banking', the bank ID parameter must be 'ob_bank_id'.

If the selected bank does not require 'ob_iban', do not include 'ob_iban' in the '/payment' request. Including 'ob_iban' may cause the transaction to fail.

Example '/payment' Request for 'apmgw_Instant_Open_Banking' with Mandatory Parameters
{
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "USD",
  "amount": "1",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Instant_Open_Banking",
      "instantOb_bankId": "ngp-bbru",
      "ob_iban": "BE96315678901234"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "BE"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "BE"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

A successful request returns a 'paymentOption.redirectUrl' for the selected bank.

Example '/payment' Response
{
  "reason": "",
  "orderId": "36298881",
  "transactionStatus": "REDIRECT",
  "clientRequestId": "GF1XTXTBM",
  "internalRequestId": 17817111,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "redirectUrl": "<bank redirect URL>",
    "userPaymentOptionId": "8061731",
    "card": {}
  },
  "sessionToken": "<sessionToken>",
  "userTokenId": "2J6QZH3UF9E2",
  "status": "SUCCESS"
}
  1. Redirect the customer to the returned 'redirectUrl' so the customer can enter their credentials and complete the payment.
  2. Allow the APM provider to process the request.
  3. After the transaction is processed, receive a Direct Merchant Notification (DMN) containing the transaction result at 'urlDetails.notificationUrl'. Nuvei recommends including this parameter in the '/payment' request.

Sending a Payout Request

A payout can be performed only after a 'userTokenId' was generated by a previous payment transaction.


To perform a payout, use one of the following options:
  1. Send a https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#payout'/payout' request. Include the 'userPaymentOptionId' returned by the payment transaction. See Payouts Using an Existing UPO for an example.
  2. Collect the account details from the deposit and use them with 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 return the IBAN in the response.


After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) containing the transaction result to 'urlDetails.notificationUrl'. Nuvei recommends including this parameter in the '/payout' request.

REST API 2.0

Collecting Payment Details

Before submitting an Open Banking or Instant Open Banking payment, collect the bank selected by the customer and any other account details required by that bank.

For both REST 2.0 payment methods, include the bank identifier in 'paymentOption.alternativePaymentMethod.data.bank'.

Open Banking Payment Method

Set 'paymentOption.alternativePaymentMethod.name' to 'openBanking':

{
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "openBanking",
      "data": {
        "bank": "<customer-selected bank>"
      }
    }
  }
}

Instant Open Banking Payment Method

Set 'paymentOption.alternativePaymentMethod.name' to 'instantOpenBanking':

{
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "instantOpenBanking",
      "data": {
        "bank": "<customer-selected bank>"
      }
    }
  }
}

For both payment methods, include 'bank' in 'paymentOption.alternativePaymentMethod.data'.

If the selected bank does not require 'iban', do not include 'iban' in the '/payments' request. Sending 'iban' if it is not required by the selected bank may cause the transaction to fail.

Sending a Payment Request

To perform an Open Banking or Instant Open Banking payment using REST 2.0:

  1. Collect the bank details entered or selected by the customer.
  2. Submit a '/payments' request.
  3. Include the 'paymentOption.alternativePaymentMethod' object in the request.
  4. Set 'paymentOption.alternativePaymentMethod.name' to:
    • 'instantOpenBanking' for Instant Open Banking.
    • 'openBanking' for Open Banking.
  5. Include the bank identifier and any additional details required by the selected bank under 'paymentOption.alternativePaymentMethod.data'.
    If succesful, a successful response is received containing 'result.status' set to 'redirect' and a 'redirectUrl'.
  6. Redirect the customer to the returned bank URL.
  7. Allow the customer to authenticate with the bank and to complete the payment authorization process.
  8. Receive the transaction result via a webhook sent to 'urlDetails.webhookUrl'.

Alternative Payment Method Parameters

For Open Banking and Instant Opening Banking methods, 'bank' is the bank identifier and must be included under 'paymentOption.alternativePaymentMethod.data'.

Example Open Banking
{
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "openBanking",
      "data": {
        "bank": "<customer-selected bank>"
      }
    }
  }
}
Example Instant Open Banking
{
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "instantOpenBanking",
      "data": {
        "bank": "<customer-selected bank>"
      }
    }
  }
}

If the selected bank does not require 'iban', do not include 'iban' in the '/payments' request. Sending 'iban' if it is not required by the selected bank may cause the transaction to fail.

Example '/payments' Request for 'instantOpenBanking'
{
  "processingEntityId": "<your processing entity ID>",
  "amount": 10,
  "currency": "EUR",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "instantOpenBanking",
      "data": {
        "bank": "Caixa Bank",
        "accountNumber": "235442",
        "iban": "133413",
        "sortCode": "421341",
        "holderName": "asd"
      }
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer IP address>"
  },
  "urlDetails": {
    "successUrl": "https://www.example.com/payment-success",
    "failureUrl": "https://www.example.com/payment-failure",
    "pendingUrl": "https://www.example.com/payment-pending",
    "cancelUrl": "https://www.example.com/payment-cancelled",
    "webhookUrl": "https://www.example.com/webhooks/payments"
  },
  "buyerDetails": {
    "buyerId": "<customer ID>",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+441234567890",
    "billingAddress": {
      "address": "1 Main Street",
      "city": "London",
      "zip": "AB12 3CD",
      "countryCode": "GB"
    }
  }
}

The fields required under 'paymentOption.alternativePaymentMethod.data' depend on the selected bank. Include only the fields required by that bank.

Example '/payments' Response

A successful Open Banking payment initiation returns a 'paymentId', 'result.status' set to 'redirect', and a 'redirectUrl'.

{
  "paymentId": "<payment ID>",
  "result": {
    "status": "redirect"
  },
  "redirectUrl": "<selected bank authorization URL>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "instantOpenBanking"
    }
  },
  "paymentTokenId": "<payment token ID>"
}

Redirect Processing

A successful '/payments' request returns a 'redirectUrl' for the selected bank.

Redirect the customer to the returned URL so the customer can authenticate with the bank and complete the payment authorization process.

After the customer completes the bank authentication flow, the APM provider processes the payment request.

Payment Webhook Processing

After the transaction is processed, Nuvei sends a webhook notification containing the transaction result to the URL specified in 'urlDetails.webhookUrl'.

Nuvei strongly recommends providing 'urlDetails.webhookUrl' in the '/payments' request.

Sending a Payout Request

Initiate an Open Banking payout in one of the following ways:

      • Supply the customer’s bank details through 'paymentOption.alternativePaymentMethod'.
      • Supply the 'paymentTokenId' of a previously stored Open Banking payment method via 'paymentOption.paymentToken'.

Initiate Payout with 'alternativePaymentMethod'

Use this option to provide the customer’s bank details directly in the payout request.

Example Payout Request Using 'alternativePaymentMethod'
{
  "processingEntityId": "<your processing entity ID>",
  "amount": 10,
  "currency": "EUR",
  "paymentOption": {
    "alternativePaymentMethod": {
      "name": "instantOpenBanking",
      "data": {
        "bank": "Caixa Bank",
        "holderName": "asd",
        "accountNumber": "235442",
        "sortCode": "421341",
        "iban": "133413"
      }
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer IP address>"
  },
  "urlDetails": {
    "webhookUrl": "https://www.example.com/webhooks/payouts"
  },
  "buyerDetails": {
    "buyerId": "<customer ID>",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+441234567890",
    "billingAddress": {
      "address": "1 Main Street",
      "city": "London",
      "zip": "AB12 3CD",
      "countryCode": "GB"
    }
  }
}

Include only the bank details required by the selected bank. If the selected bank does not require 'iban', do not include it in the payout request.

Initiate Payout with 'paymentTokenId'

Use this option to initiate a payout to a previously stored Alternative Payment Method account. Include the stored token in 'paymentOption.paymentToken.paymentTokenId'.

This option uses the Open Banking account previously stored through tokenization.

Example Payout Request with 'paymentTokenId'
{
  "processingEntityId": "<your processing entity ID>",
  "amount": 10,
  "currency": "EUR",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "abc123def456ghi789jkl012mno345pq"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer IP address>"
  },
  "urlDetails": {
    "webhookUrl": "https://www.example.com/webhooks/payouts"
  },
  "buyerDetails": {
    "buyerId": "<customer ID>",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]"
  }
}

Payout Webhook Processing

After the payout transaction is processed, Nuvei sends a webhook notification containing the transaction result to the URL specified in 'urlDetails.webhookUrl'.

Nuvei recommends providing 'urlDetails.webhookUrl' in a payout request so that the merchant system receives asynchronous payout status updates.


Web SDK

Collecting Payment Details

To retrieve a dynamic list of banks and APMs linked to the merchant account for a country:

  1. The customer enters the amount the customer wants to pay on the payment page, selects ‘Online Bank Transfer’ or ‘Instant Bank Transfer’, and then selects ‘Pay’ or the equivalent option.
  2. Send an ‘/openOrder‘ request to generate a 'sessionToken'.
  3. Instantiate a Web SDK session by sending a ‘SafeCharge()’ request that includes the 'sessionToken'.
  4. Call the ‘getAPMs()‘ method, including the relevant 'countryCode' to narrow the results.

To narrow the list of banks displayed to the customer, first determine the country in which the customer may have a bank account. Use the available information or ask the customer to select a country.

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

The response returns the APMs linked to the merchant account for the specific 'countryCode'.

Example '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": []
        }
      ]
    }
  ]
}
  1. Extract the banks returned for:
    • 'apmgw_Open_Banking'
    • 'apmgw_Instant_Open_Banking'
  2. Display the available banks so the customer can select the bank that holds the account from which they want to pay.
  3. Collect the fields identified in 'fields.listValues.mandatoryFields' for the selected bank.
  4. Display the amount, currency, and the following message before allowing the customer to continue:

    By pressing the deposit button, 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 details will be used only when necessary, such as when processing a refund.

Privacy Policy and the Terms must link to https://token.io/web-app-terms.

Output Parameters

'getAPMs()' Output Parameters

ParameterDescriptionExamples
paymentMethodIdentifier of a Payment Method.apmgw_Open_Banking
fieldsA 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.nameIdentifier of the field.ob_account_number
ob_sort_code
ob_iban
ob_bank_id
fields.listValuesA 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
Example 'fields' Array Structure with 'mandatoryFields'
"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)]
  ]
]

Sending a Payment Request

  1. Use the data entered by the customer to send a ‘createPayment()‘ request. Include the 'alternativePaymentMethod' object containing the relevant Open Banking parameters.
    • If 'paymentMethod' has a value of 'apmgw_Instant_Open_Banking', the bank ID parameter must be 'instantOb_bankId'.
    • If 'paymentMethod' has a value of 'apmgw_Open_Banking', the bank ID parameter must be 'ob_bank_id'.

If the selected bank does not require 'ob_iban', do not include 'ob_iban' in the 'createPayment()' request. Including 'ob_iban' may cause the transaction to fail.

Example 'createPayment()' Request for 'apmgw_Instant_Open_Banking' with a Mandatory Parameter
sfc.createPayment({
  sessionToken: "<sessionToken>",
  paymentOption: {
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Instant_Open_Banking",
      instantOb_bankId: "ngp-bbru",
      ob_iban: "BE96315678901234"
    }
  },
  deviceDetails: {
    ipAddress: "<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    email: "[email protected]",
    country: "BE"
  },
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    email: "[email protected]",
    country: "BE"
  }
}, function(res) {
  console.log(res);
});
Example 'createPayment()' Request for 'apmgw_Open_Banking' with No Mandatory Parameter
sfc.createPayment({
  sessionToken: "<sessionToken>",
  paymentOption: {
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Open_Banking",
      ob_bank_id: "ngp-ingba"
    }
  },
  deviceDetails: {
    ipAddress: "<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    email: "[email protected]",
    country: "BE"
  },
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    email: "[email protected]",
    country: "BE"
  }
}, function(res) {
  console.log(res);
});
  1. If the 'createPayment()' request is successful, the system opens a new tab or an IFrame and redirects the customer to the selected bank site.
  2. Allow the customer to enter credentials and complete the payment.
  3. Verify the response as described in Web SDK Response Verification.

Withdrawal Flow

For information about the Web SDK withdrawal flow, see Withdrawal.

Simply Connect

Collecting Payment Details

  1. Initiate a Session by sending an https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#openOrder'/openOrder' request. This authenticates the merchant, creates an order in the Nuvei system, and returns a 'sessionToken'.
  2. Create an HTML Placeholder to instantiate the Web SDK with the 'sessionToken' returned by '/openOrder'.
  3. Display a window in which the customer selects a bank, enters the IBAN if required by the bank, accepts the terms and conditions, and enters an amount.

Simply Connect allows the customer to enter the bank name directly. The search begins after the customer starts entering characters.

Sending a Payment Request

Use an IFrame to redirect the customer to the selected bank. The customer can then enter credentials and complete the payment transaction.

Testing

A merchant can test specific APMs using the following bank and test data.

Commerzbank (DE)
  • SEPA and SEPA Instant
  • Does not return a refund account
KD Bank (DE – Embedded Flow)
  • Credentials:
    • 'psuId': 'VRK1234567890ALL'
    • 'password': 'password'
    • 'SCA': '942: mobile TAN'
    • 'pin': '123456'
NatWest (UK)
  • FPS
  • Returns the refund account and name
  • Credentials:
    • '123456789012'
Alior (PL)
  • Elixir and SEPA
  • Does not return a refund account
  • Credentials:
    • '60370698'
    • '12345678'
BBVA (ES)
  • Credentials:
    • 'user1'
    • '1234'
    • '123456'

Last update iconLast modified October 2026