Background
There is currently no standardised way for ASPSPs to communicate the differences in ASPSP implementations. Therefore, this page intends to cover:
- Information for Customers wishing to participate
- Information for Third Party Providers wishing to use the APIs including:
- Differences in on-boarding and directory interactions
- What processes to follow in order to onboard with Mizuho
- Differences in functionality delivered for the APIs
Mizuho supports PISPs and AISPs to use the authentication methods provided to Mizuho's customers via the redirection method (as specified in the Open Banking Standards).
Two-factor authentication is assured for Open Banking customers via:
- Knowledge of credentials (logon id and password)
- Possession of a one-time-password that has been delivered to a registered email address
The customer will be required to request that a Super User is created by Mizuho. There will need to be at least two Super users and we recommend that three are created. The Super users will be responsible for setting up the sub users on their side.
Please note the Super users will be granted access to all the accounts held for the company they ask to be made accessible via the APIs.
Mizuho will not host any authorisation levels for payments. For example if a customer wants two authorisers before payment this will need to be completed prior to transmission to Mizuho.
Customers authentication lasts for a maximum for 90 days, re-authentication is required once this period has expired.
The Mizuho Bank Open Banking Gateway provides APIs that allow a Third Party Provider (TPP) to access account information, confirmation of funds and initiate payments on behalf of a Mizuho Customer (PSU). A Sandbox environment is provided so that a TPP can verify functionality before connecting to the production system. This documentation contains the information required for a TPP in order to register and invoke the APIs. For general information about the Open Banking APIs, see here. Any TPP wishing to access the APIs has to be enrolled with the UK Open Banking Directory. Enrolling onto the Open Banking Directory is described here.
The available APIs are described here for the Sandbox and here for the Production Environment. TPPs can register themselves using the Dynamic Client Registration APIs. The OIDC hybrid flow is supported for consent authorisation.
APIs to the Sandbox are accessible on api.mhbkemea.co.uk on port 446 and require a TLS certificate signed by the Sandbox Open Banking Directory. Similarly, production APIs are accessible on api.mhbkemea.co.uk on port 448 with the appropriate certificate. The OIDC API that is used to redirect the PSU to the Authorisation Server is available on api.mhbkemea.co.uk on the default port 443. Connection details can be found on the OIDC Well known endpoints at:
- https://api.mhbkemea.co.uk/oidc/sb (Sandbox)
- https://api.mhbkemea.co.uk/oidc/production (Production)
TLS Certificates for the Open Banking Sandbox can be downloaded from here.
Please note that the use of special characters in any of the identifier fields could cause problems processing the instruction. Please use standard character sets.
Dedicated tests users can be created in order to access the Sandbox data. Please request this via the contact details. A fixed set of accounts, balances and transactions will be available to be retrieved for these users.
Payments can be created and looked up in the sandbox, but will not change status beyond AcceptedSettlementInProcess.
Using a Software Statement Assertion (SSA) and a transport TLS certificate issued by the UK Open Banking Directory, a TPP can use the /register endpoint of the Dynamic Client Registration Endpoint in order to register an account on the Miuzho Open Banking Payment Gateway and obtain credentails to access it. See the Open Banking Dynamic Client Registration specification for background information. The API is documented here.
Please note the client_secret will only be displayed during the first registration of a software ID. When performing another registration request with the same Software ID, the response will indicate a success, but not return the client secret again. If the client_secret is lost, it cannot be retrieved. In this case either use a new Software ID to register or contact support in order to delete the existing registration.
A TPP can only request access to accounts that reside in a country they are licensed to operate in, otherwise the request will be rejected.
Mizuho will always return confirmation of funds as true. This replicates the payment initiation checks performed at the bank.
Mizuho will only support the following payment types:
- UK.OBIE.CHAPS
- UK.OBIE.SWIFT
- UK.OBIE.Target2
- UK.OBIE.SEPACreditTransfer
Mizuho European Open Banking will accept a payment even if it is past the given cut off time. The payment will be processed on the next working day with an amended value date.
Any payment instruction received with Exchange Rate Information will be rejected and not be processed. Exchange rate information will not be provided in the return response.
The transaction status will always be reported as Accepted Settlement in Process. This will be returned within 24 hours upon receipt of the transaction for processing by Mizuho.
- We will only accept the following payment types:
- UK.OBIE.CHAPS
- UK.OBIE.SWIFT
- UK.OBIE.SEPACreditTransfer
- UK.OBIE.Target2
- All currency-specific payment types must be submitted in the appropriate currency.
- Payment requests will be processed according to the Mizuho customer's standard terms and no special instructions will be accepted.
- UK.OBIE.SEPACreditTransfer requests must not have an instruction priority of Urgent.
- Payment requests that do not meet these guidelines will be rejected.
BACS files must be uploaded with a content-type of "text/bacs" while PAIN files must be uploaded with a content-type of text/pain. Mizuho requires that the following fields must be used in File Payment API Requests:
| Element | Requirement | Notes |
|---|---|---|
| FileType | Mandatory | Must be either "UK.Mizuho.bacs" or "UK.Mizuho.pain.001.001.03" |
| FileHash | Mandatory | |
| FileReference | Mandatory | |
| NumberOfTransactions | Mandatory | Minimum 1; Maximum 1000 |
| ControlSum | Mandatory | |
| RequestedExecutionDateTime | Mandatory | Date must not be in past |
| LocalInstrument | Not Permitted | If present then consent request will be rejected |
| DebtorAccount | Not Permitted | |
| RemittanceInformation | Not Permitted | |
| SupplementaryData | Not Permitted |
| UK.Mizuho.bacs |
|---|
| All payments must have TransactionCode (data record [63-64]) = 99 |
| FileType must be "UK.Mizuho.bacs" |
| base64 encoding of a SHA256 hash of the uploaded file must = FileHash |
| CustomerRef (header record [2-11]) must = FileReference |
| NumberOfRecords (trailer record [2-11]) must = NumberOfTransactions |
| TotalAmount (trailer record [12-24]) must = ControlSum * 100 |
| ValueDate (header record [12-21]) must = RequestedExecutionDate |
| UK.Mizuho.pain.001.001.03 |
|---|
| Must contain optional tag <GrpHdr><CtrlSum> |
| Debtor account must be identified as IBAN (PmtInf><DbtrAcct><Id><IBAN>) |
| Must have only one <PmtInf> |
| FileType must be "UK.Mizuho.pain.001.001.03" |
| base64 encoding of a SHA256 hash of the uploaded file must = FileHash |
| PaymentInformationIdentification (<GrpHdr><PmtInfId>) must = FileReference |
| NumberOfTransactions (<GrpHdr><NbOfTxs>) must = NumberOfTransactions |
| ControlSum (<GrpHdr><CtrlSum>) must = ControlSum |
| RequestedExexcutionDate (<PmtInf><ReqdExctnDt>) must = RequestedExecutionDate |
In order to send a BACS File the Mizuho account holder must have an existing agreement or request a new agreement for BACS submissions with Mizuho.
- BACS files must be provided in the Mizuho stipulated format.
- The customer must have their own SUN number.
BACS files that do not meet the above conditions or where the customer does not have an agreement with Mizuho to process BACS will be rejected.
| Symptom | Error Message | Response |
| TLS handshake error | This usually happens when the Gateway rejects the connection because of invalid certificates. Ensure that the correct certificate is being used for the request. Common errors are to use the Sandbox certificate for production or the Signature certificate as the transport certificate. | |
| Error when creating a consent | "invalid client" error message | An invalid client_id or secreat was used. Ensure that the credentials are correct and valid for the environment (Production/Sandbox). A less likely cause is that the TPP has been revoked by the UK Open Banking Directory |
| invalid certificate" error message | The client_id used in the request does not match the TLS transport certificate. Ensure the credentials match the transport certificate being used | |
| "UK.OBIE.Signature.Malformed" message when creating a payment consent | The signature verification of the detached JWT failed. Ensure that the payment consent is submitted with a detached JWT signed with the correct certificate. | |
| "invalid_scope" error message | The request is missing the scope header parameter or the value is not acceptable. See the relevant API documentation for a list of allowed scopes. | |
| An error occurs when the PSU gets redirected to the authorisation server | "invalid redirect_uri" error is displayed | The TPP has specified a redirect URL that was not included in the original SSA when registering with the gateway and the gateway has blocked this request for safety reasons. Ensure that the redirect URIs being used have been included in the SSA during registration. |
| Customer (PSU) cannot log in | A customer log in failure can be due to a number of reasons either related to the request that the TPP made or due to the customer credentials. | |
| "SPG0020 - Could not verify service provider credentials" error message | The assertion included in the redirect request was incorrect and the gateway has blocked the login. Ensure that the assertion token has been signed with the correct signature key, that it contains the correct openbanking_intent_id, client_id and redirect_uri. Also ensure that the nonce, if specified, has not been repeated. | |
| "EAPI006 - Invalid userid or password" error | The credentials for the login were incorrect. Ensure that an existing account is used with the correct password. Note that usernames in the Sandbox are case sensitive. | |
| PSU cannot approve consent | "No accounts selectable" message displayed and all accounts are greyed out. | The gateway does not allow a PSU to select accounts that are associated with the a different country than what the TPP is registered in. |
| "Authenticated user does not have authority to approve payment on this debtor account." | The gateway does not allow a PSU to select accounts that are associated with the a different country to that in which the TPP is registered. In this case, an account has been preselected by the TPP that is not accessible | |
| TPP cannot re-authenticate using the authorisation code | "invalid_client" error message | The gateway has rejected the authorisation because the client could not be verified. Ensure that the correct client_id is included in the request. Ensure that client_assertion has been submitted an is an correctly signed JWT. |
| "unknown" error message returned from the API | An unspecified error has occured. Check that the "code" header parameter has been included in the request. |