API Market documentation

Bulk Verification of Payee API - details

Changes from the previous version

This is the change log of the Bulk Verification of Payee API, enabling our corporate customers to confirm the validity of a payee’s account number and name before sending the payment. The top most item is the latest change and the API changes described in it are relative to the version directly below. The current version of the API is 1.2.

Version 1.2

Updated the API description & onboarding details. Sandbox only: API now includes support for customers with Corporate Cash Management Agreement (CCM) with Corporate Access File Transfer (CAF) service and Corporate Access Payable (CAP) service and Pain.001.001.09 (Pain.001 V9).

Version 1.1

Updated API description. Added in GET API call support for mixed results via header -> vop-return-status: mixed.

Version 1.0

We have implemented the API in a first draft version in Sandbox. The business logic behind aims to simulate a real time experience and create responses close to how we plan to implement the service in production.

Bulk Verification of Payee

Bulk Verification of Payee API is a service which enables Nordea Corporate customers who use Web Services - Corporate Payments Service (Finland) and Corporate Cash Management Agreement (CCM) with Corporate Access File Transfer (CAF) service and Corporate Access Payable (CAP) service, to reduce risk when making SEPA payments. We do so by enabling our corporate customers to confirm the validity of a payee’s account number and name before sending the payment. Both incorrect and fraudulent payments can be reduced by verifying the payee before executing SEPA payments.

The service is available in Finland for Nordea Web Service Company-based and Web Service User-based Corporate Payments Service customer: The Bulk VoP API request utilizes Pain.001.001.02 (Pain.001 V2), Pain.001.001.03 (Pain.001 V3) and Pain.001.001.09 (Pain.001 V9) ISO 20022 XML. The content of the file is to be sent in a POST API call towards our API endpoint to create a verification of the payments.

These transactions will be returned in Pain.002.001.10 (Pain002 V10) format and a payee verification status will be specified as: match, close match, no match or invalid request to each SEPA transaction. To retrieve the results a GET API call will need to be initiated by the customer. The Bulk VOP API will not push any results to the customer.

Production access to Bulk Verification of Payee

To use Bulk Verification of Payee in production, you need an active Web Service agreement and an active Web Service PKI LogonID certificate issued by Nordea. If you already have an active Web Service agreement and an active Web service PKI LogonID certificate, you can use your existing certificate to sign API calls for Bulk Verification of Payee API.

You can sign up for Bulk Verification of Payee via the automated registration process. Provide the requested information in the registration registration webform together with a signed Software statement (SSA) with your existing public certificate. A successful onboarding process will grant you production access in about 15 seconds.

Learn more about the details of the onboarding process in our Help Centre article.

Support for CCM/CAF/CAP and Pain.001.001.09 - Currently only in sandbox

In sandbox only, the service is also available for customers with Corporate Cash Management Agreement (CCM) with Corporate Access File Transfer (CAF) service and Corporate Access Payable (CAP) service. Service utilizes Pain.001.001.03 (Pain.001 V3) and Pain.001.001.09 (Pain.001 V9) ISO 20022 XML. The content of the file is to be sent in a POST API call towards our API endpoint to create a verification of the payments.

API endpoints

Bulk Verification of Payee API contains the following endpoints:

#	Endpoint	Supported HTTP Methods	Description
1	`/premium/v1/bulk-verification-of-payee`	POST	Send request for verification of payee
2	`/premium/v1/bulk-verification-of-payee/:batch_identification`	GET	Fetch verification status. `:batch_identification` path variable is `MsgId` from Group Header provided in Pain.002 response

Note! It is strongly recommended not to query GET status endpoint more often than once every 30 seconds.

Note! When calling GET report endpoint, the same Client-Id as used at POST request must be provided.

For more details, check examples section further down in this documentation.

Bulk Verification of Payee request definition and statuses

VOP API verification request accepts the same Pain.001.001.02, Pain.001.001.03 and Pain.001.001.09 XML as used for actual batch payments. Regardless of version used for verification request, status response is always returned as Pain.002.001.10.

It is worth highlighting that for POST verification request, apart from standard authorization headers (X-IBM-Client-Id, X-IBM-Client-Secret, Digest, Signature, X-Nordea-Originating-Date, X-Nordea-Originating-Host), also following headers are used:

Header	Description for Sandbox API	Description for Production API
Agreement-Type	Currently in Sandbox only. Optional. Values accepted: `WS`, `CCM`. Used to define if authorization should be performed against Web Service agreement (‘WS’) or Corporate Access CCM agreement (‘CCM’). If header is not provided, default value `WS` will be used	N/A
Agreement-Number	Web Service agreement number. Optional. Must be used only when `WS` agreement type is specified. Agreement-Number is not validated. Any value can be used	Required. Web Service agreement number
Logon-Id	Logon Id from Web Service agreement. Optional. Must be used only when `WS` agreement type is specified. Logon-Id is not validated. Any value can be used	Required. Logon Id from Web Service agreement
Document-Version	Pain version used for VOP request. Accepted values: `pain.001.001.02`, `pain.001.001.03` and `pain.001.001.09`	Pain version used for VOP request. Accepted values: `pain.001.001.02`, `pain.001.001.03`

