Payment Initiation APIs

1.0.x
(1 review)

Important Information & Bank of Ireland’s API Implementation

This page is a reflection of Bank of Ireland’s implementation of the Open Banking Payment Initiation Service APIs.

Common across both Domestic Payments ROI/NIGB and International Payments ROI/NIGB

Known Issues

  1. BOI are aware of a defect which is preventing payments being initiated to accounts with account number ‘00000000’. This is on our roadmap to fix but it is not yet possible to provide a resolution date. When a fix is scheduled and completed, updates will be published in the Transparency Calendar, here and in the News and Announcements section.

  2. merchantCustomerIdentification - We have identified a defect in our systems, whereby we restricted length of merchantCustomerIdentification (within risk block) to 32 characters. A defect fix is inour backlog and the developer portal will be updated once the fix is delivered.

Cut-off Times

  • For Banking 365 Online users, if a request to initiate a payment is received after the cut-off time, Bank of Ireland will accept the payment and process it on the next working.
  • For Business On Line users, Bank of Ireland will accept payments up to cut-off time, payments submitted after cut-off will be rejected.
  • Information on Cut-off times for Bank of Ireland Group is available "here" for Business On Line customers, and available "here" for 365 Online customers.

Payee Name length for Business On Line

Bank of Ireland UK and ROI support Payee name length up to 50 characters.
Request to process payment with payee name more than 50 characters will be declined.

Supported Fields

Bank of Ireland does not support the below fields in response messages:

  • CutOffDateTime
  • ExpectedExecutionDateTime
  • ExpectedSettlementDateTime

Supported Characters

Below is a list of special characters supported by Bank of Ireland. Bank of Ireland will reject requests received with any other character.

Special characters included in Payer Name, Payee Name and EndToEndIdentification field are confined to:

                  / -  :  ' + Space

Special characters included any other field apart from above are confined to:

                  / - ? : ( ) . , ' + Space

Supplementary information

All APIs will only return one error message in the response in case of an error scenario. Please make sure that you have provided all information that is required for a successful API call.

Scheme Name

Bank of Ireland only accepts requests with valid namespacing for Payer and Payee Scheme Name i.e. Bank of Ireland won’t be able to process values without UK.OBIE prefix.

In Ireland, valid scheme name is:

  • UK.OBIE.IBAN

In UK, valid scheme name is:

  • UK.OBIE.SortCodeAccountNumber

Requests with any other Scheme Name will be rejected.

Payment Status

For domestic payments & domestic scheduled payments, the final status supported by Bank of Ireland is AcceptedSettlementInProcess. BOI is unable to provide the AcceptedSettlementComplete status as this is not supported in the bank’s existing online payments channels. We are aware that this may cause challenges with Open Banking / API payments, and would invite TPPs to contact us if this limitation impacts them. If payment or standing order is rejected downstream, or by beneficiary bank, status will not be updated.

Local Instrument

Bank of Ireland does not process value in local instrument. Regardless of value in local instrument:

  • Bank of Ireland (ROI) will process domestic payment via SEPA.
  • Bank of Ireland UK will process domestic payment as next day payment.

Confirmation of Funds

  • Bank of Ireland will perform funds check after the user authorises their consent and before issuing an access token. The access token will be returned only if user has sufficient funds to cover the payment.
  • On payment submission, Bank of Ireland will perform funds check again and apply immediate debit to customer’s account. The bank will return a negative result if the user has insufficient funds in their chosen account to complete the transaction.

Funds Check is not performed for Domestic Scheduled Payments, International Scheduled Payments or Standing Orders i.e. the funds check does not take place at the point of authorisation or submission, but is carried out on the day the of processing.

Multi-Auth for BOL Channel

Bank of Ireland supports Multi-authorisation for BOL customers.

Bank of Ireland does not support CompletionDateTime field within the Authorisation block. If the field CompletionDateTime is passed in the payload, the payment will be rejected.

If a domestic payment requires 2nd level (dual) authorisation, BOI returns the MultiAuthorisation block with the status field in the payment submission response.

A multi-auth payment have one of the 3 valid statuses:

  • AwaitingFurtherAuthorisation
  • Authorised
  • Rejected.

Bank of Ireland does not support the below fields in response messages:

  • MultiAuthorisation.NumberRequired
  • MultiAuthorisation.NumberReceivede
  • MultiAuthorisation.LastUpdateDateTime
  • MultiAuthorisation.ExpirationDateTime

The 2nd level authoriser can Authorise or Reject a payment. The payment details cannot be amended once it has been submitted.

Domestic Payments

Currencies

  • Bank of Ireland only supports GBP for UK Jurisdiction
  • Bank of Ireland only supports EUR for ROI Jurisdiction

