Verification API

Main Verification Endpoint

The only endpoint you need for most use cases:

POST /vop/verify

EPC-Compliant Request Structure

{
  "party": {
    "name": "John Smith"
  },
  "partyAccount": {
    "iban": "DE89370400440532013000"
  },
  "partyAgent": {
    "financialInstitutionId": {
      "bicfi": "DEUTDEFF"
    }
  },
  "requestingAgent": {
    "financialInstitutionId": {
      "bicfi": "BANKDEFF"
    }
  }
}

Simple Response

✅ MTCH - Match Found

{
  "partyNameMatch": "MTCH",
  "matchedName": "John Smith"
}

❌ NMTC - No Match

{
  "partyNameMatch": "NMTC"
}

⚠️ CMTC - Close Match

{
  "partyNameMatch": "CMTC",
  "matchedName": "John Smyth"
}

ℹ️ NOAP - Not Applicable

{
  "partyNameMatch": "NOAP"
}

Response Headers (All Cases):

X-Response-Timestamp: 2024-12-11T19:24:21Z
X-Processing-Time-Ms: 65

Quick Test

# Test the API with curl (EPC-compliant structure)
curl -X POST https://localhost:8443/vop/verify \
  --cert client.crt --key client.key \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: $(uuidgen)" \
  -d '{
    "party": {
      "name": "John Smith"
    },
    "partyAccount": {
      "iban": "DE89370400440532013000"
    },
    "partyAgent": {
      "financialInstitutionId": {
        "bicfi": "DEUTDEFF"
      }
    },
    "requestingAgent": {
      "financialInstitutionId": {
        "bicfi": "BANKDEFF"
      }
    },
    "unstructuredRemittanceInformation": ["INV-2024-001"]
  }'

Request Fields (EPC Structure)

Field	Required	Description	Example
party.name	✅ Yes	Account holder name	"John Smith"
partyAccount.iban	✅ Yes	Bank account number	"DE89370400440532013000"
partyAgent.financialInstitutionId.bicfi	✅ Yes	Responding bank BIC	"DEUTDEFF"
requestingAgent.financialInstitutionId.bicfi	✅ Yes	Requesting bank BIC	"BANKDEFF"
unstructuredRemittanceInformation	❌ No	Payment reference array	["INV-2024-001"]

Response Fields

Field	Description	Values
partyNameMatch	EPC VoP verification outcome	MTCH, NMTC, CMTC, NOAP
matchedName	Actual account holder name (optional)	Name from bank records
idMatch	ID verification result (ID-based only)	MTCH, NMTC, NOAP

Response Headers:

Header	Description	Example
X-Response-Timestamp	Response timestamp (UTC)	2024-12-11T19:24:21Z
X-Processing-Time-Ms	Processing time in milliseconds	65

Error Handling

Invalid IBAN

{
  "error": "INVALID_IBAN",
  "message": "IBAN format is incorrect",
  "field": "iban"
}

Missing Name

{
  "error": "MISSING_FIELD",
  "message": "Name field is required",
  "field": "name"
}

Service Unavailable

{
  "error": "SERVICE_UNAVAILABLE",
  "message": "Verification service temporarily unavailable",
  "retry_after": 30
}

Integration Examples

JavaScript/Node.js

const response = await fetch('https://your-vop-service.com/vop/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Request-ID': crypto.randomUUID(),
    'Authorization': 'Bearer your-api-key'
  },
  body: JSON.stringify({
    party: {
      name: 'John Smith'
    },
    partyAccount: {
      iban: 'DE89370400440532013000'
    },
    partyAgent: {
      financialInstitutionId: {
        bicfi: 'DEUTDEFF'
      }
    },
    requestingAgent: {
      financialInstitutionId: {
        bicfi: 'BANKDEFF'
      }
    }
  })
});

const result = await response.json();

if (result.partyNameMatch === 'MTCH') {
  // Proceed with payment
  processPayment();
} else if (result.partyNameMatch === 'NMTC') {
  // Block payment - potential fraud
  blockPayment('Fraud risk detected');
} else if (result.partyNameMatch === 'CMTC') {
  // Close match - request user confirmation
  requestUserConfirmation(result.matchedName);
}

Python

import requests
import uuid

response = requests.post('https://your-vop-service.com/vop/verify',
  json={
    'party': {
      'name': 'John Smith'
    },
    'partyAccount': {
      'iban': 'DE89370400440532013000'
    },
    'partyAgent': {
      'financialInstitutionId': {
        'bicfi': 'DEUTDEFF'
      }
    },
    'requestingAgent': {
      'financialInstitutionId': {
        'bicfi': 'BANKDEFF'
      }
    }
  },
  headers={
    'Authorization': 'Bearer your-api-key',
    'X-Request-ID': str(uuid.uuid4())
  }
)

result = response.json()

if result['partyNameMatch'] == 'MTCH':
    # Proceed with payment
    process_payment()
elif result['partyNameMatch'] == 'NMTC':
    # Block payment - potential fraud
    block_payment('Fraud risk detected')
elif result['partyNameMatch'] == 'CMTC':
    # Close match - request user confirmation
    request_user_confirmation(result['matchedName'])

Testing Interface

Visit https://localhost:8443/test for interactive testing:

1. Enter IBAN and name
2. Click “Verify”
3. See instant results
4. Test different scenarios