Open Banking Payments
Developer Documents‣Open Banking‣Open Banking Payments

Open Banking is available as a payment method in the Cashier API when enabled on your account. It will also be shown on the Hosted Cashier payment form. See API details below

Open Banking transactions can take some time to complete. Once the account holder has authorised the payment, it will typically take a few seconds for the bank transfer to finish, but it can sometimes take longer. The UK Faster Payments scheme allows up to two hours. Advanced Payments will put the transaction in a PENDING state immediately after processing, and it will be updated to SUCCESS once the transfer is confirmed. Use notifications or query for the transaction state to find out when this happens. If the funds are not transferred within a reasonable time, the transaction will be marked as EXPIRED.

Open Banking transactions cannot be deferred, nor can a payment method be saved to reuse, such as for recurring or instalments. Refunds are supported, including multiple partial refunds, up to the amount of the original payment. Advanced Payments will put a refund transaction into a PENDING and update it to SUCCESS once the transfer is completed. Typically, a refund will take only a few seconds to complete.

Multiple Authorisations

Sometimes a transaction may require multiple account holders to authorise a payment, so it could take considerably longer than the two-hour transfer limit to complete. In this case, the transaction type will be PAYMENT_INITIALIZE with status SUCCESS and consumer spend zero. When the funds are transferred, a new secondary transaction of type PAYMENT_COMPLETE will be created, related to the initialize. The payment notifications or query for the transaction state can be used to find out when this has happened. When retrieving the initialize transaction, pay attention to the ‘followUpStatus’ section of the response, which will mention a complete transaction if one exists.

Remittance Reference

When an Open Banking transaction appears on the customer’s bank statement, it will include an auto-generated identifier based on the platform transactionId. The value will be returned in the remittanceReference field in API responses.

Best Practices

It is recommended to make use of notifications, or to poll for the transaction result to ensure that you receive the transaction result.

APIHosted

There are two integration modes for Open Banking: Redirect and Popup. With Redirect, there is a full page redirect in the browser to a page for the user to select their bank. With Popup mode, a window is opened for the user to select their bank. Redirect is recommended and is detailed on this page. See here for more details of Popup.

When using Redirect mode the customer will be returned to a specified URL once the payment is complete; This means that a returnUrl must be specified for all Redirect mode transactions. The billing address country is also required and must be “GBR”.

The API response for a payment transaction will have a status of PENDING and will contain a clientRedirect element which contains the URL where the customer will need to be redirected to. After the customer has followed the redirect and completed their payment the will be returned back to the specified return URL from the Open Banking provider.

The Open Banking provider will notify us once the payment is completed at which point we will update the status of the transaction. If you wish to manually check the latest status of the transaction, an API resume request can be performed on the initial transaction (see example below).

API examples
Create payment

POST /acceptor/rest/transactions/{instId}/payment
{
  "transaction" : {
    "currency" : "GBP",
    "amount" : 20.30,
    "description" : "Sample Transaction",
    "merchantRef" : "obDemo",
    "commerceType" : "ECOM"
  },
  "paymentMethod" : {
    "openbanking" : {
        "mode" : "REDIRECT",
        "returnUrl" : "http://example.com/return"
    },
    "billingAddress" : {
      "line1" : "Flat 1",
      "line2" : "House",
      "line3" : "A Street",
      "city" : "London",
      "postcode" : "AA1 2BB",
      "countryCode" : "GBR"
    }
  }
}
 
HTTP/1.1 201
{
    "processing": {
        "model": "MANAGE",
        "authResponse": {
            "acquirerName": "Nuapay",
            "gatewayReference": "fpzhswkkjj"
        },
        "route": "NUAPAY"
    },
    "clientRedirect": {
        "type": "REDIRECT",
        "url": "https://sandbox.nuapay.com/tpp-ui/redirect?userInterfacePaymentId=caf95924-be46-4a1d-9ab3-06e5793c5d51",
        "frame": "TOP"
    },
    "paymentMethod": {
        "openbanking": {
            "remittanceReference": "AP-12478445560",
            "mode": "REDIRECT"
        },
        "billingAddress": {
            "line1": "Flat 1 ",
            "line2": "House",
            "line3": "A Street",
            "city": "London",
            "postcode": "AA1 2BB",
            "country": "United Kingdom",
            "countryCode": "GBR"
        },
        "paymentClass": "OPENBANKING"
    },
    "transaction": {
        "transactionId": "12941435974",
        "merchantRef": "obDemo",
        "merchantDescription": "Sample Transaction",
        "status": "PENDING",
        "stage": "AUTHORISATION",
        "type": "PAYMENT",
        "amount": 20.30,
        "consumerSpend": 0,
        "currency": "GBP",
        "transactionTime": "2022-11-03T09:03:50.028Z",
        "receivedTime": "2022-11-03T09:03:50.028Z"
    },
    "outcome": {
        "status": "SUCCESS",
        "reasonCode": "U110",
        "reasonMessage": "Suspended for completion of authorisation"
    },
    "trace": "T1gNaFxoEUAJXn8rt3Abv4A"
}
Resume a payment

