AP2-like
AP2-inspired
AP2 Human Present 모델 참고

AP2 compliant
AP2 certified
공식 AP2 구현

dev.ucp.common.payment.ap2_mandate

com.example.payment.ap2_like

Merchant Checkout 상태가 Core DB와 다르면 Merchant가 정답이다.
Pay Payment 상태가 Core DB와 다르면 Pay가 정답이다.
Merchant Order 상태가 Core DB와 다르면 Merchant가 정답이다.
Core의 PurchaseRequest는 여러 원본 상태를 사용자 관점으로 집계한 상태다.

product:read
cart:read
cart:write
checkout:prepare
purchase:request
purchase:status

payment-method:sensitive-read
payment-approval:approve
payment-approval:reject
credential:issue
payment:execute

GET https://merchant.example/.well-known/ucp

dev.ucp.shopping.catalog.search
dev.ucp.shopping.catalog.lookup
dev.ucp.shopping.cart
dev.ucp.shopping.checkout
dev.ucp.shopping.order
com.example.payment.ap2_like       # Custom AP2-like Capability
com.example.pay                    # Custom Payment Handler

{
  "errorCode": "UCP_CAPABILITY_INCOMPATIBLE",
  "message": "이 판매자는 현재 우리 Agent 구매 흐름을 지원하지 않습니다.",
  "currentState": "NEGOTIATION_FAILED",
  "nextAction": "CHOOSE_ANOTHER_MERCHANT"
}

POST {merchantBaseUrl}/catalog/search
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Request-Id: req-...
Content-Type: application/json

{
  "query": "10만 원 이하 러닝화",
  "context": {
    "country": "KR"
  }
}

{
  "productRef": {
    "merchantId": "merchant-a",
    "externalProductId": "shoe-123"
  },
  "name": "러닝화 A",
  "price": {
    "amount": 89000,
    "currency": "KRW"
  },
  "availability": "IN_STOCK",
  "imageUrl": "https://merchant.example/images/shoe-123.jpg"
}

POST /carts
GET  /carts/{id}
PUT  /carts/{id}
POST /carts/{id}/cancel

local_cart_projection_id
user_id
merchant_id
external_cart_id
platform_revision
raw_cart_json
normalized_summary_json
last_synced_at
expires_at

POST {merchantBaseUrl}/checkout-sessions

{
  "id": "checkout-123",
  "status": "incomplete",
  "messages": [
    {
      "code": "missing",
      "path": "$.fulfillment.methods[0].selected_destination_id",
      "severity": "recoverable",
      "content": "배송지가 필요합니다."
    }
  ]
}

PUT {merchantBaseUrl}/checkout-sessions/checkout-123

가격 재계산
할인 재계산
재고 확인
옵션 유효성 확인
배송 가능 지역 확인
배송비 계산
세금·정책 계산
지원 Payment Handler 반환
Checkout 만료시각 설정

incomplete
requires_escalation
ready_for_complete
complete_in_progress
completed
canceled

{
  "id": "checkout-123",
  "status": "ready_for_complete",
  "currency": "KRW",
  "line_items": [],
  "totals": [
    {"type": "total", "amount": 87000}
  ],
  "com.example.payment.ap2_like": {
    "merchant_authorization": "<detached-jws>"
  }
}

{
  "merchantId": "merchant-a",
  "businessCheckoutId": "checkout-123",
  "ucpVersion": "2026-08-25",
  "status": "ready_for_complete",
  "checkoutDigest": "sha256:...",
  "total": {
    "amount": 87000,
    "currency": "KRW"
  },
  "signatureVerified": true,
  "verifiedAt": "2026-09-02T17:00:00+09:00",
  "expiresAt": "2026-09-02T17:05:00+09:00"
}

Checkout ready_for_complete?
서명 검증 완료?
Checkout 만료 전?
같은 Checkout의 활성 PurchaseRequest 없음?
지원 Payment Handler 있음?

purchaseRequestId
userId
merchantId
businessCheckoutId
checkoutEvidenceId
status = AWAITING_APPROVAL
completionIdempotencyKey

POST /internal/v1/authorization-sessions

판매자
상품명·옵션·수량
상품금액·할인·배송비·세금
최종 결제금액
배송지
선택 결제수단의 마스킹 정보
Checkout 만료시각

Checkout Mandate-like
Payment Mandate-like
Payment Credential Token
Authorization Receipt

특정 Merchant
특정 Checkout
특정 금액
특정 통화
특정 결제수단 Reference
짧은 만료시간
한 번의 논리적 결제

GET /internal/v1/authorization-sessions/{id}/artifact

POST {merchantBaseUrl}/checkout-sessions/{checkoutId}/complete
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: checkout-complete-{purchaseRequestId}

{
  "payment": {
    "instruments": [
      {
        "id": "instrument-1",
        "handler_id": "example_pay_1",
        "type": "card",
        "selected": true,
        "display": {
          "description": "VISA •••• 1234"
        },
        "credential": {
          "type": "COM_EXAMPLE_PAY_TOKEN",
          "token": "<one-time-payment-credential>"
        }
      }
    ]
  },
  "com.example.payment.ap2_like": {
    "checkout_mandate": "<signed-checkout-mandate-like>"
  }
}

