API Conventions

Base URLs and Versions

• Production:
  • Token URL: https://keycloak.public.apps.prod.vr-payment.digital/auth/realms/EPI/protocol/openid-connect/token/
  • Service URL:
    • Merchant API: https://wero.api.vr-payment.digital/
    • TSP API: https://wero.api.vr-payment.digital/tsp/
• Testing environment: https://vrp-epi-payment-service-test.public.stg.vrpintegration.dev/api/v1/payments \
• URL- version via /v1

Resources and paths

• Plural resources: /payments, /refunds, /consents, /authorizations
• Single resource: /payments
• Actions as sub-paths: /payments/{paymentId}/consents, /payments/{paymentId}/refunds

HTTP Methods

• POST → create/trigger
• GET → read/retrieve
• DELETE → delete/invalidate

Standard Headers

• Authorization: Bearer <access token> (OAuth2 Client Credentials)
• Content-Type: application/json + application/problem+json

Request/Response Format

• JSON UTF-8

Data Types and Formats

• Time: ISO-8601, UTC
• Amount: Decimal Amounts

Error Format

• return HTTP status code combined with structured JSON body.
• Example: { "type": "/problem/connection-error", "title": "Service Unavailable", "status": 503, "detail": "Connection to database timed out", "instance": "/problem/connection-error#token-info-read-timed-out"
• 4xx → Client errors
• 5xx → Server-side errors

Lifecycle states

• PENDING → SUCCESSFUL/FAILED

Session Timeout

• after 10 minutes