API Documentation
| 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 90 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 (except Chaps) | 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 | Optional. Only Mandatory for International Payments (and Chaps). |
| 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 FPS payments, Customer/ TPP to provide unique reference which can be used for reconciliation. Up to 35 text supported. |
| 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 "NOT PROVIDED" in the EndToEndIdentification field and will travel with the payment. Up to 35 text supported. |
| All Domestic Endpoints | Reference | XXX/RemittanceInformation.Structured.CreditorReferenceInformation.Reference | Unique reference, as assigned by the creditor, to enable reconciliation by the beneficiary | Optional | For FPS payments, 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. For Non FPS payments, the information will not travel with the payment. |
| 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 Endpoints (including VRP) | SchemeName | XXX/DebtorAccount/SchemeName | Name of the identification scheme, in a coded form as published in an external list. | Mandatory | For all payments, Debtor account must be in UK.OBIE.SortCodeAccountNumber If Debtor account is provided, SchemeName is mandatory. |
| All Endpoints (excluding VRP) | 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 FPS payments, the SchemeName must be UK.OBIE.SortCodeAccountNumber |
| 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. Up to 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. | 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 Up to 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. |
| 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 and 35 characters for SEPA instruction. |
| 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 (and Chaps). 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 | For International payments we support only Shared charging option. ServiceLevel, BorneByCreditor or BorneByDebtor: AIB will reject the Consent with this charging option AIB default the value with "Shared" if tag or no value present. |
| 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 the value not present. All payments with "Urgent" priority will be processed through Swift. To initiate a SEPA payment, priority should be set to "Normal" and Creditor IBAN should be SEPA reachable. |
| 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 a different set of currencies for their Business customers on the basis of InstructionPriority. AIB will reject the Consent if request is received with a currency that is not supported for respective type of customers. UK Business / Corporate Customer: Refer below AIB link for supported currencies https://aibgb.co.uk/content/dam/gb/business/Documents/ways-to-bank/ibusiness-banking/iBB-International-Payments-GB-April-2017.pdf |
| 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 Business / Corporate Customers: If Instructed Currency is not the same as CurrencyOf Transfer, then it should be the same as Debit Account Currency. If this is not the case, 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 (pre-agreed rate with AIB only), and 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 | For UK region value must be "GBP". |
| All International Endpoints | RateType | XXX/ExchangeRateInformation/RateType | Specifies the type used to complete the currency exchange. | Mandatory | Agreed: Only to be used when a customer wants to process the payment using a 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 Unique and unambiguous Dealer Reference. |
| All International Endpoints | 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. CreditorAgent must at least have either of the pairs provided: Scheme Name and Identification or Name and Postal Address. |
| 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] 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.NCC.[ISO3166-aplha2-CountryCode]" customer must provide the valid Bank Code in Identification field (OBInternational2/CreditorAgent/Identification) For SEPA payments, the SchemeName should not be populated , as AIB will derive the BIC for SEPA payments. AIB will reject the Consent if only SchemeName or only Identification is provided. CreditorAgent must at least have either of the pairs provided: Scheme Name and Identification or Name and Postal Address. |
| 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 up to 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 | If provided, this information will travel with the payment. |
| All International 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.Please note that only the 105 characters will travel with the payment to the recipient bank. |
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: - CurrencyofTransfer is GBP - Debit Account should be in GBP |
| 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. |
| International Endpoint | International payment is only supported for Business / Corporate customers. AIB will reject the International Payment Consent for Personal customers.PISP to use International Endpoint to : - Initiate SEPA Payments for UK Customers. - Initiate AccountTransfer involving FX or transfer in non-Domestic Currencies within AIB Group . - Initiate International Payments. |
P7 Refunds
- Functionality allowing TPPs to receive customer account details for potential future refunds.
- Applies to all PISP Domestic & International endpoints.
- Does not apply to File Payments.
- TPP submits ReadRefundAccount field within the Data block of the Consent Request (e.g. POST /domestic-payment-consents)
- Field allows for only 2 values; Yes and No.
- Only the ReadRefundAccount field is passed back in the Consent Response
- No additional fields required from TPPs in Payment Order request(e.g. POST /domestic-payments)
- Customer account details are passed back within the Payment Order response & responses to any GET requests (e.g. POST /domestic-payments & GET /domestic-payments/{DomesticPaymentId})
- Domestic response:
Refund block within the Data block, containing Account block. Below data is returned in the Account block:
SchemeName – the name of the identification scheme (e.g. UK.OBIE.IBAN)
Identification – the Customer account details, i.e. the Debit Account number
Name – the name of the account owner on the Debit Account
- International Response:
As Domestic, but with an additional Agent block containing:
SchemeName – the name of the identification scheme (e.g. UK.OBIE.BICFI)
Identification – the AIB BIC (ROI) or Sort Code (UK) for identifying the destination bank for non-SEPA refunds.
P8 SCA Exemptions
- Applies to all PISP endpoints, including File Payments
- Consent requests can include an optional SCASupportData block within the Data block, containing the following fields:
RequestedSCAExemptionType – the SCA Exemption being requested. Values must be as per the OBExternalSCAExemptionType1Code code class.
AppliedAuthenticationApproach – specifies whether the Customer was subject to SCA by the TPP. Values must be as per the OBExternalAppliedAuthenticationApproach1Code code class.
ReferencePaymentOrderId – the payment reference for the last payment where it is a recurring payment.
- This data is accepted on an Accept & Store basis only.
Purpose of Payment
Mandatory for all International Payments and Chaps 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 |
DestinationCountryCode
- Applies to International endpoints only.
- DestinationCountryCode appears in the Initiation block of the Consent request & is mandatory for all International payments.
- If the CreditorAgent/PostalAddress/Country is included in the payload, it must match the DestinationCountryCode.
File payments:
We support the following UK file payments in CSV file format.
a) UK.AIB.APACS.Credit
b) UK.AIB.APACS.Debit
c) UK.AIB.CSVExcel.Credit
d) UK.AIB.CSVExcel.Debit
Requirements for file uploading:
The File structure must match the File Type mentioned in the metadata payload
- File Type - must be in APACS, CSV (Excel)
- File Size Limit - 5 MB
- Hash of the file must match the File Hash in the consent request.
- No Of txns and Control sum if provided should match the actual count with the file.
- If the File fails a validation, the status of consent will appear as "Rejected"
| Access token (client credentials grant type) |
60 minutes |
|---|---|
| Access token (authorisation code grant type) |
5 minutes |
| Authorization code | 20 seconds |
| SCA reauthorisation | Every 90 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 |
The following CMA permissions are supported:
- beneficiaries
- standing-orders
- direct-debits
- products
Example scope in the consent setup request:
{
"Data": {
"Permissions": [
"ReadAccountsDetail",
"ReadBalances",
"ReadTransactionsDetail",
"ReadTransactionsCredits",
"ReadTransactionsDebits",
"ReadBeneficiariesDetail",
"ReadDirectDebits",
"ReadStandingOrdersDetail",
"ReadProducts"
],
"ExpirationDateTime": "2020-12-01T00:30:44.954Z",
"TransactionFromDateTime": "2019-11-01T08:59:52.482Z",
"TransactionToDateTime": "2019-12-01T08:59:52.482Z"
},
"Risk": {}
}
These permissions can be included in the scope of the POST /account-access-request API call across the AIB GB and AIB (NI) (formerly First Trust Bank) regions.
Please note, these permissions are not permitted for the ROI region. Should the scope include these permissions when calling the /account-access-request ROI endpoint the POST request will be immediately rejected, preventing the customer from being taken to the OAuth redirect flow.
Handling Credit Cards:
These permissions are not supported for Credit Cards. Where the scope of the API request includes all or any one of these CMA permissions, the customer will not have the ability to select their credit card(s) within the OAuth redirect. The OAuth redirect will display non-Credit Card accounts only where CMA permissions are included in the scope.
In order to share both credit card data and data on accounts (current and/or deposit) where CMA permissions are included, TPPs will require two apps defined on the AIB gateway within the region they wish to operate in i.e. if working with GB clients and utilising the GB API suite, two apps will be required on the AIB GB environment.
- 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
Frequency should match with value in "FirstPaymentDateTime" field. In case of mismatch, AIB will reject the Consent.