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​

URLDescription
https://test-apigw.apicunia.comTest/Sandbox
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
  • 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 Examples (500 Status Code)​

Internal Server Error
{
  "type": "https://example.com/probs/SERVER_ERROR",
  "code": "SERVER_ERROR",
  "title": "Encountered an unexpected error/condition",
  "status": 500,
  "detail": "Encountered an unexpected error/condition.",
  "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 Examples (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"
}