AP2-like Capability가 이 세션에서 협상됐는가?
Checkout Mandate-like가 존재하는가?
서명자가 신뢰하는 Platform Key인가?
Mandate가 만료되지 않았는가?
Mandate가 자신의 Checkout ID를 가리키는가?
checkoutDigest가 현재 Checkout과 같은가?
금액·통화·Line Item이 현재 Checkout과 같은가?
자신의 Merchant Authorization이 Mandate 내부에 포함돼 있는가?

POST https://pay.example/merchant/v1/payments
Authorization: Bearer <merchant-client-token>
Idempotency-Key: merchant-checkout-checkout-123
Content-Type: application/json

{
  "merchantId": "merchant-a",
  "businessCheckoutId": "checkout-123",
  "amount": 87000,
  "currency": "KRW",
  "credentialToken": "<one-time-payment-credential>"
}

호출 Merchant 인증 성공?
요청 merchantId == Credential audience?
요청 Checkout ID == Credential binding?
요청 금액·통화 == Credential 금액·통화?
Payment Mandate-like 서명 정상?
Payment Mandate-like checkoutDigest 일치?
사용자 승인 상태가 여전히 APPROVED?
Credential 만료 전?
Credential 미폐기?
Credential이 다른 논리적 결제에 사용되지 않았는가?
Idempotency-Key 재시도 규칙을 만족하는가?

UNKNOWN에서 금지
- 새 Payment 생성
- 다른 Idempotency-Key로 자동 재결제
- 사용자에게 단순 실패로 표시

UNKNOWN에서 허용
- PG 거래 상태 조회
- 같은 Payment ID로 Reconcile
- 운영자 확인

{
  "id": "checkout-123",
  "status": "completed",
  "order": {
    "id": "merchant-order-999",
    "permalink_url": "https://merchant.example/orders/merchant-order-999"
  }
}

localProjectionId
userId
merchantId
externalOrderId
businessCheckoutId
purchaseRequestId
currentStatus
rawOrderJson
lastVerifiedAt

get_purchase_status(purchaseRequestId)

Core PurchaseRequest
Merchant Checkout
Pay AuthorizationSession
Pay Payment Summary
Merchant Order Projection

{
  "purchaseRequestId": "purchase-123",
  "status": "COMPLETED",
  "checkoutStatus": "completed",
  "approvalStatus": "APPROVED",
  "paymentStatus": "SUCCESS",
  "order": {
    "merchantId": "merchant-a",
    "externalOrderId": "merchant-order-999"
  },
  "amount": {
    "value": 87000,
    "currency": "KRW"
  },
  "nextAction": "VIEW_ORDER"
}

JCS_Canonicalize(checkoutWithoutSecurityExtension)

Algorithm: ES256
Format: Detached JWS
Key Discovery: Merchant UCP Profile의 keys[]

{
  "id": "checkout-123",
  "status": "ready_for_complete",
  "currency": "KRW",
  "line_items": [
    {
      "id": "line-1",
      "item": {
        "id": "shoe-123",
        "title": "러닝화 A",
        "price": 89000
      },
      "quantity": 1
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 89000},
    {"type": "discount", "amount": -5000},
    {"type": "fulfillment", "amount": 3000},
    {"type": "total", "amount": 87000}
  ],
  "expires_at": "2026-09-02T17:05:00+09:00"
}

checkoutDigest = base64url(SHA-256(JCS_Canonicalize(fullCheckout)))

{
  "typ": "com.example.mandate.checkout.v1",
  "iss": "https://platform.example/.well-known/ucp",
  "aud": "merchant-a",
  "sub": "user-opaque-ref",
  "purchase_request_id": "purchase-123",
  "business_checkout_id": "checkout-123",
  "checkout_digest": "sha256:...",
  "checkout": {
    "id": "checkout-123",
    "merchant_authorization": "<detached-jws>",
    "total": 87000,
    "currency": "KRW"
  },
  "iat": 1788336060,
  "exp": 1788336300,
  "jti": "checkout-mandate-123"
}

{
  "typ": "com.example.mandate.payment.v1",
  "iss": "https://platform.example/.well-known/ucp",
  "aud": "https://pay.example",
  "transaction_id": "sha256:...",
  "payee": {
    "id": "merchant-a",
    "name": "ABC Shop"
  },
  "payment_amount": {
    "currency": "KRW",
    "amount": 87000
  },
  "payment_instrument": {
    "type": "card",
    "reference": "payment-method-ref-123",
    "display": "VISA •••• 1234"
  },
  "purchase_request_id": "purchase-123",
  "business_checkout_id": "checkout-123",
  "iat": 1788336060,
  "exp": 1788336300,
  "jti": "payment-mandate-123"
}

