Supplementary Specification | AIB Developer Portal

API Documentation

Payments API

EndPoint

Field Name

Xpath

Description

Category

Validation Rules

All Scheduled Payments

Permission

XXX/Data/Permission

Specifies the Open Banking service request types.

Mandatory

We will only accept permission code 'Create'.

All Scheduled Payments

RequestedExecutionDateTime

XXX/Data/Initiation/RequestedExecutionDateTime

Date at which the initiating party requests the clearing agent to process the payment. Usage: This is the date on which the debtor's account is to be debited.

Mandatory

AIB will accept consents with requested execution date up to 180 days into the future. Consent will be rejected, if the RequestedExecutionDateTime has expired at the time of consent.

All Endpoints (Excluding File Payments)

ReadRefundAccount

XXX/Data//ReadRefundAccount

Specifies to share the refund account details with PISP

Optional

If populated as 'Yes', we will provide the Creditor and Creditor Agent details in the refund block of our response.

Domestic Payments

PaymentPurposeCode

XXX/Risk/PaymentPurposeCode

Category code, related to the type of services or goods that corresponds to the underlying purpose of the payment that conforms to Recommended UK Purpose Code in ISO 20022 Payment Messaging List.

Optional

Only Mandatory for International Payments.

Domestic Payments

EndToEndIdentification

XXX/EndToEndIdentification

Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Mandatory

For SEPA payments, Customer to provide unique reference to enable reconciliation by the creditor. E.g. Creditor Narrative.

For Bill payments, Customer to provide unique Biller Account or Invoice number to enable reconciliation by the Service Provider / Merchant.

Domestic Scheduled Payment

EndToEndIdentification

OBDomesticScheduled2/EndToEndIdentification

Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Optional

Customer to provide unique reference to enable reconciliation by the creditor. If no value provided then AIB will populate the Customer name (i.e. Debtor Name) in the EndToEndIdentification field and will travel with the payment. E.g. Creditor Narrative.

All Domestic Endpoints

Reference

XXX/RemittanceInformation.Structured.CreditorReferenceInformation.Reference

Unique reference, as assigned by the creditor, to enable reconciliation by the beneficiary

Optional

Customer to provide unique reference to enable reconciliation by the creditor. Please note that only the 18 characters will travel with payment to the recipient bank. For Bill payments, Customer to provide unique Biller Account or Invoice number to enable reconciliation by the Service Provider / Merchant.

All Domestic Endpoints

Unstructured

XXX/RemittanceInformation/Unstructured

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.

Optional

For all payments, the information contained in this tag will travel with the payment to the recipient bank.Array of Max 140 text.

All Domestic Endpoints

LocalInstrument

XXX/LocalInstrument

This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level

Optional

If supplied in the Consent, AIB will process the LocalInstrument Code value. Value (if tag is provided) must be provided from an OB defined list. For SEPA Instant payments, value must be "UK.OBIE.SEPAInstantCreditTransfer"

All Endpoints

SchemeName

XXX/DebtorAccount/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

Mandatory

For all ROI Customer initiated payments, Debtor account must be in IBAN format.
If Debtor account is provided, SchemeName is mandatory.

All Endpoints

Name

XXX/CreditorAccount/Name

The account name is the name or names of the account owner(s) represented at an account level.

Mandatory

For all payments, the information contained in this tag will travel with the payment as a Creditor Name to the recipient bank. Incorrect Creditor Name may result in payment rejection.

Domestic

SchemeName

XXX/CreditorAccount/SchemeName

Identification assigned by an institution to identify an account. This identification is known by the account owner.

Mandatory

For SEPA payments, the SchemeName must be IBAN.

All Endpoints

AuthorisationType

XXX/Authorisation/AuthorisationType

Level of authentications require to authorise the consent

Optional

For all payments, only "Any" value is supported by AIB. AIB default the AuthorisationType as "Any" if tag or no value present. AIB will reject the payment request if value is other than "Any".

All Endpoints

CompletionDateTime

XXX/Authorisation/CompletionDateTime

Defined the date time for the payment order authorisation to be completed

Not Required

AIB does not support this field. AIB will reject the Consent if any value is populated.

Domestic Standing Order

FirstPaymentDateTime

