Quick Start Guide

This guide will help you quickly get started with the VoP (Verification of Payee) API service. We’ll cover the essentials you need to begin verifying account ownership.

API Access

Base URLs

Production: https://{eds-assigned-endpoint}/vop/api/v1
API Documentation: /swagger-ui/

Authentication

The VoP API requires mutual TLS (mTLS) authentication for all communications:

Qualified certificates from approved Certificate Authority (CA)
Certificates must be listed in European Trusted Lists (ETL)
Valid for maximum of 2 years
Must follow eIDAS requirements

Core Functionality

VoP API provides real-time account ownership verification with the following features:

Account Verification: Validate account ownership and details
Service Level: 2-second maximum response time, 99.9% availability
SEPA Coverage: Support for all SEPA countries
Data Protection: Full GDPR compliance

Matching Levels

Exact Match: Perfect alignment between provided and stored details
Close Match: Minor variations in spelling or formatting
Partial Match: Significant differences detected

Key API Endpoints

Verification Process

Submit Verification

POST /verify

Submit a new verification request

Get Result

GET /verify/{request_id}

Retrieve the verification result

Account Management

POST /accounts     # Create account (test environment only)
GET /accounts/{id} # Retrieve account details

Making Your First API Call

1. Submit Verification Request

Send a POST request to /verify:

POST https://{eds-assigned-endpoint}/vop/api/v1/verify
Content-Type: application/json

{
  "name": "John Doe",
  "iban": "GB29NWBK60161331926819",
  "lei": "5493000P35CNNWC4CN90"  // optional for business accounts
}

2. Get Verification Response

GET https://{eds-assigned-endpoint}/vop/api/v1/verify/{request_id}

Response:

{
  "response_id": "123e4567-e89b-12d3-a456-426614174000",
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "name_match_code": "EXACT",
  "id_match_code": "MATCH",
  "matched_name": "John Doe",
  "response_timestamp": "2024-12-19T22:29:50Z",
  "created_at": "2024-12-19T22:29:50Z"
}

Match Codes Explained

EXACT: Perfect match of account holder name
MATCH: Account details verified successfully
PARTIAL: Some details match but with variations
NO_MATCH: Account details could not be verified

Error Handling

The API implements standardized error categories as defined by the VoP Scheme:

Error Categories

Technical Errors (VOP_001): System or network issues
Security Errors (VOP_002): Certificate or authentication failures
Timeout Errors (VOP_003): Response time or service availability issues
Validation Errors (VOP_004): Invalid input or business rule violations
Business Errors (VOP_005): Account-related or service restriction issues

Error Response Format

{
  "errorReference": "ERR-123e4567",
  "timestamp": "2024-12-19T22:24:31Z",
  "error": {
    "code": "VOP_004",
    "category": "VALIDATION_ERROR",
    "message": "Invalid account details",
    "details": {
      "field": "iban",
      "reason": "Account not found in directory"
    }
  },
  "metadata": {
    "respondingPSP": "BANKXX22",
    "originalRequest": "REQ-123456"
  }
}