{
  "iss": "https://pay.example",
  "aud": "merchant-a",
  "jti": "credential-123",
  "purchase_request_id": "purchase-123",
  "business_checkout_id": "checkout-123",
  "checkout_digest": "sha256:...",
  "amount": 87000,
  "currency": "KRW",
  "payment_mandate": "<signed-payment-mandate-like>",
  "nbf": 1788336060,
  "exp": 1788336300
}

카드번호
CVC
PIN
생체정보
상세 주소
PG 장기 Token 원문

{
  "receiptId": "authorization-receipt-123",
  "authorizationSessionId": "auth-123",
  "checkoutDigest": "sha256:...",
  "status": "APPROVED",
  "authorizedAt": "2026-09-02T17:01:00+09:00",
  "authMethod": "BIOMETRIC",
  "signature": "<pay-signature>"
}

{
  "receiptId": "payment-receipt-123",
  "paymentId": "payment-123",
  "paymentMandateId": "payment-mandate-123",
  "merchantId": "merchant-a",
  "businessCheckoutId": "checkout-123",
  "amount": 87000,
  "currency": "KRW",
  "status": "SUCCESS",
  "processorTransactionId": "pg-777",
  "createdAt": "2026-09-02T17:01:05+09:00",
  "signature": "<pay-signature>"
}