OBDomesticStandingOrder3/MandateRelatedInformation/FirstPaymentDateTime

The date on which the first payment for a Standing Order schedule will be made

Mandatory

AIB will reject the Consent with value in this field if it is same as Today's or past date

Domestic Standing Order

RecurringPaymentDateTime

OBDomesticStandingOrder3/MandateRelatedInformation/RecurringPaymentDateTime

The date on which the first recurring payment for a Standing Order schedule will be made.

Not Required

AIB does not support this field. AIB will reject the Consent if any value is populated.

Domestic Standing Order

NumberOfPayments

XXX/StandingOrder/NumberOfPayments

Number of the payments that will be made in completing this frequency sequence including any executed since the sequence start date.

Conditional

AIB only supports maximum 4 digits (i.e. upto 9999 recurring payments for a Standing Order).

Domestic Standing Order

Frequency

XXX/MandateRelatedInformation/Frequency

Frequency of Payments for a Standing Order

Mandatory

AIB supports only WEEK, FRTN, FOWK,
MNTH, TWMH, QURT, FOMH, MIAN, YEAR.
Frequency should match with value in "FirstPaymentDateTime" field. In case of mismatch, AIB will reject the Consent.

Domestic Standing Order

CountPerPeriod

XXX/MandateRelatedInformation/Frequency/CountPerPeriod

Number of instructions to be created and processed during the specified period. Specifies a frequency in terms of a count per period within a specified frequency type.

Optional

AIB only supports ‘1’ or ‘BLANK’ in this field.

Domestic Standing Order

FinalPaymentDateTime

OBDomesticStandingOrder3/MandateRelatedInformation/FinalPaymentDateTime

The date on which the final payment for a Standing Order schedule will be made.

Conditional

AIB supports recurring payments upto 35 years. And will reject the consent if request receive to setup the standing order for more than 35 years.

AIB supports either "FinalPaymentDateTime" or "NumberOfPayments" to setup a Standing Order. And will reject the Consent if AIB receive the values in both the fields.

AIB will reject the Consent if value in "FinalPaymentAmount" block is available and there is no value in "FinalPaymentDateTime" tag.

Domestic Standing Order

Reference

XXX/RemittanceInformation/Structured/CreditorReferenceInformation/Reference

Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Mandatory

This field is mandatory to capture the unique creditor narrative that can be referred for reconciliation purpose.

AIB supports only 18 characters and will truncate if length is more than 18 characters.

Domestic Standing Order

LocalInstrument

XXX/Initiation/SupplementaryData/LocalInstrument

This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level

Conditional

Mandatory for SEPA Instant.

Optional for SEPA Standard.

If supplied in the Consent, AIB will process the LocalInstrument Code value. Value (if tag is provided) must be provided from an OB defined list. For SEPA Instant payments, the value must be "UK.OBIE.SEPAInstantCreditTransfer" For SEPA Standard payments, the value must be "UK.OBIE.SEPACreditTransfer" or the tag must not be provided.

Domestic Standing Order

Unstructured

XXX/RemittanceInformation/Unstructured

Optional

For all standing order payments (SEPA Instant and SEPA Standard) the information contained in this tag will travel with the payment to the recipient bank. AIB accepts a maximum of 139 characters.

Domestic Standing Order

Structured

XXX/RemittanceInformation/Structured

Optional

For all standing order payments (SEPA Instant and SEPA Standard), the information contained in this tag will travel with the payment to the recipient bank. AIB accepts a maximum of 139 characters.

All International Endpoints

Name

XXX/Creditor/Name

Name by which a party is known and which is usually used to identify that party.

Optional

For all payments, the information will not travel with the payment.

All International Endpoints

Creditor Agent

XXX/CreditorAgent

Financial institution servicing an account for the creditor.

Mandatory

Mandatory field.

All International Endpoints

Creditor Agentaddressline

XXX/CreditorAgent/PostalAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

Mandatory

The information in this block will travel with the payment. Please note that only 105 characters (AddressLine 1 & 2) will travel with the payment to the recipient bank.

International Payment

EndToEndIdentification

OBInternational/EndToEndIdentification

Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Mandatory

Customer to provide unique reference to enable reconciliation by the creditor. E.g. Creditor Narrative

Only 30 characters will travel with the SWIFT instruction to the recipient bank.