Additionally, when ‘CCM’ agreement type is used, following data must be delivered in request body:

Message Item	Notes
`<GrpHdr><InitgPty><Id><OrgId><Othr><Id>`	Required. ‘SignerId’ from CAF Service
`<PmtInf><Dbtr><Id><OrgId><Othr><Id>`	Required. Customers CCM Agreement number

Note: Maximum request size is 10 mb.

Statuses of payee verification that can be returned by the service are described in the table below. Status is returned for each individual transaction in the batch (example responses are provided further down in this documentation).

Status	Description	Note
RVNC	Verification of party check on the transaction is not yet completed	-
RCVC	Recipient name matches account holder name.	-
RVMC	Recipient name partially differs from the account holder name. The account holder’s name is XXX. Check the recipient information.	When this status is returned, additionally matching name will be provided in `AddtlInf` tag
RVNM	Recipient name is not the same as the account holder name. Check the recipient information. Confirming the payment may lead to transferring funds to an account not held by the recipient you indicated. In that case, the bank is not liable for the loss of funds. If you are in doubt, don’t confirm the payment.	-
RVNA	We could not compare recipient name with account holder name. Confirming the payment may lead to transferring funds to an account not held by the recipient you intended.	-
RJCT	Transaction was rejected and will not be sent for verification. Usually result of validation error ex. missing required data	-

Note: Only in Sandbox, GET verification status endpoint supports additional header vop-return-status, which accepts following values: match, close match, no match, not available, mix (= random choice of the previous). This way it is possible to simulate different verification results.

Bulk Verification of Payee examples

Example postman collection for Bulk Verification of Payee can be downloaded here.

Note: Agreement type ‘CCM’ (Corporate Access CCM) and Pain.001.001.09 (V9) are currently supported in Sandbox only

Finland: Send request for Verification of Payee in Pain.001 V3

In this example, we send request for verification of payee in Pain.001.001.03 (V3).

This endpoint URL has the following form:

https://api.nordeaopenbanking.com/corporate/premium/v1/bulk-verification-of-payee

When agreement type ‘WS’ (Web Service) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Digest: {digest} 
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Agreement-Type: 'WS'
Agreement-Number: {ws_agreement_number}
Logon-Id: {ws_logon_id}
Document-Version: 'pain.001.001.03'

Note: Agreement-Type header works currently in sandbox only

Note: In Sandbox only, Agreement-Number is not validated. Any value can be used.

Note: In Sandbox only, Logon-Id is not validated. Any value can be used.

When agreement type ‘CCM’ (Corporate Access CCM) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Digest: {digest} 
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Agreement-Type: 'CCM'
Document-Version: 'pain.001.001.03'

Note: As stated earlier in this documentation, for CCM agreement type, Signer Id and Agreement Number must be provided in request body.

This endpoint supports POST HTTP Method. Request body example:

<?xml version="1.0" encoding="utf-8"?>
<Document xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<CstmrCdtTrfInitn>
		<GrpHdr>
			<MsgId>c9b3c42a1dfac6134f03</MsgId>
			<CreDtTm>2025-06-26T17:01:15</CreDtTm>
			<NbOfTxs>4</NbOfTxs>
			<InitgPty>
				<Nm>John Smith</Nm>
				<PstlAdr>
					<Ctry>FI</Ctry>
				</PstlAdr>
			</InitgPty>
		</GrpHdr>
		<PmtInf>
			<PmtInfId>0cd98fd7b9703a68467d</PmtInfId>
			<PmtMtd>TRF</PmtMtd>
			<PmtTpInf>
				<SvcLvl>
					<Cd>SEPA</Cd>
				</SvcLvl>
			</PmtTpInf>
			<ReqdExctnDt>2025-06-27</ReqdExctnDt>
			<Dbtr>
				<Nm>John Smith</Nm>
				<Id>
					<OrgId>
						<Othr>
							<Id>012345678</Id>
							<SchmeNm>
								<Cd>BANK</Cd>
							</SchmeNm>
						</Othr>
					</OrgId>
				</Id>
			</Dbtr>
			<DbtrAcct>
				<Id>
					<IBAN>FI1234000000000016</IBAN>
					<!-- Debtor IBAN -->
				</Id>
				<Ccy>EUR</Ccy>
			</DbtrAcct>
			<DbtrAgt>
				<FinInstnId>
					<BIC>ABICTEST</BIC>
				</FinInstnId>
			</DbtrAgt>
			<ChrgBr>SLEV</ChrgBr>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>764b8fe430253b2c1a28-01</InstrId>
					<EndToEndId>o9i767ed88eae2482323-01</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<SvcLvl>
						<Cd>SEPA</Cd>
					</SvcLvl>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">1111.11</InstdAmt>
				</Amt>
				<ChrgBr>SLEV</ChrgBr>
				<Cdtr>
					<Nm>Anna Kowalsky</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI1234000000000001</IBAN>  <!-- 1st Creditor IBAN -->
                    </Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>00000000120000000001</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>764b8fe430253b2c1a28-02</InstrId>
					<EndToEndId>o9i767ed88eae2482323-02</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<SvcLvl>
						<Cd>SEPA</Cd>
					</SvcLvl>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">22.22</InstdAmt>
				</Amt>
				<ChrgBr>SLEV</ChrgBr>
				<Cdtr>
					<Nm>Joanna Czech</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI1234000000000002</IBAN>
						<!-- 2nd Creditor IBAN-->
                    </Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>00000000120000000002</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
			<CdtTrfTxInf>
				<CdtTrfTxInf>
					<PmtId>
						<InstrId>764b8fe430253b2c1a28-03</InstrId>
						<EndToEndId>o9i767ed88eae2482323-03</EndToEndId>
					</PmtId>
					<PmtTpInf>
						<SvcLvl>
							<Cd>SEPA</Cd>
						</SvcLvl>
					</PmtTpInf>
					<Amt>
						<InstdAmt Ccy="EUR">333.33</InstdAmt>
					</Amt>
					<ChrgBr>SLEV</ChrgBr>
					<Cdtr>
						<Nm>Mike Johnson</Nm>
					</Cdtr>
					<CdtrAcct>
						<Id>
							<IBAN>FI1234000000000003</IBAN>
							<!-- 3rd Creditor IBAN-->
                    </Id>
					</CdtrAcct>
					<RmtInf>
						<Strd>
							<CdtrRefInf>
								<Tp>
									<CdOrPrtry>
										<Cd>SCOR</Cd>
									</CdOrPrtry>
								</Tp>
								<Ref>00000000120000000003</Ref>
							</CdtrRefInf>
						</Strd>
					</RmtInf>
				</CdtTrfTxInf>
				<PmtId>
					<InstrId>764b8fe430253b2c1a28-04</InstrId>
					<EndToEndId>o9i767ed88eae2482323-04</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<SvcLvl>
						<Cd>SEPA</Cd>
					</SvcLvl>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">4000.04</InstdAmt>
				</Amt>
				<ChrgBr>SLEV</ChrgBr>
				<Cdtr>
					<Nm>Sam Samson</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI1234000000000004</IBAN>
						<!-- 4th Creditor IBAN-->
                    </Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>00000000120000000004</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
		</PmtInf>
	</CstmrCdtTrfInitn>
</Document>

And the sample response looks like this (response is always in Pain.002.001.10):

Note: VOP API is asynchronous. As a result, status of transactions in successful response will always be returned as ‘RVNC - Verification of party check on the transaction is not yet completed’. To check further progress of verification, please use GET Verification Status endpoint.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root xmlns:ns2="urn:iso:std:iso:20022:tech:xsd:pain.002.001.10">
	<groupHeader>
		<messageIdentification>444210cc026fc014</messageIdentification>
		<creationDateTime>2025-06-26T12:37:41.994Z</creationDateTime>
		<httpCode>202</httpCode>
	</groupHeader>
	<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Document">
		<ns2:CstmrPmtStsRpt>
			<ns2:GrpHdr>
				<ns2:MsgId>94253a54-3b0b-45d0-a5be-e3fcc2955efc</ns2:MsgId>
				<ns2:CreDtTm>2025-06-26T12:37:41.994Z</ns2:CreDtTm>
			</ns2:GrpHdr>
			<ns2:OrgnlGrpInfAndSts>
				<ns2:OrgnlMsgId>c9b3c42a1dfac6134f03</ns2:OrgnlMsgId>
				<ns2:OrgnlMsgNmId>pain.001.001.03</ns2:OrgnlMsgNmId>
			</ns2:OrgnlGrpInfAndSts>
			<ns2:OrgnlPmtInfAndSts>
				<ns2:OrgnlPmtInfId>0cd98fd7b9703a68467d</ns2:OrgnlPmtInfId>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-01</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNC</ns2:TxSts>
					<!-- 1st Creditor Response code -->
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-02</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNC</ns2:TxSts>
					<!-- 2nd Creditor Response code -->
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-03</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNC</ns2:TxSts>
					<!-- 3rd Creditor Response code -->
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-04</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNC</ns2:TxSts>
					<!-- 4rd Creditor Response code -->
				</ns2:TxInfAndSts>
			</ns2:OrgnlPmtInfAndSts>
		</ns2:CstmrPmtStsRpt>
	</response>
</root>

Finland: Get payee verification status

This endpoint URL has the following form:

https://api.nordeaopenbanking.com/corporate/premium/v1/bulk-verification-of-payee/:batch_identification

When agreement type ‘WS’ (Web Service) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Logon-Id: {ws_logon_id}

Note: In Sandbox only, ‘Logon-Id’ header is not present in GET endpoint.

When agreement type ‘CCM’ (Corporate Access CCM) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}

Note: Only in Sandbox, GET verification status endpoint supports additional header vop-return-status, which accepts following values: match, close match, no match, not available, mix (= random choice of the previous). This way it is possible to simulate different verification results.

