# Domestic Payment Initiation Consent source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/payment-initiation-consent-request/index.md ## Request overview {#request-overview} The goal of this request is to create the consent that is authorized by the Payment Service User (PSU) for the initiation of a domestic payment. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |----------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | /payments/domestic-credit-transfers/consents | `POST` | CMA9, Polish API, NextGenPSD2, Budapest Bank, Czech Open Banking Standard API Profile, Slovak Banking API Standard API Profile | Submits domestic payment consent | The following sequence diagram shows the flow for initiating domestic payment consent. Diagram domestic_payment_initiate_consent ## Request scenario {#request-scenario} API Reference: `POST /payments/domestic-credit-transfers/consents` ### Request header {#request-header} N/A #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `requestInfo` | Includes information about the request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | A set of elements used to define the request details | N/A | | `xRequestId` | The ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | String UUID | Free field that allows for the addition of information that can be referenced for future use | 36 `pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `tppRedirectURI` | URI of the TPP, where the transaction flow shall be redirected to after a Redirect | ASPSP | This element is used to specify the URI where should be redirected PSU after consent authorization | M | 1..1 | String | Call back URI where to redirect the PSU after authorization of the consent | 1-256 | | `aspspId` | ID of a financial institution servicing the Accounts of the PSU | ASPSP | Identification of ASPSP | M | 1..1 | String UUID | This element is used to specify the identification code of a financial institution which holds PSU accounts | 36 pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `isLivePsuRequest` | Indicates if PSU actively initiated the request | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean: true or false | | `psuIPAddress` | The forwarded IP address field consists of the corresponding HTTP request IP address field between PSU and TPP. | ASPSP | It shall be contained only if the PSU actively initiated this request | C | 0..1 | String | IP address of PSU's terminal device | 1-256 Required when isLivePsuRequest=true pattern: `(^(([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])\.){3}([0-9]` \| `[1-9][0-9]` \| `1[0-9]{2}` \| `2[0-4][0-9]` \| `25[0-5])$)` \| `(^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,7}:` \| `([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}` \| `([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}` \| `([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}` \| `([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}` \| `([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}` \| `[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})` \| `:((:[0-9a-fA-F]{1,4}){1,7}` \| `:)` \| `fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}` \| `::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])` \| `([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]` \| `(2[0-4]` \| `1{0,1}[0-9]){0,1}[0-9]))$)` | | `psuAgent` | Indicates the user-agent for the PSU. If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings. | ASPSP | If a user-agent is supplied to ASPSP, then this information can be used by ASPSP's security mechanisms. To avoid rejections, it is recommended to include this field when providing isLivePsuRequest and psuIPAddress. | O | 0..1 | String | PSU's browser agent details | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | Set of elements used to define the merchant details | N/A | | `id` | Merchant identification code to identify the merchant | MC | Unique Merchant identifier per TPP, which could be used for reporting/reconciliation purposes | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant ID | 1-256 | | `name` | Merchant name to identify the merchant | MC | Name of merchant | M | 1..1 | String | Field is available for TPPs to enable capturing of a merchant name | 1-256 | | `credentials` | Send PSU credentials to ASPSP that support embedded flow | ASPSP | Include the ID and value for each credential required by the ASPSP | O | 0..1 | Object | A set of elements used to define the credentials provided by the PSU. Data map \<\\string, string\> | Maximum 20 value pairs. Maximum 50 symbols for each ID and value. A list of supported credentials can be received in response to Get List of ASPSP request | | `flags` | The list of flags which can set the additional parameters in returned data | MC | This element is used to specify additional parameters which influence data returned in response | O | 0..1 | Enum | Request information flags which can influence the behavior or returned data | Enum: \[`Return.Raw.Consent`,'RETURN_REFUND_ACCOUNT'\] 'Contact your Mastercard contact, to request enabling of refund capability, before submitting a payment initiation consent request with `RETURN_REFUND_ACCOUNT` flag' | | `payments` | The object contains the list of fields used to send a payment instruction to a financial institution | MC | This element encapsulates all payment fields | M | 1..1 | Object | A set of elements used to define the payments details | N/A | | `endToEndIdentification` | Unique identification assigned by the TPP to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. | ASPSP | The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. | M | 1..1 | String | Field is available for TPPs to enable end-to-end identification of the transaction | 1-18 | | `localInstrument` | User community-specific instrument | ASPSP | This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level. | M | 1..1 | Enum | User community-specific instrument specifies which clearing system should be used to process the payment instruction | Enum: \["UK.FasterPayments", "PL.Elixir", "HU.DomesticNonEuro"\] | | `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 | ASPSP | This element is used to specify urgency mode of the payment. | C | 1..1 | String Enum | The way the transfer should be settled | Enum: `Normal`, `Urgent` Mandatory if localInstrument = `PL.Elixir` | | `instructedAmount` | The amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the TPP | ASPSP | This amount has to be transported unchanged through the transaction chain | M | 1..1 | Object | Structure aiming to embed the amount and the currency to be used | N/A | | `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" | ASPSP | The currency of the amount used in the transaction | M | 1..1 | Enum | Specifies the currency of the amount or of the account | Enum: `GBP`, `PLN`, `HUF` GBP (mandatory if localInstrument = `UK.FasterPayments`) PLN (mandatory if localInstrument = `PL.Elixir`) HUF (mandatory if localInstrument = HU.DomesticNonEuro) | | `amount` | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. | ASPSP | This element is used to specify the amount of money to be processed | M | 1..1 | Decimal | Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the TPP | Double, min: 0 | | `creditorAccount` | Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. | ASPSP | Specify an account in a financial institution servicing the creditor | M | 1..1 | Object | A set of elements used to define the creditor account details | N/A | | `schemeName` | The name of the identification scheme, in a coded form as published in an external list. | ASPSP | This field is used to identify the type of identification used to identify an account. | C | 1..1 | Enum | Account scheme name | Enum: `UK.AccountNumber`, `PL.AccountNumber`, `IBAN` `UK.AccountNumber` - if localInstrument =`UK.FasterPayments` `PL.AccountNumber` -- if localInstrument =`PL.Elixir`**IBAN - if localInstrument = `HU.DomesticNonEuro`** | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner. | ASPSP | This element is used to specify the account identification number | M | 1..1 | String | Account identification which can be used on payload-level to address specific accounts | 1-256 | | `creditorAgent` | Unambiguous identification of the financial institution of the creditor to which a credit entry will be posted as a result of the payment transaction. | ASPSP | Specify the financial institution servicing an account for the creditor. | C | 0..1 | Object | A set of elements used to define the creditor agent details | Mandatory for `UK.FasterPayments` and NOT used for `PL.Elixir` | | `clearingSystemIdentification` | The name of the identification scheme, in a coded form as published in an external list. | ASPSP | This field is used to identify the type of identification used to identify an agent. | M | 1..1 | Enum | Clearing system identification scheme | Enum: `UK.SortCode`, `BIC` Mandatory if localInstrument is UK.FasterPayments or HU.DomesticNonEuro BIC - if localInstrument = `HU.DomesticNonEuro` | | `memberIdentification` | A code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | M | 1..1 | String | Identification code to identify the financial institution | 1-256 Mandatory if localInstrument is = `UK.FasterPayments` | | `creditorName` | The name by which a party is known, and which is usually used to identify that party. | ASPSP | This element is used to specify creditor name | M | 1..1 | String | Name of the Beneficiary/Creditor | 1-70 | | `creditorAddress` | Information that locates and identifies a specific address, as defined by postal services. | ASPSP | This element is usually used to identify the creditor party address. | C | 1..1 | Object | A set of elements used to define the creditor address details | N/A | | `street` | Name of a street or thoroughfare | ASPSP | This element is used to specify the street name | M | 1..1 | String | Street name | 1-70 | | `buildingNumber` | A number that identifies the position of a building on a street. | ASPSP | This element is used to specify the building number | M | 1..1 | String | Building number | 1-256 | | `city` | Name of a built-up area, with defined boundaries, and a local government. | ASPSP | This element is used to specify the city name | M | 1..1 | String | City name | 1-256 | | `postalCode` | Identifier consisting of a group of letters and, or, numbers that are added to a postal address to assist the sorting of mail. | ASPSP | This element is used to specify the post code | M | 1..1 | String | Postal code | 1-256 | | `countrySubDivision` | Identifies a subdivision of a country such as state, region, county. | ASPSP | This element is used to specify the county code | O | 0..1 | String | County name | 1-256 | | `country` | The country in which a person resides | ASPSP | This element is used to specify the country code | M | 1..1 | String | Country name | ISO 3166 ALPHA 2 CHAR | | `remittanceInformationUnstructured` | 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. | ASPSP | Description of the payment | C | 0..1 | String | If available, the TPP should provide this information in the unstructured remittance form | 1-140 Mandatory if localInstrument = `PL.Elixir` | | `requestedExecutionDate` | The date at which the TPP requests the clearing agent to process the payment. | ASPSP | This is the date on which the debtor's account is to be debited. | C | 0..1 | ISODate | Date when the transfer is to be executed (It is used for Future Dated payments) | ISODate, YYYY-MM-DD The requestedExecutionDate field and schedule object are both optional and mutually exclusive fields | | `schedule` | Schedule object is used for standing orders. | ASPSP | Can be used to initiate a domestic standing orders payment instruction | C | 0..1 | Object | A set of elements used to define the schedule details | The schedule object and `requestedExecutionDate` field are both optional and mutually exclusive fields | | `startDate` | The first date of execution for a standing order. | ASPSP | This element is used to specify the first payment date | M | 1..1 | ISODate | Payment first execution date | ISODate, YYYY-MM-DD | | `frequency` | Frequency rule for standing orders. | ASPSP | This element is used to specify the frequency of a payment | M | 1..1 | Enum | Payment frequency -determines how often a recurring payment will be made | Enum: · `DAIL` - daily · `WEEK` - weekly · `MNTH` - monthly · `QUTR` - quarterly · `SEMI` - semi-annually · `YEAR` - yearly · `PATTERN` - pattern | | `frequencyPattern` | Sets the rule for creating scheduled payments. | ASPSP | This element is used by ASPSPs as a guidance for creating each recurrent payment of a Standing Order which refers to customized time intervals | C | 0.1 | String | This is a specific format of describing the rule for creating the payments of a Standing Order. It should comply with one of the permitted patterns. Full pattern represented as a regular expression which will be used for validating the value provided in this field: \^(EvryDay)$ \^(EvryWorkgDay)$ \^(IntrvlWkDay:0\[1-9\]:0\[1-7\])$ \^(WkInMnthDay:0\[1-5\]:0\[1-7\])$ \^(IntrvlMnthDay:(0\[1-6\] 12 24):(-0\[1-5\] 0\[1-9\] \[12\]\[0-9\] 3\[01\]))$ \^(QtrDay:(ENGLISH SCOTTISH RECEIVED))$ | Mandatory when "PATTERN" value is selected in the Frequency field. Individual pattern definitions: EvryDay - Every day EvryWorkgDay - Every working day IntrvlWkDay - An interval specified in weeks (01 to 09), and the day within the week (01 to 07) WkInMnthDay - A monthly interval, specifying the week of the month (01 to 05) and day within the week (01 to 07) IntrvlMnthDay - An interval specified in months (between 01 to 06, 12, 24), specifying the day within the month (-5 to -1, 1 to 31) QtrDay - Quarterly (either ENGLISH, SCOTTISH, or RECEIVED) ENGLISH = Paid on the 25th March, 24th June, 29th September and 25th December. SCOTTISH = Paid on the 2nd February, 15th May, 1st August and 11th November. RECEIVED = Paid on the 20th March, 19th June, 24th September and 20th December. | | `endDate` | The last applicable day of execution for a given standing order. If not given, the standing order is considered as endless, until canceled by the PSU. | ASPSP | This element is used to specify payment last execution date. | O | 0..1 | ISODate | Payment last execution date | ISODate, YYYY-MM-DD | | `numberOfPayments` | Specifies the number of payments which will be created by this Standing Order. | ASPSP | This element is used to specify the number of recurrent payments to be done while not specifying an endDate. | O | 0..1 | Integer | Number of payments that will be made in completing this frequency sequence including any executed since the sequence start date | numberOfPayments and endDate are both optional and mutually exclusive. Note that the numberOfPayments value included in a request intended for an ASPSP supporting the Polish API standard will be ignored. | | `remittanceInformationReference` | Reference information provided by the creditor to allow the identification of the underlying documents | ASPSP | If available, the TPP should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money. | O | 0..1 | String | Reference information, as assigned by the creditor, to unambiguously refer to the payment transaction | 1-18 | | `debtorAccount` | Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction | ASPSP | Specify an account in a financial institution servicing the debtor | C | 0..1 | Object | A set of elements used to define the debtor account details | If localInstrument = `UK.FasterPayments` and `debtorAgent` was specified, then becomes mandatory If localInstrument = `PL.Elixir` and `debtorAgent` was specified, then becomes mandatory If localInstrument='HU.DomesticNonEuro', then becomes mandatory. If `debtorName` was specified, then becomes mandatory. | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner | ASPSP | This element is used to specify the account identification number | M | 1..1 | String | Account identification which can be used on payload-level to address specific accounts. | 1-256 If localInstrument = 'UK.FasterPayments' and debtorAgent was specified, then this needs to be a UK Account number (8 digits) If localInstrument='HU.DomesticNonEuro' then this needs to be IBAN. | | `debtorName` | The name by which a party is known, and which is usually used to identify that party. | ASPSP | This element is used to specify the debtor name | O | 0..1 | String | Debtor name | 1-256 debtorName data is sent without providing debtorAccount details, the request fails and an error is returned. | | `debtorAgent` | Unambiguous identification of the financial institution of the debtor to which a debit entry will be made as a result of the transaction | ASPSP | Specify the financial institution servicing an account for the debtor | C | 0..1 | Object | A set of elements used to define the debtor agent details | If localInstrument = `UK.FasterPayments` and debtorAccount was specified then becomes mandatory If localInstrument='HU.DomesticNonEuro' then becomes optional | | `memberIdentification` | A code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | C | 0..1 | String | Identification code to identify the financial institution. | 1-256 If localInstrument = `UK.FasterPayments` and debtorAccount was specified, then this needs to be a UK Sort code (6 digits) If localInstrument='HU.DomesticNonEuro' then this is BIC | | `identification` | A code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | C | 0..1 | String | Identification code to identify the financial institution. | 1-256 If localInstrument = `UK.FasterPayments` and debtorAccount was specified, then this needs to be a UK Sort code (6 digits) If localInstrument='HU.DomesticNonEuro' then this is BIC The identification field will be overridden by memberIdentification when both are provided. | | `instructionIdentification` | Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. | ASPSP | The instruction identification is a point-to-point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. | O | 0..1 | String | Unique identification shared between the PISP and the ASPSP | 1-256 | | `risk` | The object contains the list of fields used to send risk information to a financial institution. | ASPSP | It is used to specify additional details for risk scoring for payments. | O | 0..1 | Object | A set of elements used to define the risk scoring details | The object is specific for the CMA9 profile | | `paymentContextCode` | Information that specifies the context for a payment. | ASPSP | Specifies the payment context | O | 0..1 | Enum | Payment context code | Enum: `BillPayment`, `EcommerceGoods`, `EcommerceServices`, `Other`, `PersonToPerson`, `BillingGoodsAndServicesInAdvance`, `BillingGoodsAndServicesInArrears`, `PispPayee`, `EcommerceMerchantInitiatedPayment`, `FaceToFacePointOfSale`, `TransferToSelf`, `TransferToThirdParty` The `PispPayee` value can be used for banks complying to v3 of the OBIE specifications. All other values are recommended for banks migrating to v4.0 of the specifications. Note that if invalid risk details are provided, PCC for example, an empty risk object will be sent to the ASPSPs to reduce the probability of rejections. | | `merchantCategoryCode` | The Category code conforms to ISO 18245, related to the type of services or goods the merchant provides for the transaction. | ASPSP | Unique merchant category code | O | 0..1 | String | Field is available to enable capturing of a merchant category code | 1-256 OBIE specifications recommend sending strings of 3-4 characters | | `merchantCustomerIdentification` | The field is to enable capturing of a merchant's PSU unique identifier. | ASPSP | Used to specify the merchant's PSU identifier. | O | 0..1 | String | The unique customer identifier of the PSU with the merchant. | 1-256 OBIE specifications recommend sending strings of max 70 characters | | `deliveryAddress` | Information that locates and identifies delivery address. | ASPSP | This element is usually used to identify the delivery address. | O | 0..1 | Object | A set of elements used to define the delivery address details | - | | `addressLine` | Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. | ASPSP | This element is used to specify the specific postal address | O | 0..1 | String | Address line | 1-70 | | `street` | Name of a street or thoroughfare | ASPSP | This element is used to specify the street name | O | 0..1 | String | Street name | 1-70 | | `buildingNumber` | A number that identifies the position of a building on a street. | ASPSP | This element is used to specify the building number | O | 0..1 | String | Building Number | 1-16 | | `postalCode` | This element is used to specify the post code | ASPSP | This element is used to specify the post code | O | 0..1 | String | Postal code | 1-16 | | `city` | Name of a built-up area, with defined boundaries, and a local government. | ASPSP | This element is used to specify the city name | M | 1..1 | String | City name | 1-35 | | `countrySubDivision` | Identifies a subdivision of a country such as state, region, county. | ASPSP | This element is used to specify the county code | O | 0..1 | String | County name | 1-35 | | `country` | The country in which a person resides | ASPSP | This element is used to specify the country code | M | 1..1 | String | Country name | ISO 3166 ALPHA 2 CHAR | | `contractPresentIndicator` | Used to show that there is a contractual relationship between the TPP and the creditor (beneficiary) of the payment | ASPSP | This element shows that a contract exists between the creditor and TPP | O | 0..1 | Boolean | Flag indicating if the creditor has a contractual relationship with the TPP. | True, False (future use) | | `beneficiaryPrepopulatedIndicator` | Used to show that TPP has added payment details | ASPSP | This element shows that TPP populated payment details and PSU has not changed them in the transaction journey | O | 0..1 | Boolean | Indicates if TPP has immutably pre-populated payment details in for PSU. | True, False (future use) | | `paymentPurposeCode` | Category code of the services/goods | ASPSP | This element is included to show the purpose of the payment | O | 0..1 | String | Category code, related to the type of services or goods that corresponds to the purpose of the payment. It conforms to ISO 20022 defined values. | | | `beneficiaryAccountType` | The type of the creditor account | ASPSP | This element is used to add details about the creditor's account type | O | 0..1 | String, Enum: "Personal", "Business" | Account type of the beneficiary. | (future use) | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). For specific error codes for this feature see **Feature specific error codes** below. #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |-----------------------|--------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | String UUID | Original `xRequestId` given by the client on request | 36 | | `aspspSCAApproach` | Type of links admitted in this response | MC | This element is used to specify the SCA link types | O | 0..1 | String Enum | Strong Customer Authentication (SCA) Approach | Enum: `REDIRECT` | | `consentRequestId` | Unique identification as assigned by the TPP to uniquely identify the consent request. | TPP | This element could be used for consent request- response tracking | O | 0..1 | String | Request consent identification | 1-256 | | `_links` | The list of link types admitted in response, (further links might be added for ASPSP defined extensions) | MC | The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. | O | 0..1 | object | A set of elements used to define the links details | N/A | | `scaRedirect` | In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browser | TPP | This element is used to specify the URL where the PSU should be redirected for consent authorization | O | 0..1 | String URL | The URL used to redirect the PSU for authentication and authorization of the consent | | | `additionalData` | Specifies additional parameters in returned data | TPP | This element is used to specify additional parameters returned in response | C | 0..1 | Object | Set of elements used to define the additional data details | Returned only if requestInfo.flags had at least one flag | | `rawConsent` | Returns raw consent data from associated ASPSP | TPP | Raw consent data could be used to extract additional information sent by ASPSP | C | 0..1 | String | Raw consent data received from ASPSP and encoded in Base64. | Returned only if requestInfo.flags contained `Return.Raw.Consent` value | | `returnRefundAccount` | Specifies the consent provided by the PSU to TPP to share debtor account details | TPP | It can be used to filter out payments which could be reversed based on the debtor account details to be provided by the ASPSP | O | 0..1 | Boolean | This information flags to the TPP that debtor account details will be available from the ASPSP in response to subsequent calls to Credit transfer and Payment status endpoints | | Alert: The OBIE, in alignment with the security community, recommends the use of the Hybrid flow. The platform today enforces this by setting the initial response type to **code id_token** in the authorization request to the ASPSP's Authorization Server. The Authorization server is required to return both the access code and id_token in this case, but the manner in which it does this is left to the discretion of the Authorization Server. This could be in either form: * TPP_REDIRECT_URL?All_Params * TPP_REDIRECT_URL#All_Params
The current best practice is to return these values as a hash fragment. This allows the User Agent to receive the values and skip redirection (performance enhancement), and not send the access code through a query string parameter where it will be logged by proxies, firewalls, application servers, and other services in the application path. Having the access code logged in plain text would weaken its value. For this reason, it is suggested that the TPP application parse the access code from the hash fragment and POST it to the Client Service (TPP service) in an AJAX request, where the value may be safely ensconced within the POST body. An example of a URL received by TPP containing the authorization string can be seen below. The authorization string starts after the "#". `https://www.mastercard.com/en-us.html#code=bd9691ea-73a3-4c12-96e3-16e11680e10b&id_token=eyJhbGciOiJQUzI1NiIsImtpZCI6InprYm9LRmpRUndCZDlVRW5QQzV3bHY1N2lnNCJ9.eyJzdWIiOiJhYWMtZDBjNzJmNmQtOGQ5OS00NzVmLTg2YTYtMjUwZGI0MjkwMWNkIiwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjoiYWFjLWQwYzcyZjZkLThkOTktNDc1Zi04NmE2LTI1MGRiNDI5MDFjZCIsImlzcyI6Imh0dHBzOi8vb2IxOS1hdXRoMS11aS5vM2JhbmsuY28udWsiLCJhdWQiOiJiMzliZTYzYi03MjIyLTQyZDEtYTNkZS0yNzVjMDkwODk2ZTIiLCJpYXQiOjE2MDc2MDk2NDMsImV4cCI6MTYwNzYxMzI0Mywibm9uY2UiOiI5NWU2NjExMC1kNTdjLTRjYmEtODVkZS02YmY0OTIwNjUxM2QiLCJhdXRoX3RpbWUiOjE2MDc2MDk2NDMsImF6cCI6ImIzOWJlNjNiLTcyMjItNDJkMS1hM2RlLTI3NWMwOTA4OTZlMiIsInJlZnJlc2hfdG9rZW5fZXhwaXJlc19hdCI6MTYwNzk5ODQ0MywiY19oYXNoIjoicUM3bVZ4V2FKaWpRTVlnQ0l3RFYyQSIsInNfaGFzaCI6IkFmUUUwT1hoQUV5WFlydGpjTjMtMFEiLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EifQ.NuPBxx8xQ2phh2G1DHVNgIhvA4Qf0zQSu45AR9ZzsD9pWdiAO4XCP56K2yckWNOZ15L4Kv_49Ta8AGVQANA-dcMahasq4YNDuXTP3muhQqR3A-WI8BfUtJkfG3szbINP498u61YC-CRuIPSEP1EodfLaUZPVm217XJygWp12KgfS-YApJoGdS5hjKwrvV1isxH3-skHbuvrY9f2UH78ikUz7qWD_Ux8sfmAaMw1y3AXVh193AbLq3XYeVMkUtUUFLZvUJiOZScmB36vYdy4YG7bYPeTgzFlEAkQVJstRGo3fz9VDePET3rNknY8eGYnphZ7BXH6eVcuOWSCgReAg0A&state=dG9rZW5pby1zdGF0ZQ__rq-qBaUX1N8TQX3hmAxreELWNmT3Z9-5zKtXEAq__` An edge case has been identified in which both a query string and hash fragment may be present as shown below. ![edge case](https://static.developer.mastercard.com/content/open-banking-connect/img/edge-case.png) Our suggestion to handle all situations is to develop a snippet as follows: Check for call-back URL -\> * 'Fragment' character (#) and send those parameters to the back-end for processing, ignoring 'query string' (?), if it exists. * Only if 'fragment' (#) does not exist, look for 'query string' (?) and send those parameters to the back-end. ## Feature-specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | N/A | `INACTIVE_URL` | The value provided for the tppRedirectURI parameter is invalid. Only URIs that have been registered with OBIE can be used by TPP. | N/A | This typically occurs when the URI has a typo or was incorrectly copied. | Make sure that to populate the value of the tppRedirectURI field, you are using a URI that was registered as an allowlisting entity with Open Banking Connect API as part of the onboarding details. If you think you should be able to use the specified value, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INACTIVE_URL" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------------------------------------------------|--------------------------|----------------------------------------------------------------------|----------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | "\[Path path\[i\]\] Numeric instance is lower than the required minimum (minimum: 0, found: %s)" | `INVALID_PAYMENT_AMOUNT` | The value provided for the instructedAmount is less or equal to zero | Return as path to the element that failed the validation | This typically occurs due to the submitting user's error. | Ensure that a value greater than 0 is populated as instructedAmount and re-submit the message. A standard amount format should be used. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_PAYMENT_AMOUNT", "Description": "[Path '/payments/instructedAmount/amount'] Numeric instance is lower than the required minimum (minimum: 0, found: -2)", "Details": "path[0]=/payments/instructedAmount/amount" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Execution Date cannot be in the past". | `FORMAT_ERROR` | The value provided for the `requestedExecutionDate` is in the past. This is an invalid scenario as this field is usually used to request a future dated payment | path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs due to submitting a user's error. | Ensure that a value populated in `requestedExecutionDate` is a present or future date and re-submit the message. The Open Banking Connect API has no limit for future date, but it could be on the ASPSP side. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Execution Date cannot be in the past", "Details": "path[0]=/payments/requestedExecutionDate" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------| | "End date is lower than start date." | `STARTDATE_GREATER_THAN_ENDDATE` | The value provided for the startDate is greater than the endDate. This is an invalid scenario as the selected dates should define the start and end dates of the Settlement Order's payment schedule. | Return as path to the element that failed the validation | This error typically occurs due to submitting user's error. | Ensure that a value populated in startDate is lower than or equal the endDate and re-submit the message | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "STARTDATE_GREATER_THAN_ENDDATE", "Description": "End date is lower than start date" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | "startDate and/or endDate cannot be a date from the past." | `INVALID_STARTDATE_OR_ENDDATE` | The value provided for the startDate or endDate is in the past. This is an invalid scenario as the selected dates should define the start and end dates of the Settlement Order's payment schedule. | Return as path to the element that failed the validation | This error typically occurs due to submitting a user's error. | Ensure that a value populated in startDate and endDate are present or future dates and re-submit the message | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "INVALID_STARTDATE_OR_ENDDATE", "Description": "End date is lower than start date" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| | "\[Path path\[i\]\] String %s is invalid against requested date format(s) yyyy-MM-dd" | `FORMAT_ERROR` | The value provided for the startDate or endDate does not comply with standard format, YYYY-MM-DD for example. | Return as path to the element that failed the validation | This error typically occurs with and invalid entry of MM-DD-YYYY. | Ensure that a value populated in startDate and endDate complies with the following format: YYYY-MM-DD | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "[Path '/payments/schedule/endDate'] String "20202-04-18" is invalid against requested date format(s) yyyy-MM-dd", "Details": "path[0]=/payments/schedule/endDate" }, { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "[Path '/payments/schedule/startDate'] String "20-03-18" is invalid against requested date format(s) yyyy-MM-dd", "Details": "path[0]=/payments/schedule/startDate" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "It is unclear what payment is requested - Future Dated or Standing Order. " | `UNCLEAR_PAYMENT_INSTRUCTION` | The request contains both `requestedExecutionDate` and schedule elements populated. This is an invalid scenario, as the former defines a future dated payment, and the later defines a Standing Order. | Return as path to the element that failed the validation | This typically happens when dates are not populated in the schedule section to initiate a Standing Order payment. | Ensure that only one element is populated; that is, either `requestedExecutionDate` in case you want to initiate a Future Dated Payment or populate the necessary fields in the schedule section to initiate a standing order based on defined schedule. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "UNCLEAR_PAYMENT_INSTRUCTION", "Description": "It is unclear what payment is requested - Future Dated or Standing Order" ] } } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------|-----------------|--------------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Method not supported by Provider's API profile" | `NOT_FOUND` | Failed to provide a supported localInstrument in PI Consent. | N/A | This typically occurs when TPP does not use a valid localInstrument value supported by their API Standard. | Make sure that you select one of the specified values for the localInstrument field based on the specification. Also make sure that you are filling in all the dependent fields according to the specification before re-submitting the message | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "NOT_FOUND", "Description": "Method not supported by Provider's API profile" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Invalid currency for selected localInstrument" | `FORMAT_ERROR` | Failed to provide required currency details for selected localInstrument in PI consent. Consult the API specification for field dependencies. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when TPP does not fill in dependent fields for their API standard. | Make sure that you are filling in currency field with the corresponding value to the selected localInstrument according to the specification before re-submitting the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Invalid currency for selected localInstrument", "Details": "path[0]=/payments/instructedAmount/currency" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| | "Conditional field RemittanceInformationUnstructured is expected for selected localinstrument" | `FORMAT_ERROR` | Failed to provide the RemittanceInformationUnstructured field in the request to an ASPSP with Polish API standard. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and son on, for each element that failed the validation | This typically occurs when the TPP does not fill in dependent fields for their API standard, "RemittanceInformationUnstructured". | Ensure that a value populated in RemittanceInformationUnstructured is present and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": " Conditional field RemittanceInformationUnstructured is expected for selected localinstrument ", "Details": "path[0]=/payments/remittanceInformationUnstructured" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | "Conditional field creditorAddress is expected for selected localinstrument" | `FORMAT_ERROR` | Failed to provide the creditorAddress object in the request to an ASPSP with the Polish API standard. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP does not fill in dependent fields for their API standard, "creditorAddress" object. | Ensure that all needed values populated in the creditorAddress object are present and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field creditorAddress is expected for selected localinstrument", "Details": "path[0]=/payments/creditorAddress" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | "Usage of schemeName does not match selected localInstrument" | `FORMAT_ERROR` | Failed to provide the schemeName value that corresponds to the localInstrument value in request. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP provides schemeName value `UK.AccountNumber` or IBAN for localInstrument= `PL.Elixir` or schemeName value 'PL.AccountNumber' or IBAN for localInstrument= 'UK.FasterPayments' or AccountNumber for localInstrument= 'HU.DomesticNonEuro'. | Ensure that the schemeName value populated in the creditorAccount object corresponds to the localInstrument value and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Usage of schemeName does not match selected localInstrument", "Details": "path[0]=/payments/creditorAccount/schemeName" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------|-----------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | "Usage of creditorAgent does not match selected localInstrument" | `FORMAT_ERROR` | Do not provide creditorAgent in the request with localInstrument = `PL.Elixir`. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP provides creditorAgent parameter for localInstrument `PL.Elixir`. | Ensure that creditorAgent parameter is missing for localInstrument= `PL.Elixir` (as required by Polish API profile) and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Usage of creditorAgent does not match selected localInstrument", "Details": "path[0]=/payments/creditorAgent" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Payment details are not aligned with selected localInstrument" | `FORMAT_ERROR` | Failed to provide clearingSystemIdentification field in the request with localInstrument = `UK.FasterPayments`. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP does not provide a clearingSystemIdentification field in request where localInstrument is 'UK.FasterPayments' or HU.DomesticNonEuro. | Ensure that the clearingSystemIdentification field is included for localInstrument= 'UK.FasterPayments' (as required by CMA9 API profile) and for 'HU.DomesticNonEuro' localInstrument (as required by NextGenPSD2, Slovak and Czech APIs), and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Payment details are not aligned with selected localInstrument", "Details": "path[0]=/payments/creditorAgent" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------------------------------|-----------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Usage of instructionPriority does not match the selected localInstrument" | `FORMAT_ERROR` | instructionPriority field's use does not correspond to API profile specifications. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP provides instructionPriority field in request where localInstrument is 'UK.FasterPayments' or when does not provide instructionPriority field in request where localInstrument is `PL.Elixir`. | Ensure that instructionPriority field is not included for localInstrument= 'UK.FasterPayments' (as required by CMA9 API profile) and not included for localInstrument ='HU.DomesticNonEuro', or included for localInstrument= `PL.Elixir` (as required by Polish API profile) and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": " Usage of instructionPriority does not match selected localInstrument", "Details": "path[0]=/payments/instructionPriority" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Usage of debtorAccount does not match selected localInstrument" | `FORMAT_ERROR` | The combination of debtorAccount and debtorAgent fields inclusion in the request does not correspond to API profile specifications. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP for localInstrument= 'UK.FasterPayments' provides only the debtorAgent field. Or, if debtorAccount was not provided when localInstrument ='HU.DomesticNonEuro'. Otherwise it occurs when TPP for localInstrument= `PL.Elixir` provides debtorAgent with or without debtorAccount. | Ensure that for localInstrument=`UK.FasterPayments` both debtorAccount and debtorAgent are included or not included at all (as required by CMA9 API profile) or in case of localInstrument=`PL.Elixir` provide only debtorAccount or do not include it at all (as required by Polish API profile) and re-submit the message. Ensure that debtorAccount is provided when localInstrument ='HU.DomesticNonEuro'. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Payment details are not aligned with selected localInstrument", "Details": "path[0]=/payments/debtorAccount/identification" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Usage of debtorAgent does not match selected localInstrument" | `FORMAT_ERROR` | debtorAgent field's inclusion in the request does not correspond to API profile specifications. | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP for localInstrument= 'UK.FasterPayments' provides only debtorAccount. | Ensure that for localInstrument= 'UK.FasterPayments' both debtorAccount and debtorAgent are included or not included at all (as required by CMA9 API profile). | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Payment details are not aligned with selected localInstrument", "Details": "path[0]=/payments/debtorAgent/identification" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | "A valid pattern value in the frequencyPattern field is expected for the selected frequency value." | `INVALID_FREQUENCY_PATTERN` | The value provided for the frequencyPattern is not a valid frequency format. | Return as path to the element that failed the validation | This typically occurs due to submitting user's error. | Ensure that a valid pattern value according to the OBIE Standing Orders frequency format is populated in the frequencyPattern field and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "UNCLEAR_PAYMENT_INSTRUCTION", "Description": "A valid pattern value in frequencyPattern field is expected for selected frequency value.", "Details": "path[0]=/payments/schedule/frequencyPattern" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------| | "\[Path 'path\[i\]'\] Numeric instance is lower than the required minimum (minimum: 1, found: %s)" | `FORMAT_ERROR` | The value provided for the numberOfPayments is less or equal to zero | Return as path to the element that failed the validation | This typically occurs due to submitting user's error. | Ensure that a value greater than 0 is populated as numberOfPayments and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "[Path '/payments/schedule/numberOfPayments'] Numeric instance is lower than the required minimum (minimum: 1, found: -2)", "Details": "path[0]=/payments/schedule/numberOfPayments" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | "It is unclear what end date of the payment is requested - by number of payments or by end date" | `UNCLEAR_END_DATE` | The request contains both endDate and numberOfPayments schedule's elements populated. This is an invalid scenario, as the fields are mutually exclusive. | Return as path to the element that failed the validation | This typically happens when parameters are wrongly populated in the schedule section while initiating a Standing Order payment. | Ensure that only one element is populated and populate the necessary fields in the schedule section to initiate a Standing Order based on a defined schedule. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "UNCLEAR_END_DATE", "Description": "It is unclear what end date of the payment is requested - by number of payments or by end date" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| | "debtorAccount data need to be provided if debtorName data is included" | `FORMAT_ERROR` | debtorAccount was not provided while having debtorName details in request. | "path\[i\]=;" where i = 0, 1, 2, and so on, for each element that failed the validation | This typically occurs when the TPP does not fill in the debtorAccount field while including debtorName data in the request. | Ensure that debtorAccount data is included along with debtorName data in the request. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "debtorAccount data need to be provided if debtorName data is included", "Details": "path[0]=/payments/debtorAccount" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------|------------------------------|-------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| | "Refund capability not enabled for TPP" | `REFUND_CAPABILITY_DISABLED` | Refund capability is not enabled for the TPP requesting for refund account details. | N/A | This typically occurs when refund capability is not enabled for the TPP requesting for refund account details. | Contact the Open Banking Connect API support team to request enabling of Refund capability. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "REFUND_CAPABILITY_DISABLED", } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | "Conditional field `psuIPAddress` is expected when `isLivePsuRequest`='true'" | `FORMAT_ERROR` | `IP address` field is mandatory if parameter `isLivePsuRequest`=true | "path\[i\]=\<\\path to the element that failed the validation\>;" where i = 0, 1, 2, and so on for each element that failed the validation | This typically occurs because the TPP has provided in request `isLivePsuRequest`=true and did not provide the IP address value. | Provide IP address of PSU in the request when providing `isLivePsuRequest`=true. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field psuIPAddress is expected when isLivePsuRequest='true'", "Details": "path[0]=/requestInfo/psuIPAddress" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------------------------------------------------|-----------------|--------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | "You are not allowed to perform this request to this ASPSP" | `NOT_ALLOWED` | Specific payment type is not allowed | N/A | Occurs when a specific payment type (future dated payment, standing order) is not supported at ASPSP or AP profile level. | Verify the specifications and ensure that the endpoint and feature is supported by the API profile returned for the ASPSP. Correct the request if needed. | **Error example code** ```json { "Errors": { "Error": [{ "Source": "OBC", "ReasonCode": "NOT_ALLOWED", "Description": "You are not allowed to perform this request to this ASPSP", "Details": "path[0]=/payments/requestedExecutionDate" } ``` Or { "Errors": { "Error": [{ "Source": "OBC", "ReasonCode": "NOT_ALLOWED", "Description": "You are not allowed to perform this request to this ASPSP", "Details": "path[0]=/payments/schedule" } } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------|------------------|-----------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | "`EndToEndIdentification` needs to be unique" | `PROVIDER_ERROR` | EndToEndIdentification needs to be unique or resend the request | N/A | Occurs when the `EndToEndIdentification` included in the request, was already used in previous requests. | Provide an unique `EndToEndIdentification` and resend the request. | **Error example code** ```json { "Errors":{ "Error":[{ "Source":"OBC", "ReasonCode":"PROVIDER_ERROR", "Description":"EndToEndIdentification needs to be unique or please resend the request.", "Recoverable":false } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------|------------------|------------------------------------------------------------------|-----------------------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Missing mandatory details" | `PROVIDER_ERROR` | Mandatory details required by ASPSPs are missing in the request. | N/A | Occurs when specific fields required by some ASPSPs were not included in the request. | Check the response to Get List of ASPSPs request and information on Mastercard Developer Portal to check the list of mandatory fields required by specific ASPSPs, and resubmit the request with mandatory field(s). | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Missing mandatory details" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------------------|------------------|---------------------------------------------------|-----------------------|---------------------------------------------------------------|------------------------------------------------------| | "Payment execution is scheduled on a bank holiday" | `PROVIDER_ERROR` | Payment execution is scheduled on a bank holiday. | N/A | Occurs when `requestExecutionDate` was set on a bank holiday. | Adjust `requestExecutionDate` and resend the request | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": " PROVIDER_ERROR ", "Description": "Payment execution is scheduled on a bank holiday" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | "Remittance Information Reference (remittanceInformationReference) is invalid" | `PROVIDER_ERROR` | Details provided in the remittance information reference field are not accepted by the bank (due to length or specific characters). | N/A | Occurs when remittance information reference field has more than 18 characters or has special characters which are not accepted by the bank. | Adjust `remittanceInformationReference` data and resend the request. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Remittance Information Reference (remittanceInformationReference) is invalid" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------|------------------|-------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------------------|------------------------------------------------------------------| | "LocalInstrument not supported by the bank" | `PROVIDER_ERROR` | The localInstrument specified is not supported by the bank. | N/A | Occurs when specific payment rails (localInstrument) is not supported by the ASPSP. | Resubmit the request specifying another payment LocalInstrument. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": " LocalInstrument not supported by the bank " } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------------------------------|------------------|------------------------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| | "Invalid creditorAccount identification" | `PROVIDER_ERROR` | The creditorAccount identification is invalid. | N/A | Occurs when creditor account provided in the request has invalid format (contains letters or length is different than 8 digits). | Adjust creditor account and resubmit the request. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Invalid creditorAccount identification" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------|------------------|------------------------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------| | "Invalid debtorAccount identification" | `PROVIDER_ERROR` | The debtorAccount identification is not valid. | N/A | Occurs when debtor account has invalid format (contains letters or length is different than 8 digits). | Adjust debtor account and resubmit the request. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Invalid debtorAccount identification" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------|------------------|----------------------------------------|-----------------------|------------------------------------------------------------------------------|---------------------------------------------------------| | "Invalid merchantCategoryCode" | `PROVIDER_ERROR` | The merchantCategoryCode is not valid. | N/A | Occurs when Merchant Category Code has invalid format (more than 3-4 chars). | Adjust Merchant Category Code and resubmit the request. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Invalid merchantCategoryCode" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------|-----------------|-----------------------|-----------------------|--------------------------------------------------------|-------------------------------------| | "Invalid Input" | `FORMAT_ERROR` | The input is invalid. | N/A | Occurs when invalid input was included in the request. | Adjust the request and resubmit it. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "PROVIDER_ERROR", "Description": "Invalid Input" } ] } } ```