Bulk Verification of Payee API - details

Bulk Verification of Payee API is a service which enables Nordea Corporate customers whom use Web Services - Corporate Payments Service (Finland) 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 Webservice - Corporate Payments Service customers.

The Bulk VOP API POST calls works based on Webservice Corporate Payments Service Pain.001.001.02 (Pain.001 V2) and Pain.001.001.03 (Pain.001 V3) ISO file format. 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 payments will be returned in Pain.002.001.10 (Pain002 V10) format and a status will be applied: 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.

This document is covers the first version of the Sandbox release, more in-depth documentation will be provided in following releases and once the production version is available.

Version 1.1

Updated API description

Added in GET API call support for mixed results: vop-return-status : mixed

Version 1.0

We have implemented the API micro service application 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.

In the Sandbox API console the following configuration should be used:

Choose Application: Bulk Verification of Payee Choose Flow: No Authentication Client Secret: Your client secret.

BULK VOP API

PAIN.001 v3

Correct Pain.001 v3

Correct Request for Pain.001.001.03 will look like this:

<?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>4</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>  <!-- Debtor 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>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>AInstIdTest0002</InstrId>
					<EndToEndId>AAAE2EidTEST000002</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>AInstIdTest0003</InstrId>
					<EndToEndId>AAAE2EidTEST000003</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>AInstIdTest0004</InstrId>
					<EndToEndId>AAAE2EidTEST000004</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> <!-- 4rd Creditor IBAN-->
                    </Id>
				</CdtrAcct>
				<RmtInf>
					<Strd>
						<CdtrRefInf>
							<Tp>
								<CdOrPrtry>
									<Cd>SCOR</Cd>
								</CdOrPrtry>
							</Tp>
							<Ref>00000000120000000004</Ref>
						</CdtrRefInf>
					</Strd>
				</RmtInf>
			</CdtTrfTxInf>
		</PmtInf>
	</CstmrCdtTrfInitn>
</Document>

Response from POST endpoint for above example will look like this:

(Response is always in Pain.002.001.10)

RVNC - Verification of party check on the transaction is not yet completed

<?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.03</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:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000003</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 3rd Creditor Response code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000004</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNC</ns2:TxSts> <!-- 4rd Creditor Response code -->
                </ns2:TxInfAndSts>
            </ns2:OrgnlPmtInfAndSts>
        </ns2:CstmrPmtStsRpt>
    </response>
</root>

Response from GET endpoint for above example will look like this:

(Response is always in Pain.002.001.10)

Vop return code meaning:

RCVC - Match

RVMC - Close Match

RVNM - No Match

RVNA - Not possible to verify/ not available

<?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.03</ns2:OrgnlMsgNmId>
            </ns2:OrgnlGrpInfAndSts>
            <ns2:OrgnlPmtInfAndSts>
                <ns2:OrgnlPmtInfId>00000001234</ns2:OrgnlPmtInfId>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000001</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RCVC</ns2:TxSts> <!-- 1st Creditor Final Response code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVMC</ns2:TxSts> <!-- 2nd Creditor Final Response code -->
                </ns2:TxInfAndSts>
				    <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000003</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNM</ns2:TxSts> <!-- 3rd Creditor Final Response code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000004</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVNA</ns2:TxSts> <!-- 4rd Creditor Final Response code -->
                </ns2:TxInfAndSts>
            </ns2:OrgnlPmtInfAndSts>
        </ns2:CstmrPmtStsRpt>
    </response>
</root>

Pain.001 v3 - Input Validation - Error message

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 Creditor IBAN format

Request for Pain.001.001.03 with incorrect Creditor IBAN Format in Pain.001.001.03 will look like this:

<?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>

Response with Error code for Pain.001 v3 with IBAN incorrect Format is provided below:

<?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>

PAIN.001 v2

Correct Pain.001 v2

Correct Request for Pain.001.001.02 will look like this:

<?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>

Response from POST endpoint for above example will look like this:

(Response is always in Pain.002.001.10)

RVNC - Verification of party check on the transaction is not yet completed

<?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.03</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>

Response from GET endpoint for above example will look like this:

(Response is always in Pain.002.001.10)

VOP return code meaning:

RCVC - Match

RVMC - Close Match

RVNM - No Match

RVNA - Not possible to verify/ not available

<?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.03</ns2:OrgnlMsgNmId>
            </ns2:OrgnlGrpInfAndSts>
            <ns2:OrgnlPmtInfAndSts>
                <ns2:OrgnlPmtInfId>00000001234</ns2:OrgnlPmtInfId>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000001</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RCVC</ns2:TxSts> <!-- 1st Creditor Final Response Code -->
                </ns2:TxInfAndSts>
                <ns2:TxInfAndSts>
                    <ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
                    <ns2:TxSts>RVMC</ns2:TxSts> <!-- 2nd Creditor Final Response Code -->
                </ns2:TxInfAndSts>
            </ns2:OrgnlPmtInfAndSts>
        </ns2:CstmrPmtStsRpt>
    </response>
</root>

Incorrect Pain.001 v2 - Input Validation - Error code

Request for Pain.001.001.02 with error in <document secrion - that was put as a comment using: will look like this:

<?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"--> 
<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>

Response to above Pain001 v2 file with error on section will look like below:

<?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>

API endpoints

The prerequisite for integration, is client’s capability to keep track on opened pre-validation cases and polling on regular basis, to collect status changes and available results from the BULK VOP API.

Bulk Verification of Payee API endpoints:

As you can see from the table, the Bulk Verification of Payee API supports HTTP GET and HTTP POST requests.

The first endpoint can be used to open a new VOP request. The second endpoint can be used to retrieve a VOP result.

Endpoint	Supported HTTP Methods
`Send POST request: /premium/v1/bulk-verification-of-payee`	POST
`Send GET request: /premium/v1/bulk-verification-of-payee/{batch_identification}`	GET

vop-return-status is mandatory header in get request, otherwise error will be returned:

error.validation Invalid vop-return-status value. Must be one of: ‘match’, ‘close match’, ‘no match’, ‘not available’, ‘mix’

Bulk Verification of Payee API response codes:

Here you can find response codes for Bulk Verification of Payee API endpoints.

List of possible return codes:

Code	Description
200	Success for GET endpoint
202	Success for POST endpoint
400	The request is invalid
401	Unauthorised
500	Internal server error. The request could not be delivered.

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