To query for status, use MsgId from Group Header provided in Pain.002 response as :batch_identification path variable. Sample response of GET verification status endpoint for verification request from above. Response is always in Pain.002.001.10:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root xmlns:ns2="urn:iso:std:iso:20022:tech:xsd:pain.002.001.10">
	<groupHeader>
		<messageIdentification>444210cc026fc014</messageIdentification>
		<creationDateTime>2025-06-26T12:37:41.994Z</creationDateTime>
		<httpCode>202</httpCode>
	</groupHeader>
	<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Document">
		<ns2:CstmrPmtStsRpt>
			<ns2:GrpHdr>
				<ns2:MsgId>94253a54-3b0b-45d0-a5be-e3fcc2955efc</ns2:MsgId>
				<ns2:CreDtTm>2025-06-26T12:37:41.994Z</ns2:CreDtTm>
			</ns2:GrpHdr>
			<ns2:OrgnlGrpInfAndSts>
				<ns2:OrgnlMsgId>c9b3c42a1dfac6134f03</ns2:OrgnlMsgId>
				<ns2:OrgnlMsgNmId>pain.001.001.03</ns2:OrgnlMsgNmId>
			</ns2:OrgnlGrpInfAndSts>
			<ns2:OrgnlPmtInfAndSts>
				<ns2:OrgnlPmtInfId>0cd98fd7b9703a68467d</ns2:OrgnlPmtInfId>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-01</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RCVC</ns2:TxSts>
					<!-- 1st Creditor Final Response code. 'Match' case -->
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-02</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVMC</ns2:TxSts>
					<!-- 2nd Creditor Final Response code. 'Close match' case -->
					<ns2:StsRsnInf>
						<ns2:Rsn>
							<ns2:Cd>NARR</ns2:Cd>
						</ns2:Rsn>
						<ns2:AddtlInf>John Smith</ns2:AddtlInf>
					</ns2:StsRsnInf>
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-03</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNM</ns2:TxSts>
					<!-- 3rd Creditor Final Response code. 'No match' case -->
				</ns2:TxInfAndSts>
				<ns2:TxInfAndSts>
					<ns2:OrgnlEndToEndId>o9i767ed88eae2482323-04</ns2:OrgnlEndToEndId>
					<ns2:TxSts>RVNA</ns2:TxSts>
					<!-- 4rd Creditor Final Response code. 'Not possible to verify/ not available' case -->
				</ns2:TxInfAndSts>
			</ns2:OrgnlPmtInfAndSts>
		</ns2:CstmrPmtStsRpt>
	</response>
</root>

Finland: Send request for Verification of Payee in Pain.001 V3 - example of input validation error

Verification of Payee API validates schema (pain.001.001.02 or pain.001.001.03) and additionally implements series of validations to ensure that received request is correct. Below you can find example message and response for file with incorrect Creditor IBAN format.

<?xml version="1.0" encoding="utf-8"?>
<Document xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<CstmrCdtTrfInitn>
		<GrpHdr>
			<MsgId>AAAAAAAA0001234-01</MsgId>
			<CreDtTm>2025-06-26T17:01:15</CreDtTm>
			<NbOfTxs>1</NbOfTxs>
			<InitgPty>
				<Nm>John Smith</Nm>
				<PstlAdr>
					<Ctry>FI</Ctry>
				</PstlAdr>
			</InitgPty>
		</GrpHdr>
		<PmtInf>
			<PmtInfId>00000001234</PmtInfId>
			<PmtMtd>TRF</PmtMtd>
			<PmtTpInf>
				<SvcLvl>
					<Cd>SEPA</Cd>
				</SvcLvl>
			</PmtTpInf>
			<ReqdExctnDt>2025-06-27</ReqdExctnDt>
			<Dbtr>
				<Nm>John Smith</Nm>
				<Id>
					<OrgId>
						<Othr>
							<Id>012345678</Id>
							<SchmeNm>
								<Cd>BANK</Cd>
							</SchmeNm>
						</Othr>
					</OrgId>
				</Id>
			</Dbtr>
			<DbtrAcct>
				<Id>
					<IBAN>FI1234000000000016</IBAN>
				</Id>
				<Ccy>EUR</Ccy>
			</DbtrAcct>
			<DbtrAgt>
				<FinInstnId>
					<BIC>ABICTEST</BIC>
				</FinInstnId>
			</DbtrAgt>
			<ChrgBr>SLEV</ChrgBr>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>AInstIdTest0001</InstrId>
					<EndToEndId>AAAE2EidTEST000001</EndToEndId>
				</PmtId>
				<PmtTpInf>
					<SvcLvl>
						<Cd>SEPA</Cd>
					</SvcLvl>
				</PmtTpInf>
				<Amt>
					<InstdAmt Ccy="EUR">1111.11</InstdAmt>
				</Amt>
				<ChrgBr>SLEV</ChrgBr>
				<Cdtr>
					<Nm>Anna Kowalsky</Nm>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI0000000000000001</IBAN> <!-- Incorrect Creditor IBAN - Schema error-->
					</Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>00000000120000000001</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
		</PmtInf>
	</CstmrCdtTrfInitn>
