Adding Open Banking (Self-Hosted mode) as a payment option to your Payment Page requires configuration as outlined below. In Self-Hosted mode you must develop your own user interface.


A detailed overview of the various steps involved in the Self-Hosted flow is provided in the image below.

Self-Hosted Flow
SELF_HOSTED Merchant Flow

To add Open Banking to your payment page you will need to carry out the following steps:

  1. (Optionally) Use your API key to retrieve a merchant access token. (For more on this see retrieving tokens).
  2. Call GET /banks to retrieve a list of all supported banks (see Retrieve Banks) to populate your Bank Selection screen. Where banks have specific branches (bank families), you will also need to call the View Bank Families endpoint. (See the section on Bank Families below for more information on this).
  3. Once the payer has selected a bank, call the /payments endpoint, (see Create Payment). Set the integrationType to SELF_HOSTED, specify the bankId provided by the payer and set the merchantPostAuthUrl (this can be the partner or merchant URL). This will return the aspspAuthUrl, to which you can redirect your PSU.
  4. Your payer interacts with the selected ASPSP to authorise the payment.
  5. The Nuapay TPP posts the payment ID to the partner/merchant URL (merchantPostAuthUrl). See posting details below.
  6. Use Retrieve Payment to determine the final payment status, if required (an optional step) or, alternatively, use Webhooks.

Merchant Post-Auth URL Handling

The merchant merchantPostAuthUrl is sent as follows:

The payload of this request that you need to process includes:

Headers e.g. Content-Type: application/x-www-form-urlencoded
Body e.g. endToEndIdentification=d8e17bf1f3244e5f96a869f9661a2a6&paymentId=gabxl3knbl

Please note that the ‘paymentId’ allows you to look up the payment associated with this callback.

User Interface Guidelines

Note that:

  • In SELF_HOSTED mode you have control over the User Interface design of your application.
  • It is important that your design incorporates links to the Nuapay “Terms of Service” and “About” pages.
  • These pages provide useful information to your PSUs in regard to Nuapay and our license details, as issued by the Financial Conduct Authority (in the UK) and by the ACPR (in the EU).

Please use the following links:

Terms of Service

Bank Families

In STET and Berlin Group:

  • Some ASPSPs are individually configured with a URL and token endpoint per regional bank.
  • For example Credit Agricole in France (which follows the STET specification) has 44 distinct regional banks.
  • Rendering individual regional banks on a user interface is problematic as, in the Credit Agricole example, this would result in 44 individual bank options.
  • In practice this would mean 44 identical icons on a Bank Selection screen (with the PSU having to find his/her specific branch by scrolling though a large list).

When designing your user interface, we recommend that you use the Retrieve Banks and the View Bank Families endpoints so that when a PSU selects a bank that has a number of regional banks (branches) linked to it, the user is provided with an option to select the required branch.

In CHECKOUT mode (i.e. where Nuapay manages the User Interface), the bank/branch selection screens are handled as follows:

  1. The user selects a bank that has a number of branches linked to it (in the call to Retrieve Banks, bankfamilyId is populated for Credit Agricole, for example).
  2. The bank is rendered once, as in the image below and appears like any other bank icon on screen:
    Bank with Bank Family Selected
  3. When the PSU selects this bank, a screen allowing the user to select his/her required branch is displayed:
    Bank Family drop-down
  4. Once the user selects the required branch (bank family), the payment flow continues as normal.