International Scheduled Payment

EndToEndIdentification

OBInternationalScheduled2/EndToEndIdentification

Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.

Optional

Customer to provide unique reference to enable reconciliation by the creditor. If no value provided then AIB will populate the value "NOT PROVIDED" in the EndToEndIdentification field and will travel with the payment. E.g. Creditor Narrative.

This field is only offered to Business / Corporate customers.

International Payment

PaymentPurposeCode

XXX/Risk/PaymentPurposeCode

Category code, related to the type of services or goods that corresponds to the underlying purpose of the payment that conforms to Recommended UK Purpose Code in ISO 20022 Payment Messaging List.

Mandatory

Mandatory for International Payments
Please refer to detailed information below for list of AIB accepted values.

All International Endpoints

ExtendedPurpose

XXX/ExtendedPurpose

Specifies the purpose of an international payment, when there is no corresponding 4 character code available in the ISO20022 list of Purpose Codes.

Optional

For all International payments, the information will not travel with the payment.

All International Endpoints

LocalInstrument

XXX/LocalInstrument

This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level

Not Required

AIB will not process the LocalInstrument Code value supplied in the Consent. AIB will derive payment clearing option using the internal payment processing rules. Value (if tag is provided) must be provided from an OB defined list.

All International Endpoints

ChargeBearer

XXX/ChargeBearer

Specifies which party/parties will bear the charges associated with the processing of the payment transaction. BorneByCreditor, BorneByDebtor, FollowingServiceLevel, Shared.

Optional

BorneByDebtor: Only be used when the beneficiary bank is outside EEA. If customer select this charging option, your account will be debited with the AIB charges and with all other bank charges when the notification is received from the relevant bank (s). This charging option is only available to Business/Corporate customers.

Shared: Payments to EEA countries must be sent using this charging option. And this option can be used for international payments where the beneficiary bank is outside EEA.

ServiceLevel or BorneByCreditor: AIB will reject the Consent with this charging option.

AIB default the value with "Shared" if tag or no value present.

Personal Customers: Only "Shared" supported for Personal customers.

All International Endpoints

InstructionPriority

XXX/InstructionPriority

Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction.

Optional

AIB default the priority as "Normal" if tag or value not present. All the payments with "Urgent" priority will be processed through Swift.

All International Endpoints

CurrencyOfTransfer

XXX/CurrencyOfTransfer

Specifies the currency of the to be transferred amount, which is different from the currency of the debtor's account.

Mandatory

AIB supports different set of currencies for their Personal & Business customers on basis of InstructionPriority. AIB will reject the Consent if request received with currency that is not supported for respectable type of customers.

Personal Customer: Refer below AIB link for supported currencies https://aib.ie/help-and-guidance/international-payments-faqs.

Business / Corporate Customer: Refer below AIB link for supported currencies https://business.aib.ie/help/international-payments-faq.

All International Endpoints

DestinationCountryCode

XXX/DestinationCountryCode

Country in which Credit Account is domiciled. Nation with its own government.

Mandatory

For all international payments, this information is mandatory

All International Endpoints

Currency

XXX/InstructedAmount/Currency

A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".

Mandatory

For Personal Customers: Instructed Currency should be same as CurrencyOfTransfer. If this is not true, AIB will reject the Consent.

For Business / Corporate Customers: If Instructed Currency is not same as CurrencyOf Transfer, then it should be same as Debit Account Currency. If this is not true, AIB will reject the Consent.

All International Endpoints

ExchangeRateInformation

XXX/ExchangeRateInformation

Provides details on the currency exchange rate and contract.

Conditional

This block is only required to process the Cross Currency payment using Dealer or Forward Contract Rate (pre-agreed rate with AIB only). And this service is only offered to Business / Corporate customers.

All International Endpoints

UnitCurrency

XXX/ExchangeRateInformation/UnitCurrency

Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP.

Mandatory

Value must be "EUR"

All International Endpoints

RateType

XXX/ExchangeRateInformation/RateType

Specifies the type used to complete the currency exchange.

Mandatory

Agreed:strong Only be used when customer wants to process the payment using Dealer or Forward Contract Rate If Rate Type equals Agreed, then values in ExchangeRateInformation or Forward Contract block are mandatory.
Actual / Indicative: AIB will reject the Consent with these RateType values