</Document>

Error response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errorResponse>
    <groupHeader>
        <messageIdentification>1ac48992a30d79ca</messageIdentification>
        <creationDateTime>2025-06-26T13:08:09.781Z</creationDateTime>
        <httpCode>400</httpCode>    <!-- Error Code -->
    </groupHeader>
    <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="errorPayload">
        <request>
            <url>/premium/v1/bulk-verification-of-payee</url>
        </request>
        <failures>
            <code>error.validation</code>
            <description>must match "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"</description>
            <path>/CstmrCdtTrfInitn/PmtInf[0]/DbtrAcct/Id/IBAN</path>
            <type>Pattern</type>
        </failures>
    </response>
</errorResponse>

Finland: Send request for Verification of Payee in Pain.001 V2

In this example, we send request for verification of payee in Pain.001.001.02 (V2).

Note: V2 is not supported for agreement type ‘CCM’ (Corporate Access CCM).

This endpoint URL has the following form:

https://api.nordeaopenbanking.com/corporate/premium/v1/bulk-verification-of-payee

The following headers must be used:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Digest: {digest} 
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Agreement-Number: {ws_agreement_number}
Logon-Id: {ws_logon_id}
Document-Version: pain.001.001.02

Note: In Sandbox only, Agreement-Number is not validated. Any value can be used.

Note: In Sandbox only, Logon-Id is not validated. Any value can be used.

This endpoint supports POST HTTP Method. Request body example:

<?xml version="1.0" encoding="utf-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.02 pain.001.001.02.xsd">
	<pain.001.001.02>
		<GrpHdr>
			<MsgId>NV0000012345000120000001234</MsgId>
			<CreDtTm>2025-07-07T03:13:23</CreDtTm>
			<NbOfTxs>2</NbOfTxs>
			<Grpg>GRPD</Grpg>
			<InitgPty>
				<Nm>ABC LTD</Nm>
				<PstlAdr>
					<AdrLine>Savory Street 7</AdrLine>
					<AdrLine>Coppenhagen</AdrLine>
					<Ctry>FI</Ctry>
				</PstlAdr>
				<Id>
					<OrgId>
						<BkPtyId>112233445</BkPtyId>
					</OrgId>
				</Id>
			</InitgPty>
		</GrpHdr>
		<PmtInf>
			<PmtInfId>PMNT0000012345000120000001001</PmtInfId> <!--Payment01-->
			<PmtMtd>TRF</PmtMtd>
			<PmtTpInf>
				<SvcLvl>
					<Cd>SEPA</Cd>
				</SvcLvl>
			</PmtTpInf>
			<ReqdExctnDt>2025-05-22</ReqdExctnDt>
			<Dbtr>
				<Nm>John Smith</Nm>
				<PstlAdr>
					<AdrLine>Savory Street 7</AdrLine>
					<AdrLine>Coppenhagen</AdrLine>
					<Ctry>FI</Ctry>
				</PstlAdr>
				<Id>
					<OrgId>
						<BkPtyId>0010010001</BkPtyId>
					</OrgId>
				</Id>
			</Dbtr>
			<DbtrAcct>
				<Id>
					<IBAN>FI1234000000000009</IBAN> <!-- Debtor IBAN-->
				</Id>
			</DbtrAcct>
			<DbtrAgt>
				<FinInstnId>
					<BIC>NDEAFIHH</BIC>
				</FinInstnId>
			</DbtrAgt>
			<ChrgBr>SLEV</ChrgBr>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>0000012345000120000011111</InstrId>
					<EndToEndId>0000012345000120000011111</EndToEndId>
				</PmtId>
				<Amt>
					<InstdAmt Ccy="EUR">11,00</InstdAmt>
				</Amt>
				<CdtrAgt>
					<FinInstnId>
						<BIC>OKOYFIHH</BIC>
					</FinInstnId>
				</CdtrAgt>
				<Cdtr>
					<Nm>Anniele Sampson</Nm>
					<PstlAdr>
						<AdrLine>Long Street 5</AdrLine>
						<AdrLine>Glasgow</AdrLine>
						<Ctry>FI</Ctry>
					</PstlAdr>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI1234000000000001</IBAN> <!-- 1st Creditor IBAN-->
					</Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<CdtrRefTp>
								<Cd>SCOR</Cd>
							</CdtrRefTp>
							<CdtrRef>1012</CdtrRef>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
			<CdtTrfTxInf>
				<PmtId>
					<InstrId>0000012345000120000022222</InstrId>
					<EndToEndId>0000012345000120000022222</EndToEndId>
				</PmtId>
				<Amt>
					<InstdAmt Ccy="EUR">22.22</InstdAmt>
				</Amt>
				<CdtrAgt>
					<FinInstnId>
						<BIC>OKOYFIHH</BIC>
					</FinInstnId>
				</CdtrAgt>
				<Cdtr>
					<Nm>Jean May</Nm>
					<PstlAdr>
						<AdrLine>Green Square 2/123</AdrLine>
						<AdrLine>Helsinki</AdrLine>
						<Ctry>FI</Ctry>
					</PstlAdr>
				</Cdtr>
				<CdtrAcct>
					<Id>
						<IBAN>FI1234000000000002</IBAN>   <!-- 2nd Creditor IBAN -->
					</Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<CdtrRefTp>
								<Cd>SCOR</Cd>
							</CdtrRefTp>
							<CdtrRef>1012</CdtrRef>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
		</PmtInf>
	</pain.001.001.02>