POST /acceptor/rest/transactions/{instId}/{transactionId}/resume
{}
 
HTTP/1.1 201
{
    "processing": {
        "model": "MANAGE",
        "authResponse": {
            "acquirerName": "Nuapay",
            "gatewayReference": "re273vajmd",
            "status": "AUTHORISED"
        },
        "route": "NUAPAY"
    },
    "paymentMethod": {
        "openbanking": {
            "remittanceReference": "AP-12478445566",
            "account": {
                "sortCode": "110874",
                "accountNumber": "****3569"
            },
            "multiAuthorisation": "AUTHORISED",
            "mode": "REDIRECT"
        },
        "billingAddress": {
            "line1": "Flat 1",
            "line2": "House",
            "line3": "A Street",
            "city": "London",
            "postcode": "AA1 2BB",
            "country": "United Kingdom",
            "countryCode": "GBR"
        },
        "paymentClass": "OPENBANKING"
    },
    "customFields": {
        "fieldState": []
    },
    "transaction": {
        "transactionId": "12478445566",
        "merchantRef": "obDemo",
        "merchantDescription": "Sample Transaction",
        "status": "SUCCESS",
        "stage": "COMPLETE",
        "type": "PAYMENT",
        "amount": 20.30,
        "consumerSpend": 20.30,
        "currency": "GBP",
        "transactionTime": "2025-02-17T10:24:51.265Z",
        "receivedTime": "2025-02-17T10:24:51.265Z"
    },
    "outcome": {
        "status": "SUCCESS",
        "reasonCode": "S100",
        "reasonMessage": "Authorised"
    },
    "trace": "TNQFxuvYdfVQiqOA8jKTnpg",
    "link": [
        {
            "href": "http://bluebox:12430/acceptor/rest/transactions/200000/12478445566",
            "rel": "transaction"
        }
    ]
}
API Endpoint
endpoint: /acceptor/rest/transactions/{instId}/payment
method: POST
summary: process Payment

parameters:

Name
Data Type
Description
instId
string
The installation id
request body:
{
sessionId string
Your reference for the Customer’s session.
transaction { Mandatory
currency string
Mandatory
The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount float
Mandatory
The amount of your Customer’s transaction.
commerceType string
Mandatory
Possible Values: ECOM, MOTO, CA
The commerce type for your Customer’s transaction. Should be ECOM for Open Banking.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The sales channel for your Customer’s transaction.
merchantRef string
Your reference for the transaction. Max length: 255. It’s recommended that you keep this unique.
description string
The description of the transaction. Maximum length: 255.
}
locale string
The ISO-639-1 code for your Customer’s locale.
customer {
id string
Our ID for the Customer where they are already registered with us.
update boolean
Indicates if you want to update the Customer’s details with the transaction.
email string
Email address for the Customer.
merchantRef string
Conditional
Your reference for the Customer. Not required if registered is set to false, mandatory otherwise.
dob string
Date of birth for the Customer.
billingAddress { The address of the Customer.
line1 string
Line 1 of the Customer’s address.
line2 string
Line 2 of the Customer’s address.
line3 string
Line 3 of the Customer’s address.
line4 string
Line 4 of the Customer’s address.
city string
City of the Customer’s address.
region string
Region of the Customer’s address.
postcode string
Post Code of the Customer’s address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s address country
}
displayName string
Conditional
The Customer’s name. Not required if registered is set to false, mandatory otherwise.
telephone string
Telephone number for the Customer.
ip string
The Customer’s IP address.
registered boolean
Indicates if we should register your customer; false if you do not wish to register your customer, otherwise set to true, default value is true.
}
transactionOptions {
sendEmailReceipt boolean
If true, an email receipt will be sent for this transaction. If false, no receipt will be sent. If not present, your account configuration determines if an email is sent.
}
paymentMethod { Mandatory
openbanking { Mandatory
mode string
Possible Values: REDIRECT, POPUP
The Open Banking integration mode.
returnUrl string
Conditional
Mandatory for REDIRECT mode. The URL that the user will be returned to after the payment has been completed.
}
billingAddress { The billing address of the Customer. Will be used for AVS checks. We’ll save the billing address when the customer makes their first payment. Providing a billing address for subsequent payments will update the address we’ve saved if you send new, empty or no values for each field.
line1 string
Line 1 of the Customer’s billing address.
line2 string
Line 2 of the Customer’s billing address.
line3 string
Line 3 of the Customer’s billing address.
line4 string
Line 4 of the Customer’s billing address.
city string
City of the Customer’s billing address.
region string
Region of the Customer’s billing address.
postcode string
Post Code of the Customer’s billing address.
countryCode string
Mandatory
The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}
response:
{
clientRedirect { Information about where to send your customer in the case of 3DS or a Callback.
frame string
Possible Values: TOP
The frame type for the redirect to be displayed in.
type string
Possible Values: REDIRECT
The type of client redirect.
url string
The URL the Customer should be redirected to.
}
transaction {
transactionId string
Our ID for the transaction.
deferred boolean
Indicates if the Payment capture is deferred.
merchantRef string
Your reference for the transaction.
merchantDescription string
The description of the transaction provided in the request.
status string
Possible Values: SUCCESS, FAILED, PENDING, EXPIRED, CANCELLED, VOIDED
The current state of the transaction.
type string
Possible Values: PAYMENT, PREAUTH, PAYOUT, REFUND, CAPTURE, CANCEL, REPEAT, CASH_ISSUE, CASH_PAYMENT
Indicates the type of the transaction.
amount float
Indicates the requested amount of the transaction.
consumerSpend float
Indicates the actual amount of the transaction. This will be zero for any type of INITIALIZE transaction, deferred transactions, and rejected transactions.
currency string
Indicates the currency of the transaction. Use the 3 character ISO-4217 code.
transactionTime string
The date and time we processed the transaction in ISO-8601 format.
receivedTime string
The date and time we received the transaction in ISO-8601 format.
commerceType string
Possible Values: ECOM, MOTO, CA
The Commerce Type of the transaction.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The Sales Channel of the transaction.
relatedTransaction { This field is not applicable for Payments. In case of Refunds it indicates the transaction that was refunded.
transactionId string
Our ID for the transaction that was original.
merchantRef string
Your reference for the transaction that was original.
}
}
processing { Information about the authorisation status of your transaction.
route string
The name of the processing engine your transaction was submitted to.
authResponse {
statusCode string
The code for the status received from the authoriser, if applicable.
acquirerReference string
The reference received from the authoriser for your transaction, if applicable.
acquirerName string
Name of the authoriser, if applicable.
message string
The message received from the authoriser, if applicable.
authCode string
The code received from the authoriser, if applicable.
gatewayReference string
The reference received from the processing engine.
gatewaySettlement string
The date the processing engine will settle the transaction. in YYYY-MM-DD format.
gatewayCode string
The code for the status received from the processing engine.
gatewayMessage string
The message received from the processing engine.
gatewayStatus string
The status received from the processing engine.
status string
Possible Values: AUTHORISED, DECLINED, REVERSED, REVERSE_FAILED, ERROR
The status received from the authoriser, if applicable.
}
}
customer { Information about the Customer.
id string
Our ID for the Customer.
merchantRef string
Your reference for the Customer.
}
outcome { Information about the overal outcome of the request.
reasonMessage string
A message indicating the overall outcome of the request. This is where we’ll provide detailed reasons for any errors. In the case of a decline this message can be very general. There can be useful guidance to the cause of the decline in processing.authResponse.gatewayMessage.
status string
Possible Values: SUCCESS, FAILED
The overall outcome of the request.
reasonCode string
A code indicating the overall outcome of the request. Refer to Errors for more information.
}
paymentMethod { Information about the Payment Method used in the request.
paymentClass string
The classification of payment method used. Eg. Card, Cash, PayPal
openbanking {
mode string
Possible Values: REDIRECT, POPUP
The chosen Open Banking integration mode.
remittanceReference string
Reference shown on customer’s bank statement.
account { Details of the bank account being used to make the payment. Will be available after the payment has completed.
sortCode string
The account sort code, 6 digits without any formatting.
accountNumber string
The masked account number. e.g. “*****3445”
}
multiAuthorisation string
Status of multiple authorisation requirements when relevant.
AUTHORISED – The transaction has had all the authorisations required to be processed.
INCOMPLETE – At least one more authorisation is required for this transaction to be processed.
REJECTED – At least one authoriser has rejected the transaction, and it will not be processed.
}
billingAddress { The billing address of the Customer. Will be used for AVS checks. We’ll save the billing address when the customer makes their first payment. Providing a billing address for subsequent payments will update the address we’ve saved if you send new, empty or no values for each field.
line1 string
Line 1 of the Customer’s billing address.
line2 string
Line 2 of the Customer’s billing address.
line3 string
Line 3 of the Customer’s billing address.
line4 string
Line 4 of the Customer’s billing address.
city string
City of the Customer’s billing address.
region string
Region of the Customer’s billing address.
postcode string
Post Code of the Customer’s billing address.
country string
Country name of the Customer’s billing address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}

No special actions are required to create a Hosted session that supports Open Banking. If Open Banking is available on your account then it will appear on the payment form for eligible transactions. It will be the first, pre-selected, payment method on the form. The payment methods available, and their order, can be customised on the Hosted session creation request using features.paymentMethods; see API specification below.

Please note: Open Banking is only available when using a version two Hosted skin.

  • If you are using, or intend to use, a custom skin, make sure it’s the right version. See Upgrading from skinning version 1 to version 2.
  • Our current default skin (id: 2) supports Open Banking. The legacy default (id: 1) does not.
  • For other skins we provide, please contact Support to confirm the version.

If you have a custom skin, it is recommended to check it works with Open Banking in MITE before it is enabled in production, see Testing Open Banking.

If you are using our hosted payment page inside an iframe then you can use the restoreUrl field to return back to your web page when the transaction is complete. If the restoreUrl is specified then the customer will be returned to this URL with a query parameter containing the URL to load in the frame.

Hosted examples
Create session

POST /hosted/rest/sessions/{instId}/payments
{
  "session": {
    "transactionNotification": {
      "url": "http://www.example.com/notification"
    },
    "returnUrl": {
      "url": "http://www.example.com/transactionResult?MERCHANTREF=761585761585"
    }
  },
  "transaction": {
    "merchantReference": "761585761585",
    "money": {
      "amount": {
        "fixed": 10.30
      },
    "currency": "GBP"
    }
  }
}

HTTP/1.1 200
{
  "sessionId": "5280f295-b7ea-4eaa-8e3b-ebd6fa67cc58",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/8f2c9ec4-f9e6-44a7-b14a-39a47d3aeb65/begin/5280f295-b7ea-4eaa-8e3b-ebd6fa67cc58",
  "status": "SUCCESS"
}
Create session with restore URL

POST /hosted/rest/sessions/{instId}/payments
{
  "session": {
    "transactionNotification": {
      "url": "http://www.example.com/notification"
    },
    "returnUrl": {
      "url": "http://www.example.com/transactionResult?MERCHANTREF=761585761585"
    },
    "restoreUrl": {
      "url": "http://www.example.com/restore"
    }
  },
  "transaction": {
    "merchantReference": "761585761585",
    "money": {
      "amount": {
        "fixed": 10.30
      },
    "currency": "GBP"
    }
  }
}

HTTP/1.1 200
{
    "sessionId": "SMjqvmA5Zzh9CNYu2AqISLQNr",
    "redirectUrl": "http://bluebox:12460/hosted/SMjqvmA5Zzh9CNYu2AqISLQNr/begin/SMjqvmA5Zzh9CNYu2AqISLQNr",
    "status": "SUCCESS"
}
Hosted endpoint
endpoint: /hosted/rest/sessions/{instId}/payments
method: POST
summary: process Payment

parameters:

Name
Data Type
Description
instId
string
The installation id
request body:
{
transaction { Mandatory
Details of the transaction you want to create.
merchantReference string
Your reference for the transaction.
money { Mandatory
currency string
Mandatory
The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount { Mandatory
Choose one of fixed, choice, range or suggested amount specifications.
fixed float
Choice
Use if you want your customer to only make a payment for a fixed amount. The customer can not change the amount.
choice { Choice
Use if you want your customer to select from a predefined set of amounts.
option [ array
Mandatory
Mandatory if Amount Choice included in the request.
item float
]
}
range { Choice
Use if you want your customer to choose an amount between a minimum and maximum value or within a part-bounded range. You can also provide a default amount. This can be overtyped by the customer if they want to.
min float
Mandatory if Amount Range included in the request and max value not present.
max float
Mandatory if Amount Range included in the request and min value not present.
default float
}
suggested { Choice
Use if you want to your customer to choose an amount between a minimum and maximum value or from a predefined set of amounts.
choice { Mandatory
Mandatory if Suggested included in the request.
option [ array
Mandatory
item float
]
}
range { Mandatory
Mandatory if Suggested included in the request.
min float
max float
default float
}
}
}
}
description string
The description of the transaction.
commerceType string
Possible Values: ECOM, MOTO, CNP
The commerce type for your Customer’s transaction.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The sales channel for your Customer’s transaction. If no channel is provided we’ll automatically classify the channel as WEB
}
customer {
create boolean
Deprecated. Use ‘registered’ instead, as this will be removed in the future.
registered boolean
Indicates if you wish to create or use a registered customer. False if you do not wish to register your customer, otherwise set to true. Default value is true.
identity { Conditional
Mandatory when registering a new customer, or using an already registered customer, optional otherwise.
platformCustomerId string
Choice
Our ID for your customer.
merchantCustomerId string
Choice
Your ID for the customer.
}
details { Conditional
Mandatory when registering a new customer, optional otherwise. NB – If details element is present when fetching an existing customer, the details stored for that customer will be updated with those present in the request.
name string
Conditional
The Customer’s name
Mandatory when registering a new customer, optional otherwise.
address { Conditional
Mandatory when registering a new customer, optional otherwise. This is used to pre-populate the customers billing address fields.
line1 string
Line 1 of the Customer’s address.
line2 string
Line 2 of the Customer’s address.
line3 string
Line 3 of the Customer’s address.
line4 string
Line 4 of the Customer’s address.
city string
City of the Customer’s address.
region string
Region of the Customer’s address.
postcode string
Post Code of the Customer’s address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s address country.
}
telephone string
Telephone number for the Customer.
emailAddress string
Email address for the Customer.
ipAddress string
The Customer’s IP address.
}
}
locale string
The ISO-639-1 code for your Customer’s locale.
session { Mandatory
preAuthCallback { Details of the callback made before the transaction is sent for authorisation.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
postAuthCallback { Details of the callback made after the transaction is sent for authorisation.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
transactionNotification { Details of the notification sent after transaction completion.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
returnUrl { Mandatory
The URL that we will return your customer to after processing the transaction.
url string
Mandatory
}
cancelUrl { The URL that we will return your customer to if they cancel the hosted session. If omitted the returnUrl is used if they cancel.
url string
Mandatory
}
restoreUrl { If specified we’ll take your customer to this URL after the transaction has been processed. You will need to use this field if you iFrame our hosted product.
url string
Mandatory
}
skin The ID of the skin used to drive look and feel for this session. Refer to Customise hosted look and feel for more information.
}
features { Holder of features that can be enabled/disabled during a hosted session.
paymentMethods array
Possible Values in the Array: card, openbanking
Allow the customer to specify which payment methods are to be displayed, in the specified order. The array should contain strings for the names of payment methods. This is only available for a version 2 skin. Any additionally payment methods enabled on your account can be included in this array.
sendEmailReceipt boolean
If true, an email receipt will be sent for this transaction. If false, no receipt will be sent. If not present, your account configuration determines if an email is sent.
showResultsPage boolean
If true, after processing the transaction the user will be shown a page with the result, including key details of the transaction, including amount, transaction id, merchant reference, etc. Default is false, meaning it is up to the merchant to inform the customer of the result of the transaction.
NOTE: This option is only available when using a version 2 hosted skin, see Skin Properties
}
}
response:
{
sessionId string
Our ID for the hosted session.
redirectUrl string
The URL you should direct your customer to to start the hosted session.
status string
Possible Values: SUCCESS, FAILED
Indicates the status of the session creation.
reasonCode string
Further information about the status of the session creation.
reasonMessage string
Further information about the status of the session creation. This is where we will provide detailed information about any errors.
}