Skip to main content

Verification of Payee (Gateway)

EPC-compliant verification of payee (VoP), delivered through a single, easy-to-integrate API.

This API is organised around REST. The API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Make all API requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Metadata​

  • OpenAPI version: 3.0.4
  • API version: 1.0.2

External Documentation​

Servers​

URLDescriptionNote
https://test-apigw.apicunia.comSandboxUses a fixed set of dummy accounts with known outcomes.
Performance may be slower due to reduced scaling and cold‑start effects.
https://apigw.apicunia.comProduction

Authentication​

Authentication for this API is via OAuth 2.0. Requesting client must provide a valid bearer/access token in the Authorization header for all API requests. The API uses the Client Credentials Grant flow.

Token Endpoint​

GET https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token

Request Example​

bash
curl --location --request GET 'https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={YOUR_CLIENT_ID}' \
--data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
--data-urlencode 'scope={YOUR_SCOPE_ID}/.default'

For additional information on this method of API authentication see OAuth 2.0.

Verification of Payee​

Verify Payee
POST
/vopgateway/v1/payee-verifications

Summary​

Verification of Payee detail endpoint.

Returns a Regulated EPC VoP Response indicating whether the supplied Payee details are a match or otherwise.

As Requestor:
The endpoint validates and routes an incoming VoP request to the applicable responding PSP/RVM and relays the VoP response back to the calling application. The Gateway API enriches the incoming request by performing a BIC lookup on the incoming IBAN in order to route to the responding PSP/RVM.

Request​

Request Headers​

NameTypeFormatRequiredDescription
X-Request-IDstringuuidYesThe Requesting PSP's reference ID of the VoP Request
X-Request-Timestampstringdate-timeYesTimestamp of the VoP Request in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ss.sssZ)

Request Body​

Content Type: application/json
Schema: VerificationOfPayeeRequest

Schema: VerificationOfPayeeRequest
{
  "party": {
    "name": "string (optional if identification present)",
    "identification": {
      "organisationId": {
        "lei": "string (Code LEI (Legal Entity Identifier) ISO 17442)",
        "anyBIC": "string (A BIC11 Business Identifier Code, used to identify a specific branch of a bank or financial institution)",
        "others": [
          {
            "identification": "string",
            "schemeNameCode": "BANK | CBID | CHID | CINC | COID | CUST | DUNS | EMPL | GS1G | SREN | SRET | TXID | BDID | BOID",
            "schemeNameProprietary": "string",
            "issuer": "string"
          }
        ]
      }
    }
  },
  "partyAccount": {
    "iban": "string (International Bank Account Number upt 34 characters depending on the country)"
  }
}

Examples​

IBAN and Party Name
{
  "party": {
    "name": "Lukas Klein"
  },
  "partyAccount": {
    "iban": "DE33500105175746121394"
  }
}

Response​

Response Headers​

NameTypeFormatRequiredDescription
X-Request-IDstringuuidYesThe Requesting PSP's reference ID of the VoP Request
X-Response-Timestampstringdate-timeYesTimestamp of the VoP Response in ISO 8601 UTC format

Response Body​

Content type: application/json Schema: VerificationOfPayeeResponse

Schema: VerificationOfPayeeResponse
{
  "partyNameMatch": "MTCH | CMTC | NMTC | NOAP",
  "partyIdMatch": "MTCH | NMTC | NOAP",
  "matchedName": "string (If the result of partyNameMatch is CMTC, then matchedName is mandatory and can only be used in this case)"
}

200 OK Response​

Regulated EPC VoP response codes (HTTP Status Code 200)

CodeMeaningNote
MTCHMatchAccount is Valid and the Name Matches exactly
CMTCClose Match (matched name is also included in the response)Account is Valid and the Name is a partial Match
NMTCNo MatchAccount is Valid but the Name does not match
NOAPNot ApplicableAccount matching is not possible

NOTE: There are some legitimate reasons for a NOAP but the specific reason is not disclosed by the responding PSP/RVM. The account IBAN supplied may well be valid at the responding PSP/RVM but;

  • Not eligible for VoP (none accepting payment account)
  • Account is confidential/protected and reason cannot legally be disclosed
  • Issue with Name data at the PSP so cannot perform a VoP check
  • Explicitly excluded from VoP by the PSP and again reason cannot be disclosed