</Document>

And the sample response looks like this (response is always in Pain.002.001.10):

Note: VOP API is asynchronous. As a result, status of transactions in successful response will always be returned as ‘RVNC - Verification of party check on the transaction is not yet completed’. To check further progress of verification, please use GET Verification Status endpoint.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root xmlns:ns2="urn:iso:std:iso:20022:tech:xsd:pain.002.001.10">
    <groupHeader>
        <messageIdentification>444210cc026fc014</messageIdentification>
        <creationDateTime>2025-06-26T12:37:41.994Z</creationDateTime>
        <httpCode>202</httpCode>
    </groupHeader>
    <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Document">
        <ns2:CstmrPmtStsRpt>
            <ns2:GrpHdr>
                <ns2:MsgId>94253a54-3b0b-45d0-a5be-e3fcc2955efc</ns2:MsgId>
                <ns2:CreDtTm>2025-06-26T12:37:41.994Z</ns2:CreDtTm>
            </ns2:GrpHdr>
            <ns2:OrgnlGrpInfAndSts>
                <ns2:OrgnlMsgId>AAAAAAAA0001234-01</ns2:OrgnlMsgId>
                <ns2:OrgnlMsgNmId>pain.001.001.02</ns2:OrgnlMsgNmId>
            </ns2:OrgnlGrpInfAndSts>
            <ns2:OrgnlPmtInfAndSts>
                <ns2:OrgnlPmtInfId>00000001234</ns2:OrgnlPmtInfId>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000001</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 1st Creditor Response Code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 2nd Creditor Response Code -->
                </ns2:TxInfAndSts>
            </ns2:OrgnlPmtInfAndSts>
        </ns2:CstmrPmtStsRpt>
    </response>
</root>

Finland: Send request for Verification of Payee in Pain.001 V2 - example of input validation error

Some changes to input validation has been introduced to provide more informative responses. Validation of schema is provided within the solution. Below you can find example message and response for file with Incorrect section.

<?xml version="1.0" encoding="utf-8"?> <!-- below is the commented section that is giving error code-->
<!--Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.02 pain.001.001.02.xsd"--> 
<?xml version="1.0" encoding="UTF-8"?>
<Document>
   <pain.001.001.02>
      <GrpHdr>
         <MsgId>NV0000012345000120000001234</MsgId>
         <CreDtTm>2025-07-07T03:13:23</CreDtTm>
         <NbOfTxs>2</NbOfTxs>
         <Grpg>GRPD</Grpg>
         <InitgPty>
            <Nm>ABC LTD</Nm>
            <PstlAdr>
               <AdrLine>Savory Street 7</AdrLine>
               <AdrLine>Coppenhagen</AdrLine>
               <Ctry>FI</Ctry>
            </PstlAdr>
            <Id>
               <OrgId>
                  <BkPtyId>112233445</BkPtyId>
               </OrgId>
            </Id>
         </InitgPty>
      </GrpHdr>
      <PmtInf>
         <PmtInfId>PMNT0000012345000120000001001</PmtInfId>
         <!--Payment01-->
         <PmtMtd>TRF</PmtMtd>
         <PmtTpInf>
            <SvcLvl>
               <Cd>SEPA</Cd>
            </SvcLvl>
         </PmtTpInf>
         <ReqdExctnDt>2025-05-22</ReqdExctnDt>
         <Dbtr>
            <Nm>John Smith</Nm>
            <PstlAdr>
               <AdrLine>Savory Street 7</AdrLine>
               <AdrLine>Coppenhagen</AdrLine>
               <Ctry>FI</Ctry>
            </PstlAdr>
            <Id>
               <OrgId>
                  <BkPtyId>0010010001</BkPtyId>
               </OrgId>
            </Id>
         </Dbtr>
         <DbtrAcct>
            <Id>
               <IBAN>FI1234000000000009</IBAN>
               <!--Transaction01-->
            </Id>
         </DbtrAcct>
         <DbtrAgt>
            <FinInstnId>
               <BIC>NDEAFIHH</BIC>
            </FinInstnId>
         </DbtrAgt>
         <ChrgBr>SLEV</ChrgBr>
         <CdtTrfTxInf>
            <PmtId>
               <InstrId>0000012345000120000011111</InstrId>
               <EndToEndId>0000012345000120000011111</EndToEndId>
            </PmtId>
            <Amt>
               <InstdAmt Ccy="EUR">11,00</InstdAmt>
            </Amt>
            <CdtrAgt>
               <FinInstnId>
                  <BIC>OKOYFIHH</BIC>
               </FinInstnId>
            </CdtrAgt>
            <Cdtr>
               <Nm>Anniele Sampson</Nm>
               <PstlAdr>
                  <AdrLine>Long Street 5</AdrLine>
                  <AdrLine>Glasgow</AdrLine>
                  <Ctry>FI</Ctry>
               </PstlAdr>
            </Cdtr>
            <CdtrAcct>
               <Id>
                  <IBAN>FI1234000000000001</IBAN>
               </Id>
            </CdtrAcct>
            <RmtInf>
               <Strd>
                  <CdtrRefInf>
                     <CdtrRefTp>
                        <Cd>SCOR</Cd>
                     </CdtrRefTp>
                     <CdtrRef>1012</CdtrRef>
                  </CdtrRefInf>
               </Strd>
            </RmtInf>
         </CdtTrfTxInf>
         <CdtTrfTxInf>
            <PmtId>
               <InstrId>0000012345000120000022222</InstrId>
               <EndToEndId>0000012345000120000022222</EndToEndId>
            </PmtId>
            <Amt>
               <InstdAmt Ccy="EUR">22.22</InstdAmt>
            </Amt>
            <CdtrAgt>
               <FinInstnId>
                  <BIC>OKOYFIHH</BIC>
               </FinInstnId>
            </CdtrAgt>
            <Cdtr>
               <Nm>Jean May</Nm>
               <PstlAdr>
                  <AdrLine>Green Square 2/123</AdrLine>
                  <AdrLine>Helsinki</AdrLine>
                  <Ctry>FI</Ctry>
               </PstlAdr>
            </Cdtr>
            <CdtrAcct>
               <Id>
                  <IBAN>FI1234000000000002</IBAN>
               </Id>
            </CdtrAcct>
            <RmtInf>
               <Strd>
                  <CdtrRefInf>
                     <CdtrRefTp>
                        <Cd>SCOR</Cd>
                     </CdtrRefTp>
                     <CdtrRef>1012</CdtrRef>
                  </CdtrRefInf>
               </Strd>
            </RmtInf>
         </CdtTrfTxInf>
      </PmtInf>
   </pain.001.001.02>