Payee Address for Bank of Ireland (ROI) SEPA Payments and Bank of Ireland UK Domestic Payments

  • For Banking 365 Online users and Business On Line (BOL) users, Bank of Ireland UK does not require payee address to post Domestic Payments. If payee address is included in the Domestic Payment request, it will not be considered while posting the transaction.
  • For Banking 365 Online users, Bank of Ireland (ROI) does not support payee address for SEPA payments. Request to process payment with payee address will be declined

  • For BOL (ROI) customers, payee address is mandatory. Bank of Ireland (ROI) supports 3 lines of address.

    • Country Code is mandatory

    • Up to 2 lines of maximum 35 characters each, minimum 1 line of address.

              “CreditorPostalAddress”:{

         “Country”:”IE”,

         “AddressLine”:{

          ”.....”,

         “.....”

               }

          }

Request to process payment without payee address, or payee address in any other format will be declined.

SEPA Reachable countries via domestic payments API for Bank of Ireland (ROI)

All SEPA countries are reachable.

Scheduled Payment

Bank of Ireland will accept scheduled payments up to 60 calendar days in future.

A customer can cancel a scheduled payment which has been made via TPP on the channel today. This can happen, once the customer is cancelling the payment before it has been executed. The TPP will not be notified of this change.

Domestic Payments Standing Orders

Below are the validations that will be performed in the live environment for Standing Orders:

  • Bank of Ireland supports open ended standing orders only. Requests to create standing orders with an end date would be rejected.
  • Bank of Ireland supports only one amount for first, recurring and last standing order. If request to setup standing order is received with different amounts, it will be rejected.
  • Bank of Ireland supports only start date and frequency. Regardless of recurring date requested on standing order setup request, recurring date would be calculated using start date and frequency.
  • Bank of Ireland supports below frequencies only, request to setup SO with any other frequency would be rejected.
    • Weekly
    • Fortnightly
    • Monthly
    • Yearly
  • Below table shows few examples of how Bank of Ireland will handle frequency.

Value provided by PISP

Bank of Ireland Processing

Frequency

EvryDay

Reject - 400 Bad Request

NA

EvryWorkgDay

Reject - 400 Bad Request

NA

IntrvlDay

Reject - 400 Bad Request

NA

IntrvlWkDay:01:01
TO
IntrvlWkDay:01:07

Accept
if FirstPaymentDateTime matches IntrvlWkDay

Weekly

IntrvlWkDay:02:01
TO
IntrvlWkDay:02:07

Accept
if FirstPaymentDateTime matches IntrvlWkDay

Fortnightly

Any other CMA compliant value for 
IntrvlWkDay

Reject - 400 Bad Request

NA

Any CMA compliant value for 
WkInMnthDay

Reject - 400 Bad Request

NA

IntrvlMnthDay:01:01
TO
IntrvlMnthDay:01:31

Accept
if FirstPaymentDateTime matches IntrvlMnthDay

Monthly

IntrvlMnthDay:12:01
TO
IntrvlMnthDay:12:31

Accept
if FirstPaymentDateTime matches IntrvlMnthDay

Yearly

Any other CMA compliant value for 
IntrvlMnthDay

Reject - 400 Bad Request

NA

Any other CMA compliant value for QtrDay

Reject - 400 Bad Request

NA
  • Standing Orders must be for value of £1 or more. This is in line with the limits on BOI’s online channels. Any Standing Order setup request for a value of less than £1 will return an error.
International Payments

The following must be considered for Bank of Ireland B365 International Payments:

B365 International Payments is a separate service to Domestic/SEPA payments. Different services must be called depending on the payment type.

To make a Euro payment to a country within the SEPA zone, the payment must be made through the Domestic Payment API.

Countries and Currencies

  • Please click here for list of supported countries and currencies when making International Payments for Bank of Ireland Banking 365 Online users. If an international payment request is made containing a country outside of this list of supported countries, the payment will be rejected.
  • The Currency of Transfer and Instructed Amount currency constraints are dependent on CreditorAgent/Country. For Bank of Ireland Banking 365 Online users, Currency of Transfer and Instructed Amount currency must be the same. For example: when Creditor Agent country is Australia (AU), currency of transfer and instructed amount currency must be Australian Dollar.

Payee Address for Bank of Ireland International Payments

For both Business On Line International Payments and Banking 365 Online International Payments, payee address is mandatory. Bank of Ireland supports 3 lines of address.

  • Payee Name is mandatory
  • For Banking 365 Online the following rules apply to payee name:
    • When CreditorAgent/Country is Hungary, Payee Name is max 26 characters
    • When CreditorAgent/Country is United Kingdom, Payee Name is max 18 characters
    • When CreditorAgent/Country is United States, Payee Name is max 26 characters
    • For every other country, Payee Name is max 35 characters
  • Country Code is mandatory

  • Up to 2 address lines are accepted for Payee address

    • Address line 1 is mandatory
      • If creditorAgent/Country is US, Creditor/Address1 is max 26 chars
      • For every other country,Creditor/Address1 is max 35 chars

    • Address line 2 is optional

             “CreditorPostalAddress”:{

        “Country”:”IE”,

        “AddressLine”:{

        ”.....”,

        “.....”

               }

           }

Request to process payment without payee address, or payee address in any other format will be declined.