All International Endpoints

ContractIdentification

XXX/ExchangeRateInformation/ContractIdentification

Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent.

Conditional

The field should be used to supply a unique and unambiguous Dealer Reference.

International Payment

Name

OBInternational2/CreditorAgent/Name

Name by which an agent is known and which is usually used to identify that agent.

Optional

Creditor Agent Name will travel with CreditorAgent/PostalAddress/AddressLine if provided. In certain scenarios, this information will not travel if UK.OBIE.BICFI and IE.AIB.LCC is populated.

All International Endpoints

SchemeName

XXX/CreditorAgent/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

Optional

AIB supports below values:
- UK.OBIE.BICFI,
- UK.OBIE.NCC.[ISO3166-aplha2-CountryCode]
- UK.OBIE.LCC.

In case of "UK.OBIE.BICFI", customer must provide the valid BIC ( 8 or 11 characters) in Identification field (OBInternational2/CreditorAgent/Identification).

In case of "UK.OBIE.LCC.[ISO3166-aplha2-CountryCode]", customer must provide the valid Bank Code in Identification field (OBInternational2/CreditorAgent/Identification).

AIB will reject the Consent if only SchemeName or only Identification is provided.

All International Endpoints

PostalAddress

XXX/CreditorAgent/PostalAddress

Information that locates and identifies a specific address, as defined by postal services.

Optional

Only Addressline information in this block will travel with payment if available
No other information will travel with the payment.

All International Endpoints

AddressLine

XXX/CreditorAgent/PostalAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

Optional

Information in this block will travel with payment if available. Please note that only the 105 characters (AddressLine 1 & 2) will travel with the payment to the recipient bank.

All International Endpoints

ForwardContract

XXX/SupplementaryData/ForwardContract/Identification

FX rate contract agreed for conversion of an amount from one currency to another.

Conditional

This block is only required to process the Cross Currency payment using Forward Contract Rate (i.e. pre-agreed rate with AIB only). AIB supports upto 5 Forward Contracts for a payment.This services is only offers to Business / Corporate customers.

All International Endpoints

Reference

XXX/RemittanceInformation/structured/CreditorReferenceinformation/Reference

Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.

Optional

Please note that only the 18 characters will travel with payment to the recipient bank.

All International Endpoints

Unstructured

XXX/RemittanceInformation/Unstructured

Optional

For all payments, the information contained in this tag will travel with the payment to the recipient bank.

Please note that only the 105 characters will travel with the payment to the recipient bank.

For FPS payments, only 70 characters will travel with the payment to the recipient bank.

File Payments

FileReference

OBFile2/FileReference

Reference for the file.

Mandatory

Customer to provide a unique reference to enable reconciliation. AIB supports only 18 alphanumeric characters and will truncate if length is more than 18 characters

File Payments

LocalInstrument

OBFile2/LocalInstrument

This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level

Conditional

Mandatory for SEPA Instant.

Not required for SEPA Standard.

File Payments

RequestedExecutionDateTime

OBFile2/RequestedExecutionDateTime

Date at which the initiating party requests the clearing agent to process the payment.

Usage: This is the date on which the debtor's account is to be debited.

Mandatory

AIB will reject the Consent if date in this field is a past date or if the date is greater than 30 days.

File Payments

Identification

OBFile2/DebtorAccount/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner.

Mandatory

The field is mandatory and must include the Customer OIN.

File Payments

SchemeName

OBFile2/DebtorAccount/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

Mandatory

The SchemeName must be "IE.AIB.OIN".

File Payments

FileType

OBFile2/FileType

Specifies the payment file type.

Mandatory

For ROI should always be IE.AIB.XML

File Payments

NumberOfTransactions

OBFile2/NumberOfTransactions

Number of individual transactions contained in the payment information group.

Optional

AIB will reject the Consent if the value in this field is not the same as the total number of transactions in the file (irrespective of the currency)

File Payments

ControlSum

OBFile2/ControlSum

Total of all individual amounts included in the group, irrespective of currencies.

Mandatory

AIB will reject the Consent if the value in this field is not the same as total amount in the file (irrespective of the currency)

File Payments

AuthorisationType