</Document>

Error response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errorResponse>
    <groupHeader>
        <messageIdentification>52eeaedab6ab3c10</messageIdentification>
        <creationDateTime>2025-07-07T13:40:35.987Z</creationDateTime>
        <httpCode>400</httpCode> <!-- Error Code -->
    </groupHeader>
    <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="errorPayload">
        <request>
            <url>/premium/v1/bulk-verification-of-payee</url>
        </request>
        <failures>
            <code>error.service</code>
            <description>Document cannot be processed. Make sure that document version and document type are equal.</description>
        </failures>
    </response>
</errorResponse>

Finland: Send request for Verification of Payee in Pain.001 V9

In this example, we send request for verification of payee in Pain.001.001.09 (V9).

This endpoint URL has the following form:

https://api.nordeaopenbanking.com/corporate/premium/v1/bulk-verification-of-payee

When agreement type ‘WS’ (Web Service) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Digest: {digest} 
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Agreement-Type: 'WS'
Agreement-Number: {ws_agreement_number}
Logon-Id: {ws_logon_id}
Document-Version: 'pain.001.001.09'

Note: Agreement-Type header works currently in sandbox only

Note: In Sandbox only, Agreement-Number is not validated. Any value can be used.

Note: In Sandbox only, Logon-Id is not validated. Any value can be used.

When agreement type ‘CCM’ (Corporate Access CCM) is used, the following headers must be sent:

Content-Type: application/xml
X-IBM-Client-Id: {client_id}
X-IBM-Client-Secret: {client_secret}
Digest: {digest} 
Signature: {signature}
X-Nordea-Originating-Date: {date} 
X-Nordea-Originating-Host: {host}
Agreement-Type: 'CCM'
Document-Version: 'pain.001.001.09'

Note: As stated earlier in this documentation, for CCM agreement type, Signer Id and Agreement Number must be provided in request body.

