Skip to main content
Version: v2

V2 API Environment Availability

This page describes which V2 endpoints are available in each CCG environment, what status codes to expect when an endpoint is not available, and how the blocking mechanism works at both the application and infrastructure layers.

Environment Access Matrix​

EnvironmentV2 Endpoints AvailableBehaviour
dev✅ YesAll implemented endpoints accessible; stubs return 501
test✅ YesAll implemented endpoints accessible; stubs return 501
reg✅ YesAll implemented endpoints accessible; stubs return 501
perf✅ YesAll implemented endpoints accessible; stubs return 501
stage❌ NoAll V2 routes return 503 Service Unavailable
prod❌ NoAll V2 routes return 503 Service Unavailable
V2 is not production-ready

The V2 API is currently in active development. All /v2/ paths are blocked in stage and production until the full split-tender implementation is complete and has passed production readiness review.

Response Codes​

503 — Environment Block (stage / prod)​

Any request to a /v2/ path in stage or prod returns a 503 Service Unavailable before reaching the application:

{
  "status": 503,
  "title": "V2_ENDPOINT_UNAVAILABLE",
  "detail": "V2 endpoints are not available in this environment. V2 API access is restricted to non-production environments only."
}

This block operates at two independent layers — either is sufficient to stop the request:

  1. Istio VirtualService fault injection — the service mesh rejects the request at the gateway before it enters the cluster.
  2. Application filter (V2EndpointFilter) — a Spring WebFlux filter short-circuits the request at the service level with a 503 JSON response.

501 — Not Yet Implemented (lower environments only)​

In dev, test, reg, and perf, a subset of V2 endpoints are available as declared stubs — routes that are registered in the router but whose implementation is in progress. Calling one of these returns a 501 Not Implemented:

{
  "status": 501,
  "title": "V2_ENDPOINT_NOT_IMPLEMENTED",
  "detail": "Capture for split-tender V2 is under active development and not yet available for consumption."
}

The detail field contains an endpoint-specific message describing what is under development.

Endpoint Status Reference​

Payment Service (wallet-payment-service)​

EndpointMethodStatusNotes
/v2/paymentsPOST✅ ImplementedCreate split-tender payment
/v2/paymentsGET✅ ImplementedGet payment by merchantTransactionId
/v2/payments/{id}GET✅ ImplementedGet payment by paymentId
/v2/payments/{id}/capturePATCH✅ ImplementedCapture authorized payment
/v2/payments/{id}/cancelPATCH🔧 Stub (501)In development
/v2/refundsPOST✅ ImplementedCreate refund
/v2/refunds/{refundId}GET✅ ImplementedGet refund status

Auth Service (wallet-auth-service)​

EndpointMethodStatusNotes
/v2/sessionsPOST✅ ImplementedCreate checkout session
/v2/sessions/{id}GET✅ ImplementedGet session status
/v2/checkout-sessions/{id}GET🔧 Stub (501)In development
/v2/checkout-sessions/{id}/cancelPOST🔧 Stub (501)In development
/v2/checkout-sessions/{id}/child-sessionsPOST🔧 Stub (501)In development
/v2/checkout-sessions/{id}PATCH🔧 Stub (501)In development

How It Works​

The access control model uses two orthogonal, independently operating layers:

Incoming /v2/ request
        │
        ▼
┌───────────────────────────────────────────────────────────┐
│  Layer 1: Istio VirtualService (gateway)                  │
│  stage / prod → fault injection: HTTP 503                 │
│  lower envs   → pass through to cluster                   │
└───────────────────────────────────────────────────────────┘
        │ (lower envs only)
        ▼
┌───────────────────────────────────────────────────────────┐
│  Layer 2: V2EndpointFilter  @Order(-200)                  │
│  stage / prod → 503 JSON response (application level)     │
│  lower envs   → pass through to next filter               │
└───────────────────────────────────────────────────────────┘
        │ (lower envs only)
        ▼
┌───────────────────────────────────────────────────────────┐
│  Layer 3: V2NotImplementedFilter  @Order(-100)            │
│  Handler annotated @V2NotImplemented → 501 JSON response  │
│  Handler not annotated               → pass through       │
└───────────────────────────────────────────────────────────┘
        │ (implemented endpoints only)
        ▼
   Controller handler executes normally

Both infrastructure controls (Istio) and application controls (V2EndpointFilter) independently enforce the production block. This provides defense-in-depth: even if one layer is misconfigured, the other prevents exposure.

Infrastructure Routing​

V2 public paths are routed through the CCG API v2 VirtualService (ccg-api-v2). All CCG V2 endpoints are exposed via Istio VirtualService — there is no direct HCP ingress for any of these paths. The Istio IngressGateway (istio-ingressgateway) sits at the cluster edge and forwards traffic to the appropriate service via the VirtualService route rules.

MethodPublic pathRewrites toServiceRouting
POST/payments/v2/paymentspayment-serviceVirtual (Istio)
GET/payments/v2/paymentspayment-serviceVirtual (Istio)
POST/token/payments/v2/paymentspayment-service (PCI)Virtual (Istio)
PATCH/payments/{id}/cancel/v2/payments/{id}/cancelpayment-serviceVirtual (Istio)
POST/payments/{id}/capture/v2/payments/{id}/capturepayment-serviceVirtual (Istio)
POST/refunds/v2/refundspayment-serviceVirtual (Istio)
GET/refunds/{refundId}/v2/refunds/{refundId}payment-serviceVirtual (Istio)
POST/sessions/v2/sessionsauth-serviceVirtual (Istio)
GET/sessions/{sessionId}/v2/sessions/{sessionId}auth-serviceVirtual (Istio)
GET/checkout-sessions/{id}/v2/checkout-sessions/{id}auth-serviceVirtual (Istio)
POST/checkout-sessions/{id}/cancel/v2/checkout-sessions/{id}/cancelauth-serviceVirtual (Istio)
POST/checkout-sessions/{id}/child-sessions/v2/checkout-sessions/{id}/child-sessionsauth-serviceVirtual (Istio)
PATCH/checkout-sessions/{id}/v2/checkout-sessions/{id}auth-serviceVirtual (Istio)

In stage and prod, Istio fault injection (HTTPFaultInjection.Abort, 100% rate, HTTP 503) is applied to all routes before the rewrite reaches the destination service.