Party Name Examples (200 OK Status Code)​

Match – Party Name (Person or Legal)
{
  "partyNameMatch": "MTCH"
}

Party ID Examples (200 OK Status Code)​

Match – Party ID (LEI/BIC/TXID/EUID/..)
{
  "partyIdMatch": "MTCH"
}

400 Status Code​

Bad/Malformed VoP Request. The request body is malformed. See Problem Details for additional information about API errors.

Bad Request Examples (400 Status Code)​

Format Error (Missing Name/Identifier)
{
  "type": "https://example.com/probs/FORMAT_ERROR",
  "code": "FORMAT_ERROR",
  "title": "Validation of VoP Request failed. See Detail",
  "status": 400,
  "detail": "At least one of 'name' or 'identification' must be provided.",
  "instance": "/vopgateway/v1/payee-verifications"
}

401 Status Code​

Invalid Request. The Requestor is not authorised to perform the request. See Problem Details for additional information about API errors.

Unauthorised Examples (401 Status Code)​

Invalid Client 1
{
  "type": "https://example.com/probs/CLIENT_INVALID",
  "code": "CLIENT_INVALID",
  "title": "Validating the client failed. See Detail",
  "status": 401,
  "detail": "Invalid Client, no permission to access resource.",
  "instance": "/vopgateway/v1/payee-verifications"
}

500 Status Code​

Internal Server Error. This code is used whenever a technical problem occurred in the application code or application server that prevented the execution of the request. See Problem Details for additional information about API errors.

Internal Server Error Example (500 Status Code)​

Internal Server Error
{
  "type": "https://example.com/probs/SERVER_ERROR",
  "code": "SERVER_ERROR",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The API server experienced an unexpected error processing the request",
  "instance": "/vopgateway/v1/payee-verifications"
}

502 Status Code​

Bad Gateway Error. This code is used whenever a technical problem occurred and the server acted as a gateway or proxy and received an invalid response from an upstream server. See Problem Details for additional information about API errors.

Bad Gateway Example (502 Status Code)​

Bad Gateway Error
{
  "type": "https://example.com/probs/SSL_ERROR",
  "code": "SSL_ERROR",
  "title": "SSL/TLS handshake failed",
  "status": 502,
  "detail": "SSL/TLS handshake failed.",
  "instance": "/vopgateway/v1/payee-verifications"
}

504 Status Code​

Gateway Timeout Error. This code is used whenever the Apicunia server was working as a gateway to get a response and could not get a response within the alloted time. See Problem Details for additional information about API errors.

Gateway Timeout Example (504 Status Code)​

Gateway Timeout Error
{
  "type": "https://example.com/probs/TIMEOUT_ERROR",
  "code": "TIMEOUT_ERROR",
  "title": "Responder Timeout",
  "status": 504,
  "detail": "Responder did not respond within timespan (seconds): 5",
  "instance": "/vopgateway/v1.0/confirmation-payee/name-verification"
}

Sandbox data (Dummy Accounts)​

The following IBAN and Party Name/ID details may be used against the Apicunia VoP Sandbox for intitial automated integration testing.

These are dummy accounts and do not connect to the live VoP network.

Each combination will trigger a known 200 Status OK VoP response with the specific result detailed.

IBANParty NameSandbox VoP Response
DE33500105175746121394Lukas Klein"partyNameMatch": "MTCH" IBAN is valid and the Name matches exactly
BE71096123456769Biroelas Search Ltd"partyNameMatch": "MTCH" IBAN is valid and the Name matches exactly
BE19131422633712Marc Baert"partyNameMatch": "CMTC" IBAN is valid and the Name is a partial/close match
LU770105783789356856Henri Andér"partyNameMatch": "CMTC" IBAN is valid and the Name is a partial/close match
AT102040454763965773Anna Bauer"partyNameMatch": "NMTC" IBAN is valid but the Name does not match
DE47500105179331844773Sandra Martin"partyNameMatch": "NMTC" IBAN is valid but the Name does not match
BE23817417767591Ada Georgiou"partyNameMatch": "NOAP" IBAN and Name matching is not possible
NL58ABNA4475689805Eeli Koskinen"partyNameMatch": "NOAP" IBAN and Name matching is not possible