This endpoint supports POST HTTP Method. Request body example:

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>e1a87114d0c102c051d8a3361f2aeeb213</MsgId>
      <CreDtTm>2025-11-18T09:43:28.388270</CreDtTm>
      <NbOfTxs>2</NbOfTxs>
      <CtrlSum>5.0</CtrlSum>
      <InitgPty>
        <Id>
          <OrgId>
            <Othr>
              <Id>14646724079</Id>
              <SchmeNm>
                <Cd>CUST</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>23491943e61e19509a0eada682d07d9308</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <CtrlSum>5.0</CtrlSum>
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
        <LclInstrm>
          <Cd>INST</Cd>
        </LclInstrm>
      </PmtTpInf>
      <ReqdExctnDt>
        <Dt>2025-11-18</Dt>
        <DtTm>14:15:22</DtTm>
      </ReqdExctnDt>
      <Dbtr>
        <Nm>Tom</Nm>
        <PstlAdr>
          <StrtNm>Nekalantie</StrtNm>
          <BldgNb>99860</BldgNb>
          <TwnNm>Morottaja</TwnNm>
          <Ctry>FI</Ctry>
        </PstlAdr>
        <Id>
          <OrgId>
            <Othr>
              <Id>85162022834</Id>
              <SchmeNm>
                <Cd>BANK</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <IBAN>FI0515723000311373</IBAN>
        </Id>
        <Ccy>EUR</Ccy>
      </DbtrAcct>
      <DbtrAgt>
        <FinInstnId>
          <BICFI>NDEAFIHH</BICFI>
          <PstlAdr>
            <StrtNm>Hippoksenkatu</StrtNm>
            <BldgNb>99950</BldgNb>
            <TwnNm>Kaamasmukka</TwnNm>
            <Ctry>FI</Ctry>
          </PstlAdr>
        </FinInstnId>
      </DbtrAgt>
      <CdtTrfTxInf>
        <PmtId>
          <InstrId>c4521074dab0ab89b444</InstrId>
          <EndToEndId>6fe27231e1cc42ceb965fa7f4d018c62d5</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">4.00</InstdAmt>
        </Amt>
        <Cdtr>
          <Nm>Adam</Nm>
          <PstlAdr>
            <StrtNm>Loutunkatu</StrtNm>
            <BldgNb>99980</BldgNb>
            <TwnNm>Skalluvaara</TwnNm>
            <Ctry>FI</Ctry>
          </PstlAdr>
        </Cdtr>
        <CdtrAcct>
          <Nm>Adam</Nm>
          <Id>
            <IBAN>FI1258498520048800</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>Unstructured information</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
      <CdtTrfTxInf>
        <PmtId>
          <InstrId>8757d7b96895bf193aae</InstrId>
          <EndToEndId>40ad296869ee82e9f1b342a2542f50d17d</EndToEndId>
        </PmtId>
        <Amt>
          <InstdAmt Ccy="EUR">1.00</InstdAmt>
        </Amt>
        <Cdtr>
          <Nm>John</Nm>
          <PstlAdr>
            <StrtNm>Loutunkatu</StrtNm>
            <BldgNb>99980</BldgNb>
            <TwnNm>Skalluvaara</TwnNm>
            <Ctry>FI</Ctry>
          </PstlAdr>
        </Cdtr>
        <CdtrAcct>
          <Nm>John</Nm>
          <Id>
            <IBAN>FI1258498520048858</IBAN>
          </Id>
        </CdtrAcct>
        <RmtInf>
          <Ustrd>Unstructured information</Ustrd>
        </RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

And the sample response looks like this (response is always in Pain.002.001.10):

Note: VOP API is asynchronous. As a result, status of transactions in successful response will always be returned as ‘RVNC - Verification of party check on the transaction is not yet completed’. To check further progress of verification, please use GET Verification Status endpoint.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root xmlns:ns2="urn:iso:std:iso:20022:tech:xsd:pain.002.001.10">
    <groupHeader>
        <messageIdentification>444210cc026fc014</messageIdentification>
        <creationDateTime>2025-06-26T12:37:41.994Z</creationDateTime>
        <httpCode>202</httpCode>
    </groupHeader>
    <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Document">
        <ns2:CstmrPmtStsRpt>
            <ns2:GrpHdr>
                <ns2:MsgId>94253a54-3b0b-45d0-a5be-e3fcc2955efc</ns2:MsgId>
                <ns2:CreDtTm>2025-06-26T12:37:41.994Z</ns2:CreDtTm>
            </ns2:GrpHdr>
            <ns2:OrgnlGrpInfAndSts>
                <ns2:OrgnlMsgId>AAAAAAAA0001234-01</ns2:OrgnlMsgId>
                <ns2:OrgnlMsgNmId>pain.001.001.09</ns2:OrgnlMsgNmId>
            </ns2:OrgnlGrpInfAndSts>
            <ns2:OrgnlPmtInfAndSts>
                <ns2:OrgnlPmtInfId>00000001234</ns2:OrgnlPmtInfId>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000001</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 1st Creditor Response Code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 2nd Creditor Response Code -->
                </ns2:TxInfAndSts>
            </ns2:OrgnlPmtInfAndSts>
        </ns2:CstmrPmtStsRpt>
    </response>
</root>

Payment Track & Trace API v1 Multi-Payout Instant API v1

Bulk Verification of Payee API - details

Changes from the previous version

Version 1.2

Version 1.1

Version 1.0

Bulk Verification of Payee

Production access to Bulk Verification of Payee

Sign up for Bulk Verification of Payee

Support for CCM/CAF/CAP and Pain.001.001.09 - Currently only in sandbox

API endpoints

Bulk Verification of Payee request definition and statuses

Bulk Verification of Payee examples

Finland: Send request for Verification of Payee in Pain.001 V3

Finland: Get payee verification status

Finland: Send request for Verification of Payee in Pain.001 V3 - example of input validation error

Finland: Send request for Verification of Payee in Pain.001 V2

Finland: Send request for Verification of Payee in Pain.001 V2 - example of input validation error

Finland: Send request for Verification of Payee in Pain.001 V9