OBWriteFileConsent3/Data/Authorisation/AuthorisationType

Level of authentications require to authorise the consent

Optional

For all payments, only "Any" value is supported by AIB. AIB default the AuthorisationType as "Any" if tag or no value is present.

AIB will reject the payment request if the value is other than "Any".

File Payments

CompletionDateTime

OBWriteFileConsent3/Data/Authorisation/CompletionDateTime

Defined the date time for the payment order authorisation to be completed

Not Required

AIB does not support this field. AIB will reject the Consent if any value is populated.

Supported Character Set:

a b c d e f g h i j k l m n o p q r s t u v w x y z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

0 1 2 3 4 5 6 7 8 9

/ –. , ‘

Space

Special Rules:

FPS/CHAPS

Only Customers with their account in Branch 238590 can initiate FPS/CHAPS payments with priority as Urgent

Domestic Endpoint

PISP to use Domestic Endpoint only for:
- SEPA Standard Payments (EUR payments to SEPA Reachable Creditor Agent) OR EUR Account Transfer within AIB.
- SEPA Instant Payments (EUR payments to SEPA Instant Reachable Creditor Agent) OR EUR Account Transfer within AIB.
- CurrencyofTransfer is EUR
- Debit Account should be in EUR

International Scheduled Payment Endpoint

International Scheduled payment is only supported for Business / Corporate customers. AIB will reject the International Scheduled Payment Consent for Personal customers and UK Customers.

International Endpoint

PISP to use International Endpoint to :
- Initiate AccountTransfer involving FX or transfer in non-Domestic Currencies within AIB Group.
- Initiate International Payments.
- Initiate FPS/CHAPS payment for NSC 238590.

Purpose of Payment

Mandatory for all International Payments.

Values accepted by AIB;

Code Value

Code Name

BKFE

BankLoanFees

FCOL

FeeCollection

CSDB

CashDisbursementCashManagement

DEPT

Deposit

LIMA

LiquidityManagement

CRPR

CrossProduct

BEXP

BusinessExpenses

GDSV

PurchaseSaleOfGoodsAndServices

CHAR

CharityPayment

HLRP

PropertyLoanRepayment

INTE

Interest

LOAN

Loan

LOAR

LoanRepayment

CCRD

CreditCardPayment

EDUC

Education

GIFT

Gift

IVPT

InvoicePayment

OTHR

Other

RENT

Rent

SAVG

Savings

TREA

TreasuryPayment

HLTI

HealthInsurance

MDCS

MedicalServices

ALLW

Allowance

COMM

Commission

PENS

PensionPayment

SALA

SalaryPayment

LFEE

LendingFees

TAXS

TaxPayment

TAXR

TaxRefund

TRPT

RoadPricing

UBIL

Utilities

GAMB

GamblingOrWageringPayment

Timeout values

Access token
(client credentials grant type)

60 minutes

Access token
(authorisation code grant type)

5 minutes

Authorization code

20 seconds

SCA reauthorisation

Every 180 days

Entering user credentials (customer journey)

If the user is idle for 3 minutes and 50 seconds, they are displayed an inactive screen.
In addition to the 3m50s if the user remains idle, they will be automatically timed out after 1 minute.

Timeout values for international payments:

Access token for international payments
(authorisation code grant type)

40 seconds

Authorization code for international payments

30 seconds

Enumerations supported in ROI

Endpoint: Transactions Endpoint (Account Information Services)

Reference: OBReadTransaction6/Data/Transaction/CreditorAccount

Within the CreditorAccount block the following enumerations are supported:

ROI.PSD.IBAN
ROI.PSD.PAN
ROI.PSD.SortCodeAccountNumber
ROI.PSD.P2P

Supporting permissions (AISP Consent)

The following permissions are supported:

accounts
balances
transactions

AIB only supports the below values for Standing Order Frequency

Weekly (WEEK)
Fortnightly (FRTN)
Every 4 weeks (FOWK)
Monthly (MNTH)
Every 2 months (TWMH)
Quarterly (QURT)
Every 4 months (FOMH)
Half yearly (MIAN)
Annually (YEAR)

And will reject the consent if AIB receive any other values.

Domestic response

Frequency should match with value in "FirstPaymentDateTime" field. In case of mismatch, AIB will reject the Consent.