Bulk Verification of Payee API - details
Bulk Verification of Payee API is a service which enables Nordea Corporate customers whom use Web Services - CPS (Finland) to reduce risk when making SEPA payments. We do so by enabling our corporate customers to confirm the validity of a payees’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 WS - CPS customers.
BULK VOP API can parse POST XML data based on WS CPS Pain.001.V2 and Pain001.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 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 client.
During the subscription process of the BULK VOP production version you will see the BULK VOP product plan, which is stating: “10 000 calls per hour”. Please be informed, that this number is related to the maximum allowed amount of calls per hour from you to Nordea (rate limit).
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.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.
The examples and following details are valid for Pain.001.V3 ( V2 will be provided in later updates )
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>
</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>
</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>
</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>
</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>
</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>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVNC</ns2:TxSts>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000003</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVNC</ns2:TxSts>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000004</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVNC</ns2:TxSts>
</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>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000002</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVMC</ns2:TxSts>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000003</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVNM</ns2:TxSts>
</ns2:TxInfAndSts>
<ns2:TxInfAndSts>
<ns2:OrgnlEndToEndId>AAAE2EidTEST000004</ns2:OrgnlEndToEndId>
<ns2:TxSts>RVNA</ns2:TxSts>
</ns2:TxInfAndSts>
</ns2:OrgnlPmtInfAndSts>
</ns2:CstmrPmtStsRpt>
</response>
</root>
Input Validation
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 IBAN
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>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>
</Id>
</CdtrAcct>
<RmtInf>
<Strd>
<CdtrRefInf>
<Tp>
<CdOrPrtry>
<Cd>SCOR</Cd>
</CdOrPrtry>
</Tp>
<Ref>00000000120000000001</Ref>
</CdtrRefInf>
</Strd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>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>
</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>API endpoints
The prerequisite for integration, is client’s capability to keep track on opened pre-validation cases and polling on regular basis, e.g. twice a day, to collect status changes and available results from the BULK VOP API.
Bulk Verification of Payee API endpoints:
| 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 |
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 VOP result.
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. |