Creditor Account details for Bank of Ireland B365 International Payments

  • For Banking 365 Online Bank of Ireland International Payments, please click here for list of creditor account details that are required for Banking 365 Online users to make International Payments to any of the countries listed here.
  • Please review the below table, it shows which creditor account details are optional and which are mandatory:
Creditor Agent Country Name All Mandatory Creditor Account Details fields B365 All Optional Creditor Account Details fields B365
Australia NSC
Account number
Canada NSC
Account number
China Account number NSC - optional
Croatia IBAN
Czech Republic IBAN
Denmark IBAN
Hong Kong Account number NSC - optional
Hungary IBAN
India Account number NSC - optional
New Zealand Account number NSC - optional
Norway IBAN
Pakistan IBAN
Philippines Account number NSC - optional
Poland IBAN
Russia Account number NSC - optional
Singapore Account number NSC - optional
South Africa NSC
Account number
Sweden IBAN
Switzerland IBAN
Thailand Account number NSC - optional
Turkey IBAN
United Arab Emirates IBAN
United Kingdom IBAN
United States ABA
Account number
  • Please review the below, it shows the possible enumerations for CreditorAccount/SchemeName for Banking 365 Online users for Bank of Ireland International Payments:
    • Creditor Account Scheme Name tells us how to parse Creditor Account Identification
    • Creditor Account Scheme Name can have one of a possible 36 SchemeName values
      • UK.OBIE.IBAN
        • This indicates the scheme name is an IBAN. This means a sort code or branch identifier are not provided.
      • IE.BOI.NCCAndAccountNumber.0
        • This indicates the scheme name captures an account number. This means a sort code or branch identifier are not provided
      • IE.BOI.NCCAndAccountNumber.1
        • This indicates that the first digit will be the a sort code or branch identifier, the rest of the characters provided will translate into the account number
      • IE.BOI.NCCAndAccountNumber.2
        • This indicates that the first two digits will be a sort code or branch identifier, the rest of the characters provided will translate into the account number
      • IE.BOI.NCCAndAccountNumber.3
        • This indicates that the first three digits will be a sort code or branch identifier, the rest of the characters provided will translate into the account number
      • IE.BOI.NCCAndAccountNumber.4
        • This indicates that the first four digits will be a sort code or branch identifier, the rest of the characters provided will translate into the account number
      • ….
      • IE.BOI.NCCAndAccountNumber.35

This indicates that the first thirty-five digits will be a sort code or branch identifier, the rest of the characters provided will translate into the account number

Creditor Agent for Bank of Ireland B365 International Payments

  • For Banking 365 Online users, Creditor Agent block is mandatory.

  • The following fields are mandatory for the Creditor Agent block for Banking 365 Online users for Bank of Ireland (ROI):

    • CreditorAgent /SchemeName
      • Optional when CreditorAgent/Country is US, mandatory for all other countries
      • Only supported value for SchemeName is ‘UK.OBIE.BICFI’
    • CreditorAgent /Identification
      • Optional when CreditorAgent/Country is US, mandatory for all other countries
      • Identification must be a valid BIC
    • CreditorAgent /Name
      • Mandatory only when CreditorAgent/Country is US, not required for all other countries
      • If BICFI is provided as CreditorAgent/Identification when CreditorAgent/Country is the US, the Bank will overwrite the bank name provided by TPP

    • B365 Bank of Ireland (ROI) supports 4 lines of CreditorAgent /PostalAddress.

      • Country code is mandatory and for Bank of Ireland Banking 365 Online users CreditorAgent/PostalAddress/Country must be a country within these constraints.
      • TownName is mandatory

      • 2 lines of maximum 35 characters each of CreditorAgent /PostalAddress /AddressLine.

        • AddressLine 1 is mandatory, AddressLine 2 is optional.

            “CreditorPostalAddress”:{

   “Country”:”IE”,

   "TownName":"DUBLIN",

   “AddressLine”:{

   ”.....”,

    “.....”

          }

      }

Request to process payment without CreditorAgent block, or CreditorAgent block in any other format will be declined.

Exchange Rate Information

  • The following exchange rate types will only be accepted:
    • Actual
    • Indicative
  • Requests including rate type of ‘Agreed’ will be rejected
  • If a TPP requests a rate type of ‘Indicative’, an ‘Actual’ exchange rate will be used for the transaction.

Charge Bearer

  • If charge bearer is included in the initial payload, the only value that will be accepted is ‘Shared’.
  • Any other value will be rejected

UK Post Office

UK Post Office Current Accounts are no longer available and access to these accounts is not available via APIs.

Payment Initiation from Credit Cards

API endpoints are not available on credit cards as balance transfers and money transfers cannot be completed through Bank of Ireland online banking.

Note:

BOI supports HTTP 'x-content-type-options' response header by setting the value to 'nosniff' which is returned to TPPs for all APIs.
The Content-Type representation header is used to indicate the original media type of the resource (prior to any content encoding applied for sending). In responses, a Content-Type header provides a TPP with the actual content type of the returned content. This header's value may be ignored, for example when browsers perform MIME sniffing as BOI has set the value to ‘nosniff’ to prevent this behaviour.

Reviews