# FAQs source: https://developer.mastercard.com/open-banking-connect/documentation/tutorials-and-guides/faqs-tutorial/index.md ## General HTTP response codes {#general-http-response-codes} The HTTP response code communicates the success or failure of a TPP request message. | Response Code | Description | |---------------------|---------------------------------------------------------------------| | 200 OK | Success | | 400 Bad Request | Validation error occurred | | 504 Gateway Timeout | The server did not receive a timely response from the data provider | ### HTTP Error code response body {#http-error-code-response-body} If the HTTP response code = 400 is returned, the response body typically provides additional details on the error. The table below describes the structure of errors in such a scenario: | **Name** | **Condition** | **Multiplicity** | **Type** | **Description** | |-------------|------------------------------------------|------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | errors | M | 1..1 | Object | This section can include messages to the TPP on operational issues (errors) | | error | M | 1..\* | Object | Error object. For example, include one instance per each schema validation error | | source | O | 0..1 | String | N/A (not included in the response) | | reasonCode | O | 0..1 | String | The code of the error. The following Codes can be expected at the moment: · INACTIVE_ACCOUNT · INACTIVE_PROVIDER · INTERNAL_ERROR · FORMAT_ERROR · TIMEOUT · PROVIDER_ERROR | | description | O | 0..1 | String | In some scenarios, includes description of the error | | recoverable | O | 0..1 | Boolean | N/A (not included in the response) | | details | O | 0..\* | Object | In some scenarios, includes additional error details | | name | C ( if `value` populated then mandatory) | 0..1 | String | The name field contains the index key of the error's detail, such as "path" | | value | C (if `name` populated then mandatory) | 0..1 | String | The value field contains the description of the error detail accessed by name index key. For example, return as path to the element that failed the validation | ### HTTP response code = 400 reason codes {#http-response-code--400-reason-codes} | **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 | Typically occurs when the URI has a typo or is incorrectly copied. | Make sure that in order to populate the value of the tppRedirectURI field, you are using a URI that was registered 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": "com.mastercard.mcob.apiserver", "ReasonCode": "INACTIVE_URL", } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |------------------|------------------|--------------------------------------------------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------| | Inactive Account | INACTIVE_ACCOUNT | The source TPP (clientId) that has sent the message is not recognized or is invalid. | n/a | Typically occurs when the TPP onboarding has not completed or TPP used incorrect ClientID value. **Note:** ClientID is equivalent of the ConsumerKey Id in Mastercard portal | Contact Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "com.mastercard.mcob.apiserver", "ReasonCode": "INACTIVE_ACCOUNT" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-------------------|-------------------|------------------------------------------------------------------|-----------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Inactive Provider | INACTIVE_PROVIDER | The destination ASPSP (aspspId) is not recognized or is invalid. | n/a | Typically occurs when aspspId value is incorrect or ASPSP was disabled. | Check that the value used for aspspId in the request is valid as per the list of ASPSPs returned by Open Banking Connect API (for example, in /payments/aspsps or /accounts/aspsps). If you think you should be able to access the specified ASPSP, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "com.mastercard.mcob.apiserver", "ReasonCode": "INACTIVE_PROVIDER" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "You are not allowed to perform request to this ASPSP" | NOT_ALLOWED | TPP is not allowed to submit requests to this ASPSP. The availability of an ASPSP for a TPP is recorded in Open Banking Connect based on TPP registration Data. Only available ASPSPs are returned to the TPP from the Open Banking Connect API. | Return as path to the element that failed the validation. | Typically happens when TPP does not register correctly. | Check that the value used for aspspId in the request is valid as per the list of ASPSPs returned by Open Banking Connect API (for example,. in /payments/aspsps or /accounts/aspsps). If you think you should be able to access the specified ASPSP, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "com.mastercard.mcob.apiserver", "ReasonCode": "NOT_ALLOWED", "Description": "You are not allowed to perform this request to this ASPSP" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Method not supported by Provider's API profile" | NOT_FOUND | Method not supported by ASPSP. Depending on the API Standard /Profile implemented at the side of the ASPSP, some of the endpoints may not be available for that ASPSP. The information about API Profile support is provided in the specification for each endpoint. | n/a | Typically happens with new customers who send data not part of the API Standard. | Verify the specification and ensure that the endpoint the ASPSP supports the API Profile returned (for example, in /payments/aspsps or /accounts/aspsps). If you think you should be able to access the specified endpoint, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": "NOT_FOUND", "Description": "Method not supported by Provider's API profile" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------|------------------|----------------------------------------------------------------------|-----------------------|--------------------------------------------------------------------------------------------|------------------------------------------------| | "Unable to process request this time." | `PROVIDER_ERROR` | There was an error returned from the ASPSP or connectivity partners. | n/a | This typically occurs due to incorrect parameters sent to connectivity partners or ASPSPs. | Contact Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "ReasonCode": "PROVIDER_ERROR", "Description": "Unable to process request this time" } ] } } ``` ### HTTP response code = 504 reason codes {#http-response-code--504-reason-codes} | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |----------------------------------------|-----------------|----------------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| | "Unable to process request this time." | TIMEOUT | This is returned when HTTP Status Code = 504 | n/a | This usually occurs when server, while acting as a gateway or proxy, did not receive a timely response from the upstream server, such as the connectivity partner or the ASPSP. Exceptions: \[health\] and \[aspsps\] endpoints will not raise this error because they do not use an upstream server. | Re-try sending the same request after a recommended period of time. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "com.mastercard.mcob.apiserver", "ReasonCode": "TIMEOUT", "Recoverable": true } ] } } ``` Return to the [Knowledge Base](https://developer.mastercard.com/open-banking-connect/documentation/tutorials/index.md) Return to [Documentation](https://developer.mastercard.com/open-banking-connect/documentation/index.md) ### Initiate A Payment Request {#initiate-a-payment-request} Payment requests currently use either of three payment products - Domestic Credit Transfers, SEPA credit transfers, or Cross-Border (international) Payments. The flow is the same regardless of which is used by the targeted ASPSP. We will use the Domestic Credit Transfer option for purposes of this illustration. Steps to initiate a payment request 1. Create a consent for the PSU (*/payments/domestic-credit-transfer/consents*) 2. Redeem the payment request (*/payments/domestic-credit-transfer* ) * The status and details of the payment may also be requested at a later time. 3. Check the payment status: (*/payments/domestic-credit-transfer/payment-status*) 4. Get the details of the payment status from the ASPSP: (*/payments/domestic-credit-transfer/payment-details*) ### Conditions {#conditions} Each message specification data field/element includes the following condition codes. Each condition is described in the respective request or response. * O (Optional): The field is supported by the API, but the usage is optional. * C (Conditional): The field is required by the API under certain conditions (see "Description"). * M (Mandatory): The field is always required by the API. *** ** * ** *** ### Multiplicity {#multiplicity} Multiplicity indicates the cardinality of the elements in the message structure: * (0..1) -- 0 or 1 instances of the element * (1..1) -- exactly one instance of the element only * (0..N) -- 0 to N instances of the element *** ** * ** *** ### Interface API structure {#interface-api-structure} The API Interface is resource oriented. Resources are addressed under the API endpoints. For example: [https://{provider}/{service}](https://%7Bprovider%7D/%7Bservice%7D) Where * {provider} is the host and path of the API. * {service} has the values consents, payments, accounts, eventually extended by more information on product types and request scope. *** ** * ** *** ### API Profiles {#api-profiles} All ASPSPs that can be accessed through Mastercard Open Banking Connect have a descriptor that indicates the API Profile of the ASPSP, that is, the Open Banking API standard implemented on the side of the ASPSP. As of the Drop 2 release, Open Banking Connect provides access only to ASPSPs that have one of the following API profiles: * **CMA9** -- An Open Banking API standard defined by the Open Banking Implementation Entity (OBIE) in UK, which is mandatory for the nine major banks, per the order from Competition and Markets Authority (CMA). Currently this API profile is based on v3.1 of the OBIE specification for AIS and PIS. * **PolishAPI** -- An Open Banking API standard for the banking sector in Poland currently based on v2.1.3 of the Polish API specification. * **NextGenPSD2** -- An Open Banking API standard defined by Berlin Group for the EU banking sector. They developed the standard to create uniform and interoperable communications between EU banks and TPPs. * **STET** - An Open Banking API standard defined by group of major French banks for full range of payment instruments in the French and Belgian market. * **Slovak Banking API Standard** - An Open Banking API standard developed in Slovakia, which defines secure communication between the banks and third-party providers based on PSD2 requirements. * **Czech Open Banking Standard** - An Open Banking API standard developed in the Czech market which lays down rules for communication, mainly for services defined by the PSD2. * **"Budapest Bank" API standard** - A bank specific Open Banking API standard, based on the specifications of NextGenPSD2 standard. The API Profile enables the TPP to determine if the original API standard of the ASPSP supports a specific endpoint included in the Open Banking Connect API. The endpoints specifications included in this document provide details of the supported API Profile. The API returns the API Profile for each ASPSP when the TPP requests the list of ASPSPs. Return to the [Knowledge Base](https://developer.mastercard.com/open-banking-connect/documentation/tutorials/index.md) Return to [Documentation](https://developer.mastercard.com/open-banking-connect/documentation/index.md) ### Open Banking Connect Release information {#open-banking-connect-release-information} The following documents are provided as "hard-copy" of the information provided in Mastercard Developers. Any information is only relevant to the stated release. For the most up to date information review the pages available on this website. YAML files are available upon request from Mastercard. Current Release number is **1.18.1**. #### Supporting documents {#supporting-documents} * [OB_Connect_API_Specification_Release_1-18_v1-0.pdf](https://static.developer.mastercard.com/content/open-banking-connect/Documents/OB_Connect_API_Specification_Release_1-18_v1-0.pdf) (5MB) * [OB_Connect_API_Production_Release_Notes-Release_1-18-1_v1-0.pdf](https://static.developer.mastercard.com/content/open-banking-connect/Documents/OB_Connect_API_Production_Release_Notes-Release_1-18-1_v1-0.pdf) (218KB) * [OB_Connect_API_Sandbox_Release_Notes-Release_1-18-1_v1-0.pdf](https://static.developer.mastercard.com/content/open-banking-connect/Documents/OB_Connect_API_Sandbox_Release_Notes-Release_1-18-1_v1-0.pdf) (233KB) * [OB_Connect_API_Sandbox_Scenarios_1-18_v1-0.pdf](https://static.developer.mastercard.com/content/open-banking-connect/Documents/OB_Connect_API_Sandbox_Scenarios_1-18_v1-0.pdf) (1MB) * [OB_Connect_SandboxDataSet_R1-17-0.pdf](https://static.developer.mastercard.com/content/open-banking-connect/Documents/OB_Connect_SandboxDataSet_R1-17-0.pdf) (561KB) *** ** * ** *** Return to the [Knowledge Base](https://developer.mastercard.com/open-banking-connect/documentation/tutorials/index.md) Return to [Documentation](https://developer.mastercard.com/open-banking-connect/documentation/index.md) ## Open Banking industry background {#open-banking-industry-background} The Payment Service Directive (PSD) known as PSD2 (PSD2, Directive (EU) 2015/2366), issued by the European Union (EU), allows regulated TPPs, with the consent of the Payment Services User (PSU), to connect to customer accounts held by Account Servicing Payments Services Providers (ASPSPs). This connection is in order to securely obtain account information or initiate payments to or from the respective accounts. The ASPSPs give access to three types of services to implement the APIs used to allow the connection: * Payment Initiation Service (PIS) -- Operated by a Payment Initiation Service Provider (PISP) TPP, as defined by article 66 of PSD2. * Account Information Service (AIS) -- Operated by an Account Information Service Provider (AISP) TPP, as defined by article 67 of PSD2. * Confirmation of the Availability of Funds service (CAF) -- Used by Payment Instrument Issuing Service Provider (PIISP) TPP, as defined by article 65 of PSD2. PSD2 does not specify the actual API standards used by ASPSPs. ASPSPs can select any of the standards available on the market already or implement their own, as long as it complies with the provisions of PSD2. Thus, integrating a TPP with even a small number of ASPSPs may require a significant amount of effort and investment. *** ** * ** *** ### Special considerations {#special-considerations} To create the APIs for this product, Mastercard leveraged the Berlin Group specification standard as an industry reference (alongside other global standards) for Mastercard's own data model, per the Berlin Group Creative Commons Attribution 4.0 International Public License: *** ** * ** *** ### Important notice for current single API Users {#important-notice-for-current-single-api-users} Prior to the Drop 2 (June 2019) release of the Open Banking Connect API Specification, there was only a single API. Due to a need to split the AIS and PIS functions in Drop 2, a second API has been introduced for AIS. PIS will continue to use the original API. Customers that want to use both AIS and PIS functions must connect to both APIs. Current customers on a single API must contact their Onboarding contact or their Open Banking Development team contact to ensure they are correctly pointing to both the APIs. New customers must use the Mastercard Developer site to access the APIs. Return to the [Knowledge Base](https://developer.mastercard.com/open-banking-connect/documentation/tutorials/index.md) Return to [Documentation](https://developer.mastercard.com/open-banking-connect/documentation/index.md) ## Before you start {#before-you-start} Prerequisites to use the Mastercard Open Banking Connect platform 1. A valid TPP license from either the FCA (OBIE), or your local National Competent Authority (NCA), if in the EU. 2. Work with your assigned Customer Implementation Specialist (CIS) to finalize onboarding through the Mastercard Connect B2B portal. 3. Authenticate to the Open Banking Connect APIs as described in our [Authentication Guide](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/).