외부 /internal/** 라우팅
Nginx에서 비즈니스 상태 판단
Nginx 로그에 Authorization/Credential Body 원문 저장
Merchant가 넘긴 Host를 동적으로 proxy_pass에 사용

UCP Merchant 직접 호출
Pay Service 직접 호출
상품·Cart·Checkout 상태 저장
가격·재고·배송비 계산
Payment Credential 취득·보관
사용자 결제 승인
PG 호출

mcp-server/
└── src/main/java/com/project/mcp/
    ├── auth/
    │   ├── AgentTokenVerifier.java
    │   ├── ScopeAuthorizer.java
    │   └── AgentPrincipal.java
    ├── tool/
    │   ├── catalog/
    │   ├── cart/
    │   ├── checkout/
    │   └── purchase/
    ├── client/
    │   └── CoreInternalClient.java
    ├── mapper/
    ├── error/
    ├── observability/
    └── config/

{
  "errorCode": "CHECKOUT_PRICE_CHANGED",
  "message": "판매자가 최종 가격을 변경했습니다. 새 금액을 확인해 주세요.",
  "currentState": "RECONFIRMATION_REQUIRED",
  "nextAction": "REVIEW_CHECKOUT",
  "retryable": false,
  "traceId": "trace-123"
}

상품·재고 원본 소유
Merchant 가격 임의 계산
카드·CVC·PIN·생체정보 저장
결제 승인
Payment Credential 장기 보관
PG 직접 호출
결제 성공만 보고 로컬 원본 Order 생성
Agent가 전달한 임의 URL 호출

core-service/
└── src/main/java/com/project/core/
    ├── identity/
    │   ├── user/
    │   ├── login/
    │   └── token/
    ├── agentauth/
    │   ├── client/
    │   ├── connection/
    │   ├── authorization/
    │   └── token/
    ├── address/
    ├── platformprofile/
    │   ├── PlatformProfileController.java
    │   ├── PlatformProfileService.java
    │   └── PlatformKeyProvider.java
    ├── merchantregistry/
    │   ├── MerchantRegistration.java
    │   ├── MerchantEndpointPolicy.java
    │   ├── MerchantAuthConfig.java
    │   └── MerchantRegistryService.java
    ├── ucp/
    │   ├── discovery/
    │   │   ├── BusinessProfileClient.java
    │   │   ├── BusinessProfileValidator.java
    │   │   └── ProfileCache.java
    │   ├── negotiation/
    │   │   ├── ProtocolVersionNegotiator.java
    │   │   ├── CapabilityNegotiator.java
    │   │   └── PaymentHandlerSelector.java
    │   ├── catalog/
    │   │   ├── UcpCatalogClient.java
    │   │   ├── ProductReference.java
    │   │   └── ProductProjectionMapper.java
    │   ├── cart/
    │   │   ├── UcpCartClient.java
    │   │   ├── CartProjection.java
    │   │   └── CartRevisionPolicy.java
    │   ├── checkout/
    │   │   ├── UcpCheckoutClient.java
    │   │   ├── CheckoutProjection.java
    │   │   ├── VerifiedCheckoutEvidence.java
    │   │   └── CheckoutStateMapper.java
    │   ├── order/
    │   │   ├── UcpOrderClient.java
    │   │   ├── OrderProjection.java
    │   │   └── OrderWebhookHandler.java
    │   └── security/
    │       ├── MerchantAuthorizationVerifier.java
    │       ├── UcpHttpSignatureVerifier.java
    │       ├── WebhookSignatureVerifier.java
    │       └── CanonicalJsonService.java
    ├── purchase/
    │   ├── domain/
    │   │   ├── PurchaseRequest.java
    │   │   ├── PurchaseStatus.java
    │   │   └── CompletionAttempt.java
    │   ├── application/
    │   │   ├── PrepareCheckoutService.java
    │   │   ├── RequestApprovalService.java
    │   │   ├── CompleteCheckoutService.java
    │   │   └── GetPurchaseStatusService.java
    │   └── scheduler/
    │       └── CompletionReconciliationJob.java
    ├── integration/pay/
    │   ├── PayAuthorizationClient.java
    │   └── PayArtifactClient.java
    ├── notification/
    ├── realtime/
    ├── outbox/
    ├── inbox/
    ├── audit/
    └── observability/

상품 검색
Merchant Cart 수정
배송비 계산
Merchant Checkout 생성·Update
Merchant Order 생성
Agent OAuth 관리
MCP Tool 제공

pay-service/
└── src/main/java/com/project/pay/
    ├── paymentmethod/
    │   ├── PaymentMethod.java
    │   ├── PaymentMethodToken.java
    │   └── PaymentMethodService.java
    ├── credential/
    │   ├── PinCredential.java
    │   ├── BiometricCredential.java
    │   ├── CredentialVerifier.java
    │   └── DeviceChallengeService.java
    ├── merchant/
    │   ├── MerchantAccount.java
    │   ├── MerchantAuthenticator.java
    │   └── MerchantHandlerConfiguration.java
    ├── authorization/
    │   ├── AuthorizationSession.java
    │   ├── AuthorizationStatus.java
    │   ├── AuthorizationSessionService.java
    │   └── AuthorizationExpiryJob.java
    ├── trustedsurface/
    │   ├── ApprovalViewAssembler.java
    │   └── CheckoutEvidenceVerifier.java
    ├── mandate/
    │   ├── CheckoutMandate.java
    │   ├── PaymentMandate.java
    │   ├── MandateSigner.java
    │   └── MandateVerifier.java
    ├── token/
    │   ├── PaymentCredentialToken.java
    │   ├── PaymentTokenIssuer.java
    │   ├── PaymentTokenVerifier.java
    │   └── TokenConsumptionPolicy.java
    ├── payment/
    │   ├── Payment.java
    │   ├── PaymentAttempt.java
    │   ├── PaymentService.java
    │   └── PaymentStateMachine.java
    ├── processor/
    │   ├── PaymentProcessor.java
    │   ├── PgPaymentProcessor.java
    │   └── PgMockPaymentProcessor.java
    ├── reconciliation/
    │   └── PaymentReconciliationJob.java
    ├── receipt/
    │   └── PaymentReceipt.java
    ├── idempotency/
    ├── outbox/
    ├── inbox/
    ├── audit/
    └── observability/

1. App API
   사용자 카드·PIN·생체·승인 대기 목록·승인·거부

2. Core Internal API
   AuthorizationSession 생성·상태 조회·Artifact 조회·무효화

3. Merchant Processor API
   외부 Merchant가 Credential로 결제 요청·상태 조회

ucp-merchant-mock/
├── profile/
├── catalog/
├── inventory/
├── cart/
├── checkout/
├── security/
├── paymenthandler/
├── order/
├── fulfillment/
├── webhook/
├── idempotency/
└── scenario/

NORMAL
PRICE_CHANGED
OUT_OF_STOCK
ADDRESS_NOT_SERVICEABLE
REQUIRES_ESCALATION
INVALID_MERCHANT_SIGNATURE
COMPLETE_TIMEOUT_BEFORE_PROCESS
COMPLETE_TIMEOUT_AFTER_ORDER
WEBHOOK_DUPLICATE
WEBHOOK_DELAYED

SUCCESS
FAILED
TIMEOUT_BEFORE_PROCESS
TIMEOUT_AFTER_PROCESS
UNKNOWN_THEN_SUCCESS
UNKNOWN_THEN_FAILED
DELAYED_SUCCESS

GET https://platform.example/.well-known/ucp

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-08-25",
          "transport": "rest",
          "endpoint": "https://platform.example/ucp/v1",
          "spec": "https://ucp.dev/2026-08-25/specification/overview",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.catalog.lookup": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.cart": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.checkout": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.order": [
        {
          "version": "2026-08-25",
          "config": {
            "webhook_url": "https://platform.example/webhooks/ucp/orders"
          }
        }
      ],
      "com.example.payment.ap2_like": [
        {
          "version": "2026-09-02",
          "spec": "https://pay.example/spec/ap2-like",
          "schema": "https://pay.example/schemas/ap2-like.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.pay": [
        {
          "id": "example_pay_platform_v1",
          "version": "2026-09-02",
          "spec": "https://pay.example/spec/payment-handler",
          "schema": "https://pay.example/schemas/payment-handler.json",
          "available_instruments": [
            {"type": "card"}
          ]
        }
      ]
    }
  },
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "use": "sig",
      "kid": "platform-signing-2026-09",
      "x": "...",
      "y": "..."
    }
  ]
}

GET https://merchant.example/.well-known/ucp

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-08-25",
          "transport": "rest",
          "endpoint": "https://merchant.example/ucp/v1",
          "spec": "https://ucp.dev/2026-08-25/specification/overview",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.catalog.search": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.catalog.lookup": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.cart": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.checkout": [
        {"version": "2026-08-25"}
      ],
      "dev.ucp.shopping.order": [
        {"version": "2026-08-25"}
      ],
      "com.example.payment.ap2_like": [
        {
          "version": "2026-09-02",
          "spec": "https://pay.example/spec/ap2-like",
          "schema": "https://pay.example/schemas/ap2-like.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.pay": [
        {
          "id": "example_pay_merchant_a",
          "version": "2026-09-02",
          "spec": "https://pay.example/spec/payment-handler",
          "schema": "https://pay.example/schemas/payment-handler.json",
          "available_instruments": [
            {"type": "card"}
          ],
          "config": {
            "merchant_id": "merchant-a",
            "processor_endpoint": "https://pay.example/merchant/v1/payments"
          }
        }
      ]
    }
  },
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "use": "sig",
      "kid": "merchant-a-signing-2026-09",
      "x": "...",
      "y": "..."
    }
  ]
}

HTTPS인가?
Redirect가 없는가?
Host가 Merchant Registry의 허용 Origin인가?
문서 크기가 제한 이내인가?
ucp.version이 날짜 버전인가?
REST Endpoint가 HTTPS인가?
Capability Namespace와 Schema Host의 Authority Binding이 유효한가?
Payment Handler Namespace와 Schema Host가 일치하는가?
keys[]의 kid가 중복되지 않는가?
지원하지 않는 필드는 tolerant reader 원칙으로 무시 가능한가?

Public App API
MCP Tool
Internal Service API
External Merchant/Protocol API

Authorization: Bearer <service-jwt>
X-End-User-Id: user-123
X-Agent-Connection-Id: connection-123
X-Trace-Id: trace-123

{
  "purchaseRequestId": "purchase-123",
  "userId": "user-123",
  "merchant": {
    "merchantId": "merchant-a",
    "displayName": "ABC Shop",
    "profileUrl": "https://merchant.example/.well-known/ucp"
  },
  "checkoutEvidence": {
    "businessCheckoutId": "checkout-123",
    "checkoutDigest": "sha256:...",
    "canonicalCheckout": {},
    "merchantAuthorization": "<detached-jws>",
    "total": {
      "amount": 87000,
      "currency": "KRW"
    },
    "expiresAt": "2026-09-02T17:05:00+09:00"
  },
  "paymentHandler": {
    "name": "com.example.pay",
    "handlerId": "example_pay_merchant_a"
  }
}

Authorization: Bearer <merchant-client-token>
Idempotency-Key: merchant-checkout-checkout-123
X-Request-Id: req-123

POST /webhooks/ucp/orders
UCP-Agent: profile="https://merchant.example/.well-known/ucp"
Signature-Input: ...
Signature: ...
Content-Digest: ...
Webhook-Id: webhook-123

core_db / core_user
pay_db / pay_user
merchant_db / merchant_user

users
refresh_tokens
login_failure_attempts

agent_clients
agent_connections
agent_authorization_codes
agent_refresh_tokens

addresses

merchant_registrations
merchant_auth_configs
merchant_profile_cache
negotiated_capability_snapshots

product_references
product_projection_cache

commerce_sessions
ucp_cart_projections
ucp_checkout_projections
verified_checkout_evidence

purchase_requests
completion_attempts

ucp_order_projections
ucp_order_snapshots

webhook_inbox
core_outbox_events
core_inbox_events
user_events
core_audit_events

id
merchant_id
name
display_name
profile_url
allowed_origin
status
authentication_type
auth_secret_reference
created_at
updated_at

UNIQUE(merchant_id)
UNIQUE(profile_url)
UNIQUE(allowed_origin)

id
merchant_id
profile_url
ucp_version
raw_profile_json
etag
cache_control
fetched_at
expires_at
validation_status
profile_hash

id
merchant_id
platform_profile_hash
business_profile_hash
ucp_version
service_binding_json
capability_intersection_json
payment_handler_intersection_json
negotiated_at
expires_at

id
merchant_id
external_product_id
canonical_ref
created_at

UNIQUE(merchant_id, external_product_id)

id
user_id
merchant_id
external_cart_id
platform_revision
ucp_status
raw_cart_json
normalized_summary_json
expires_at
last_synced_at
created_at
updated_at

UNIQUE(user_id, merchant_id, external_cart_id)

id
user_id
merchant_id
external_checkout_id
external_cart_id
ucp_status
amount
currency
raw_checkout_json
merchant_authorization
expires_at
last_synced_at
created_at
updated_at

id
merchant_id
external_checkout_id
ucp_version
raw_checkout_json
canonical_checkout_json
merchant_authorization
merchant_key_id
signature_algorithm
signature_verified
checkout_digest
amount
currency
verified_at
expires_at
created_at

UNIQUE(merchant_id, external_checkout_id, checkout_digest)

id
user_id
merchant_id
external_checkout_id
checkout_evidence_id
authorization_session_id
status
completion_idempotency_key
external_order_id
last_error_code
last_error_payload
created_at
updated_at
version

UNIQUE(merchant_id, external_checkout_id, checkout_evidence_id)
UNIQUE(completion_idempotency_key)

id
purchase_request_id
request_id
idempotency_key
request_hash
status
merchant_http_status
response_hash
started_at
completed_at
last_error

id
user_id
merchant_id
external_order_id
external_checkout_id
purchase_request_id
status
permalink_url
amount
currency
raw_order_json
last_verified_at
created_at
updated_at

UNIQUE(merchant_id, external_order_id)
UNIQUE(purchase_request_id)

id
merchant_id
webhook_id
event_type
payload_hash
status
received_at
processed_at
last_error

UNIQUE(merchant_id, webhook_id)

payment_pin_credentials
pin_failure_attempts
biometric_credentials
biometric_challenges

payment_methods
payment_method_tokens

merchant_accounts
merchant_handler_configs
merchant_api_credentials

authorization_sessions
pay_verified_checkout_evidence
authorization_receipts

checkout_mandates
payment_mandates
payment_credential_tokens

payments
payment_attempts
pg_transactions
payment_receipts
payment_reconciliation_jobs

idempotency_records
pay_outbox_events
pay_inbox_events
pay_audit_events

id
user_id
provider
provider_token_reference
brand
last4
expiry_month
expiry_year
status
is_default
created_at
updated_at
deleted_at

id
purchase_request_id
user_id
merchant_id
external_checkout_id
checkout_digest
amount
currency
selected_payment_method_id
status
required_action
expires_at
approved_at
rejected_at
invalidated_at
auth_method
created_at
updated_at
version

UNIQUE(purchase_request_id)
UNIQUE(merchant_id, external_checkout_id, checkout_digest)

id
authorization_session_id
jti
issuer
audience
checkout_digest
signed_artifact_encrypted
artifact_hash
issued_at
expires_at
status

id
authorization_session_id
jti
transaction_id
merchant_id
external_checkout_id
amount
currency
payment_method_ref
signed_artifact_encrypted
artifact_hash
issued_at
expires_at
status

id
authorization_session_id
checkout_mandate_id
payment_mandate_id
token_hash
token_ciphertext
merchant_id
external_checkout_id
checkout_digest
amount
currency
status
issued_at
expires_at
consumed_at
consumed_by_payment_id

ISSUED
CONSUMED
EXPIRED
REVOKED

id
merchant_id
external_checkout_id
purchase_request_id
credential_token_id
amount
currency
status
processor_transaction_id
idempotency_key
request_hash
created_at
updated_at
version

UNIQUE(merchant_id, idempotency_key)
UNIQUE(credential_token_id)

id
payment_id
attempt_no
operation
request_hash
pg_request_id
status
started_at
completed_at
error_code

products
product_options
inventory

carts
cart_items

checkout_sessions
checkout_line_items
checkout_totals
checkout_idempotency_records

orders
order_items
fulfillment_events

merchant_keys
platform_registrations
webhook_deliveries
merchant_audit_events

Profile Cache 보조
짧은 TTL Challenge
Rate Limit Counter
SSE Connection Registry
분산 Lock이 꼭 필요한 짧은 구간

PurchaseRequest
AuthorizationSession
Payment
Credential 소비 상태
Order Projection
Idempotency 결과

사용자는 승인했지만 Merchant Complete가 아직 호출되지 않음
Merchant가 Pay를 호출했지만 PG 결과가 UNKNOWN
Pay는 성공했지만 Merchant Complete 응답이 Core에 도착하지 않음
Merchant는 Order를 만들었지만 Webhook이 지연됨

Core DB
Pay DB
Merchant DB
PG

UNIQUE(agent_connection_id, idempotency_key)

Idempotency-Key: authorization-{purchaseRequestId}

UNIQUE(purchase_request_id)
UNIQUE(service_client_id, idempotency_key)

Cart Create      cart-create-{commerceSessionId}
Cart Update      cart-update-{externalCartId}-{platformRevision}
Checkout Create  checkout-create-{purchaseDraftId}
Checkout Update  checkout-update-{checkoutId}-{evidenceRevision}
Checkout Complete checkout-complete-{purchaseRequestId}
Checkout Cancel  checkout-cancel-{checkoutId}

UNIQUE(merchant_id, idempotency_key)
UNIQUE(credential_token_id)

UPDATE authorization_sessions
SET status = 'APPROVED',
    approved_at = NOW(),
    version = version + 1
WHERE id = :authorizationId
  AND user_id = :userId
  AND status = 'PENDING'
  AND expires_at > NOW();

UPDATE ucp_cart_projections
SET platform_revision = platform_revision + 1,
    updated_at = NOW()
WHERE id = :cartProjectionId
  AND platform_revision = :expectedRevision;

상품
옵션
수량
가격
할인
배송비
세금
배송지
통화
Merchant

PurchaseRequest = COMPLETION_UNKNOWN

새 PurchaseRequest 생성
새 승인 세션 생성
새 Credential 발급
새 Idempotency-Key로 Complete 호출

Payment = UNKNOWN
Reconciliation Job 생성

Payment SUCCESS 저장
Payment Receipt 저장
pay_outbox_events 저장
COMMIT

core_inbox_events에 eventId 저장
중복이면 기존 처리 결과 반환
PurchaseRequest Projection 갱신
user_events 저장
COMMIT

{
  "sub": "user-123",
  "client_id": "external-agent-1",
  "client_type": "AGENT",
  "aud": ["mcp-server"],
  "scope": [
    "product:read",
    "cart:read",
    "cart:write",
    "checkout:prepare",
    "purchase:request",
    "purchase:status"
  ],
  "connection_id": "connection-123",
  "exp": 1788340000
}

{
  "sub": "user-123",
  "client_type": "MOBILE_APP",
  "aud": ["core-api", "pay-api"],
  "scope": [
    "address:manage",
    "payment-method:manage",
    "payment-approval:read",
    "payment-approval:approve",
    "payment-approval:reject"
  ],
  "exp": 1788340000
}

kid 필수
활성 Key와 검증 전용 이전 Key 동시 공개
Private Key를 애플리케이션 설정 파일에 저장 금지
정기 Rotation
폐기 시점 전 발급 Artifact 검증 기간 고려

짧은 TTL
1회 사용
authorizationSessionId와 결합
userId·deviceId와 결합
재사용 시 거절

카드번호
CVC
PIN
생체 서명 전체
Payment Credential 원문
Mandate 원문 전체
Refresh Token 원문
상세 배송지 전체
PG 장기 Token

traceId
requestId
userId 또는 해시
merchantId
externalCheckoutId
purchaseRequestId
authorizationSessionId
paymentId
externalOrderId
credential jti 또는 Hash 일부
카드 brand/last4
상태 전이
오류 코드

authorization.created
authorization.approved
authorization.rejected
authorization.expired
authorization.invalidated
payment.processing
payment.succeeded
payment.failed
payment.unknown
payment.reconciled

checkout.prepared
checkout.reconfirmation_required
purchase.approval_required
purchase.submitting
purchase.completed
purchase.failed
purchase.completion_unknown
order.updated

order.created
order.updated
fulfillment.updated
adjustment.created

GET /api/v1/events
Last-Event-ID: event-123

user_events
- event_id
- user_id
- event_type
- resource_type
- resource_id
- payload
- created_at
- expires_at

{
  "errorCode": "...",
  "message": "...",
  "currentState": "...",
  "nextAction": "...",
  "retryable": false,
  "traceId": "..."
}

backend/
├── settings.gradle
├── build.gradle
├── gradle/
│   └── libs.versions.toml
│
├── apps/
│   ├── core-service/
│   ├── mcp-server/
│   └── pay-service/
│
├── mocks/
│   ├── ucp-merchant-mock/
│   └── pg-mock/
│
├── libs/
│   ├── ucp-contract/
│   ├── payment-handler-contract/
│   ├── internal-api-contract/
│   ├── event-contract/
│   ├── security-support/
│   ├── observability/
│   └── test-support/
│
├── infra/
│   ├── nginx/
│   ├── docker/
│   ├── monitoring/
│   ├── migrations/
│   └── ci/
│
└── docs/
    ├── adr/
    ├── openapi/
    ├── mcp/
    ├── ucp-profile/
    ├── payment-handler/
    ├── event-schema/
    ├── sequence/
    └── threat-model/

생성된 API Client/DTO
UCP Schema Validation 도구
공통 오류 Envelope
Service JWT 검증
HTTP Signature 유틸리티
JCS Canonicalization 유틸리티
Trace ID·Observability
테스트 Fixture

JPA Entity
Repository
Core Purchase Domain
Pay Payment Domain
Merchant Checkout Domain
상태 전이 로직
DB 접근 코드

nginx
mcp-server
core-service
pay-service
ucp-merchant-mock
pg-mock
core-db
pay-db
merchant-db
redis
prometheus
grafana

/actuator/health/liveness
/actuator/health/readiness

Core: Core DB, Redis 선택, Pay 연결 가능 여부는 Degraded 표현
Pay: Pay DB, PG 연결 상태
Merchant Mock: Merchant DB, Pay Handler 연결 상태
MCP: Core 연결 상태

traceId
requestId
userId 또는 userHash
agentConnectionId
merchantId
externalCartId
externalCheckoutId
checkoutDigest
purchaseRequestId
authorizationSessionId
paymentId
externalOrderId
webhookId
idempotencyKeyHash

mcp_tool_calls_total{tool,status}
mcp_tool_latency_seconds{tool}
mcp_scope_denied_total

ucp_profile_fetch_total{merchant,status}
ucp_request_latency_seconds{merchant,operation}
ucp_capability_negotiation_failed_total
checkout_status_total{status}
merchant_authorization_failed_total
purchase_request_total{status}
completion_unknown_total
order_webhook_lag_seconds

authorization_total{status,method}
authorization_failure_total{reason}
credential_issued_total
credential_replay_blocked_total
payment_total{status,merchant}
payment_unknown_total
payment_reconciliation_latency_seconds
pg_request_latency_seconds{operation}

Agent 연결·해제
Merchant Profile 변경
Capability 협상 결과
Cart 변경
Checkout 생성·Update
Merchant Authorization 검증
PurchaseRequest 생성
승인·거부·만료·무효화
Mandate·Credential 발급·폐기·소비
Payment 상태 변경
Reconciliation
Order Webhook 처리
운영자 수동 상태 확정

Unit Test
Contract Test
Integration Test
Concurrency Test
Security Test
End-to-End Test
Failure-Recovery Test

등록되지 않은 Merchant 차단
악성 Profile URL 차단
Profile Cache 만료·갱신
Version 불일치
필수 Capability 미지원
Catalog 결과 정규화
상품 ID 충돌 방지
Cart Revision 충돌
Checkout incomplete 보완
requires_escalation 처리
Merchant 서명 정상·실패
Checkout Digest 재현성
가격 변경 후 승인 무효화
같은 승인 요청 멱등 처리
Complete 응답 유실 후 조회 복구
Order Webhook 중복 제거
Order Webhook 지연 후 Polling

Profile Discovery
Payment Handler 광고
Custom AP2-like Capability 광고
Checkout 조건 서명
잘못된 Mandate 거절
현재 Checkout과 Mandate 조건 비교
Pay 성공 전 Order 생성 금지
Pay 성공 후 Order 한 번 생성
Complete 중복 호출에 기존 Order 반환
Order Webhook 서명·중복 전송

Human Not Present 자율 구매
Open Checkout Mandate
Open Payment Mandate
Agent Key 위임과 Mandate Chain
공식 SD-JWT+KB 상호운용 구현
공식 AP2 적합성 주장
다중 Merchant 합산 Cart
분할 결제와 부분 성공
다중 통화와 환율
할부
3DS 정식 연동
실제 카드번호·CVC 저장
부분취소·부분환불
반품·교환
판매자 정산
Chargeback 자동화
구독·반복 결제
프로모션 엔진 전체 구현
택배사 실연동

apps/core-service/
├── platformprofile/**
├── merchantregistry/**
├── ucp/discovery/**
├── ucp/negotiation/**
├── ucp/catalog/**
├── ucp/cart/**
├── ucp/checkout/**
├── ucp/order/**
├── ucp/security/**
├── purchase/**
└── integration/pay/**

mocks/ucp-merchant-mock/
├── profile/**
├── catalog/**
├── inventory/**
├── cart/**
├── checkout/**
├── order/**
└── webhook/**

apps/mcp-server/**

apps/core-service/
├── identity/**
├── agentauth/**
├── address/**
├── realtime/**
├── notification/**
└── publicapi/**

apps/pay-service/
├── paymentmethod/**
├── credential/**
├── authorization/**
├── trustedsurface/**
├── mandate/**
└── token/**

apps/pay-service/
├── merchant/**
├── payment/**
├── processor/**
├── reconciliation/**
├── receipt/**
├── idempotency/**
├── outbox/**
├── inbox/**
└── audit/**

mocks/pg-mock/**

mocks/ucp-merchant-mock/
└── paymenthandler/**

infra/
├── nginx/**
├── docker-compose.yml
├── ci/**
└── monitoring/**

libs/ucp-contract/**
libs/pay-handler-contract/**
libs/event-contract/**
docs/openapi/**
docs/mcp/**
docs/ucp-profile/**
docs/adr/**

A — UCP / Commerce Core
외부 Merchant 방향의 수직 흐름 소유

B — MCP / Agent Platform
외부 Agent·사용자 방향의 수직 흐름 소유

B는 "Agent가 무엇을 요청했는가"를 책임지고,
A는 "외부 Merchant와 그 요청을 어떻게 안전하게 완료하는가"를 책임진다.

C — Authorization / Credential
사용자가 정확히 무엇을 승인했으며 어떤 권한 증거를 발급할 수 있는가

D — Processor / Reliability
승인된 Credential로 결제를 한 번만 실행하고 결과를 어떻게 확정하는가

com.example.pay
com.example.payment.ap2_like
https://platform.example/.well-known/ucp
https://merchant.example/.well-known/ucp

prepare_order
  → 내부적으로 prepare_checkout 실행

request_payment
  → 내부적으로 request_purchase_approval 실행

get_payment_request_status
  → 내부적으로 get_purchase_status 실행

traceId
requestId
userId
agentConnectionId
merchantId
externalCartId
businessCheckoutId
purchaseRequestId
authorizationSessionId
checkoutMandateId
paymentMandateId
paymentId
externalOrderId
webhookId

"Timeout이 났지만 다시 결제하지 않았고,
같은 Payment와 Checkout을 조회해 성공을 확정했다."