Quick Start PISP Initiation | Nuapay Developer Hub

Quick Start - Let's make an Open Banking payment!

Overview

You can interact with Nuapay Open Banking PISP via one of the following integration models:

REDIRECT
SELF-HOSTED
SELF-HOSTED-CALLBACK
CHECKOUT

See PISP Implementation Options for more on these options.

Depending on the setup that best suits your business needs, the API calls that you need to make and how you process the responses vary.

A Note on Authentication

When interacting with the Nuapay Endpoints you must be authenticated via one of the following:

API Keys
OAuth Tokens

For more details on this see the section on API Key Authentication or OAuth Tokens in the Token Management section.

Postman Collection

We highly recommend that you use Postman to test our PISP APIs on the Sandbox environment. Download it for free from www.postman.com/downloads.

Tip: Unlike the Swagger specification, the Postman Collection we’ve created allows you to work with the APIs directly in our Sandbox environment. While our Swagger file is a formal definition of our PISP service, which you can use to generate client libraries, the Postman Collection logically groups the services together so that you can see the business logic of why (and when) to call the various PISP endpoints.

You will need to download:

A Collection .JSON file.
An Environment .JSON file.

Download the files from Github here: Postman Collections on Github

If you are new to Postman and are unsure how to import the collection, please see the README.

Once you have downloaded the Collection and the Environment files:

Open Postman.
Import the collection files.
Specify your API Key.

Tip: If you don’t already have one, contact our Support Team to request an API Key: api.support@nuapay.com.

Redirect Mode

Note: CHECKOUT and REDIRECT is only available for merchants who want to process GBP payments; if you want to process EUR transactions then you must go with either the SELF-HOSTED or SELF-HOSTED-CALLBACK integration.

If you are acting as a partner:

You will need to retrieve your merchant’s identifier.
If you want to set up a payment for Merchant X but do not have the merchant identifier and need to query the GET /organisations service to retrieve it as a first step.

Call the following services in this order

GET	Organisations	(Optional - For Partner users only) Use this service to retrieve the list of organisations/merchants under you as the Partner entity. Use your Partner-level API Key Store the required merchant identifier
POST	Access Token	(Optional) For merchants, use this service to retrieve an OAuth token. For partners: Retrieve an OAuth token for your required merchant Pass your API Key and merchantId Set scope = `openbanking_pisp`
POST	Create Payment	Note that: The `integrationType` must be set to REDIRECT The `merchantPostAuthUrl` must be provided The Create Payment service generates an Open Banking payment object Returns a unique `userInterfacePaymentId` Initial payment status is PENDING The URI must be passed to the PSU Bank Selection screen launches in a new browser window/tab when the user clicks the link
-	-	The PSU selects a bank and is redirected to authenticate and approve the payment on that ASPSP's online banking portal.
GET	Retrieve Payment Status	Retrieve the status of the payment.

For more details on this see the Redirect Setup.

Self-Hosted

Call the following services in this order:

GET	Organisations	(Optional - For Partner users only) Use this service to retrieve the list of organisations/merchants under you as the Partner entity. Use your Partner-level API Key Store the required merchant identifier
POST	Access Token	(Optional) For merchants, use this service to retrieve an OAuth token. For partners: Retrieve an OAuth token for your required merchant Pass your API Key and merchantId Set scope = `openbanking_pisp`
GET	Retrieve Banks	Use this service to give your PSU a list of banks from which to choose.
-	-	The PSU selects an ASPSP.
POST	Create Payment	Once the user selects an ASPSP, pass its `bankId` in the payment request. Note that: The `integrationType` must be set to SELF_HOSTED The `merchantPostAuthUrl` must be provided The Create Payment service generates an Open Banking payment object Returns a unique `userInterfacePaymentId` Initial payment status is PENDING The URI must be passed to the PSU Bank Selection screen launches in a new browser window/tab when the user clicks the link
-	-	The PSU is redirected to authenticate and approve the payment on that ASPSP's online banking portal. Once the user approves or declines the payment he/she is redirected to the `merchantPostAuthUrl` (as referenced in the Create Payment call).
GET	Retrieve Payment Status	Retrieve the status of the payment.

For more details on this see the Self-Hosted Setup section.

Self-Hosted Callback

Call the following services in this order:

GET	Organisations	(Optional - For Partner users only) Use this service to retrieve the list of organisations/merchants under you as the Partner entity. Use your Partner-level API Key Store the required merchant identifier
POST	Access Token	(Optional) For merchants, use this service to retrieve an OAuth token. For partners: Retrieve an OAuth token for your required merchant Pass your API Key and merchantId Set scope = `openbanking_pisp`
GET	Retrieve Banks	Use this service to give your PSU a list of banks from which to choose.
-	-	The PSU selects an ASPSP.
POST	Create Payment	Once the user selects an ASPSP, pass its `bankId` in the payment request. Note that: The `integrationType` must be set to SELF_HOSTED_CALLBACK The `merchantPostAuthUrl` must be provided The Create Payment service generates an Open Banking payment object Returns a unique `userInterfacePaymentId` Initial payment status is PENDING The URI must be passed to the PSU Bank Selection screen launches in a new browser window/tab when the user clicks the link
-	-	The PSU is redirected to authenticate and approve the payment on that ASPSP's online banking portal. Once the user approves or declines the payment he/she is redirected to the `merchantPostAuthUrl` (as referenced in the Create Payment call).
POST	Access Token	Pass your merchant API Key with the required scope = `openbanking_callback` to retrieve an OAuth access token.
POST	Forward Payment Callback	In this mode as the callback/redirect from the ASPSP does not go directly to the Nuapay TPP, it is required to forward the details via this service; you must pass your `callbackAccessToken` and the `callbackParams`
GET	Retrieve Payment Status	Retrieve the status of the payment.

For more details, see Self-Hosted-Callback Payment Page Setup.

Checkout Mode

Tip: The CHECKOUT integration can be problematic in the mobile flow on some devices. If you want to use the Nuapay UI, we recommend that you use the REDIRECT integration to avoid any issues.

Note: CHECKOUT and REDIRECT are only available for merchants who want to process GBP payments; if you want to process EUR transactions then use the SELF-HOSTED integration.

As a partner, you will need to interact with the Nuapay Open Banking services on behalf of your merchants. In this example we will assume that you want to set up a payment for Merchant X but do not have the merchant identifier and need to query the GET /organisations service to retrieve it as a first step.

Call the following services in this order:

GET	Organisations	(Optional) For Partners Use this service to retrieve the list of organisations/merchants under your entity. Use your Partner-level API Key and store the required merchant identifier.
POST	Access Token	Use this service to retrieve an OAuth token for the required merchant. Pass your API Key and merchantId with scope = `openbanking_pisp`.
POST	Create Payment	Call this service with the merchant access token; the Create Payment service generates an Open Banking payment object, returning a unique `userInterfacePaymentId` with an (initial) status of `PENDING`. Apply the Nuapay-provided JS and CSS on your page to render the Bank Selection screen for your merchant’s payers.
-	-	The PSU selects a bank (also referred to as the ASPSP) and is redirected to authenticate and approve the payment on that ASPSP’s online banking portal.
GET	Retrieve Payment Status	Retrieve the status of the payment.

For more details on this see the Checkout Setup.