contract -> generated interfaces/models -> implementation -> contract tests -> runtime validation

implementation -> guessed documentation -> broken merchant integration

Author canonical contract in OpenAPI 3.1.1.
Validate tooling compatibility.
If a generator requires 3.0.x, generate a downgraded artifact from canonical spec, not hand-maintain two specs.

payment-api-contracts/
  openapi/
    public-v1.yaml
    internal-v1.yaml
    provider-webhook-v1.yaml
    merchant-webhook-v1.yaml
  components/
    schemas/
      money.yaml
      errors.yaml
      payment-intent.yaml
      payment-attempt.yaml
      refund.yaml
      next-action.yaml
      pagination.yaml
    parameters/
      idempotency-key.yaml
      request-id.yaml
      pagination.yaml
    responses/
      errors.yaml
  examples/
    payment-intent-create-request.json
    payment-intent-succeeded-response.json
    refund-processing-response.json
  rules/
    spectral.yaml
  compatibility/
    breaking-change-policy.md

openapi: 3.1.1
info:
  title: Payment Platform Public API
  version: 1.0.0
  description: Public merchant-facing payment API for payment intent, capture, cancellation, refund, and event retrieval.
servers:
  - url: https://api.payment.example.com/v1
    description: Production
  - url: https://sandbox-api.payment.example.com/v1
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: PaymentIntents
  - name: Refunds
  - name: Events
paths:
  /payment-intents:
    post:
      tags: [PaymentIntents]
      operationId: createPaymentIntent
      summary: Create a payment intent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntent'
        '400':
          $ref: '#/components/responses/InvalidRequestError'
        '409':
          $ref: '#/components/responses/ConflictError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 255
      description: Required for commands that may create or change financial effects.

Money:
  type: object
  required:
    - currency
    - valueMinor
  additionalProperties: false
  properties:
    currency:
      type: string
      minLength: 3
      maxLength: 3
      pattern: '^[A-Z]{3}$'
      description: ISO 4217 currency code.
      examples: [IDR, USD, EUR]
    valueMinor:
      type: integer
      format: int64
      minimum: 0
      description: Amount in the currency minor unit. For IDR this is the amount without decimal fraction.
  examples:
    - currency: IDR
      valueMinor: 15000000

PaymentIntent:
  type: object
  required:
    - id
    - object
    - status
    - amount
    - amountCapturable
    - amountReceived
    - captureMethod
    - createdAt
    - updatedAt
  additionalProperties: false
  properties:
    id:
      type: string
      pattern: '^pi_[A-Za-z0-9]+$'
    object:
      type: string
      const: payment_intent
    status:
      $ref: '#/components/schemas/PaymentIntentStatus'
    amount:
      $ref: '#/components/schemas/Money'
    amountCapturable:
      $ref: '#/components/schemas/Money'
    amountReceived:
      $ref: '#/components/schemas/Money'
    captureMethod:
      $ref: '#/components/schemas/CaptureMethod'
    latestAttempt:
      anyOf:
        - $ref: '#/components/schemas/PaymentAttemptSummary'
        - type: 'null'
    nextAction:
      anyOf:
        - $ref: '#/components/schemas/NextAction'
        - type: 'null'
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time

PaymentIntentStatus:
  type: string
  enum:
    - REQUIRES_PAYMENT_METHOD
    - REQUIRES_CONFIRMATION
    - REQUIRES_ACTION
    - PROCESSING
    - AUTHORIZED
    - PARTIALLY_CAPTURED
    - CAPTURED
    - SUCCEEDED
    - CANCELED
    - FAILED
    - EXPIRED
    - UNKNOWN

Server may add new enum values in a minor version only if client SDKs and docs define unknown enum handling.

public final class PaymentIntentStatusValue {
    private final String value;

    public boolean isKnown() {
        return known().contains(value);
    }

    public Optional<KnownPaymentIntentStatus> asKnown() {
        return KnownPaymentIntentStatus.from(value);
    }
}

CreatePaymentIntentRequest:
  type: object
  required:
    - merchantId
    - referenceType
    - referenceId
    - amount
    - captureMethod
    - allowedPaymentMethods
  additionalProperties: false
  properties:
    merchantId:
      type: string
      pattern: '^mrc_[A-Za-z0-9]+$'
    referenceType:
      type: string
      enum: [ORDER, INVOICE, SUBSCRIPTION, CUSTOM]
    referenceId:
      type: string
      minLength: 1
      maxLength: 128
    amount:
      $ref: '#/components/schemas/Money'
    captureMethod:
      $ref: '#/components/schemas/CaptureMethod'
    allowedPaymentMethods:
      type: array
      minItems: 1
      uniqueItems: true
      items:
        $ref: '#/components/schemas/PaymentMethodType'
    expiresAt:
      type: string
      format: date-time
    metadata:
      $ref: '#/components/schemas/Metadata'

Metadata:
  type: object
  additionalProperties:
    type: string
    maxLength: 500
  maxProperties: 50
  description: Merchant-defined key-value data. Do not store PAN, CVV, password, government identifiers, or sensitive authentication data.

pan
card_number
cvv
password
pin
otp
secret
private_key
nik
ssn

NextAction:
  oneOf:
    - $ref: '#/components/schemas/RedirectNextAction'
    - $ref: '#/components/schemas/DisplayQrCodeNextAction'
    - $ref: '#/components/schemas/DisplayBankTransferInstructionNextAction'
  discriminator:
    propertyName: type
    mapping:
      REDIRECT: '#/components/schemas/RedirectNextAction'
      DISPLAY_QR_CODE: '#/components/schemas/DisplayQrCodeNextAction'
      DISPLAY_BANK_TRANSFER_INSTRUCTION: '#/components/schemas/DisplayBankTransferInstructionNextAction'

RedirectNextAction:
  type: object
  required: [type, redirectUrl]
  additionalProperties: false
  properties:
    type:
      type: string
      const: REDIRECT
    redirectUrl:
      type: string
      format: uri

DisplayQrCodeNextAction:
  type: object
  required: [type, qr]
  additionalProperties: false
  properties:
    type:
      type: string
      const: DISPLAY_QR_CODE
    qr:
      $ref: '#/components/schemas/QrInstruction'

ErrorResponse:
  type: object
  required: [error]
  additionalProperties: false
  properties:
    error:
      $ref: '#/components/schemas/ApiError'

ApiError:
  type: object
  required:
    - type
    - code
    - message
    - requestId
  additionalProperties: false
  properties:
    type:
      $ref: '#/components/schemas/ErrorType'
    code:
      type: string
      pattern: '^[A-Z0-9_]+$'
    message:
      type: string
      maxLength: 1000
    field:
      type: [string, 'null']
    requestId:
      type: string
      pattern: '^req_[A-Za-z0-9]+$'
    paymentIntentId:
      type: [string, 'null']
    retryAfterSeconds:
      type: [integer, 'null']
      minimum: 0
    details:
      type: object
      additionalProperties: true

ErrorType:
  type: string
  enum:
    - INVALID_REQUEST
    - AUTHENTICATION_ERROR
    - AUTHORIZATION_ERROR
    - RESOURCE_NOT_FOUND
    - IDEMPOTENCY_ERROR
    - STATE_CONFLICT
    - RATE_LIMIT_ERROR
    - PROVIDER_UNAVAILABLE
    - UNKNOWN_OUTCOME
    - INTERNAL_ERROR

Error message is for humans.
Error code is for machines.
Error type is for broad handling.
HTTP status is transport semantics.
Payment resource status is financial lifecycle.

IdempotencyKey:
  name: Idempotency-Key
  in: header
  required: true
  schema:
    type: string
    minLength: 8
    maxLength: 255
    pattern: '^[A-Za-z0-9._:-]+$'
  description: |
    A unique key supplied by the client to safely retry commands.
    The same key with the same request fingerprint returns the original result.
    The same key with a different request fingerprint returns an idempotency error.

RequestId:
  name: Payment-Request-Id
  in: header
  required: false
  schema:
    type: string
    maxLength: 128
  description: Optional client-supplied correlation id. The platform always returns its own request id in response headers.

headers:
  Payment-Request-Id:
    schema:
      type: string
    description: Unique request id generated by the payment platform.

/payment-intents/{paymentIntentId}/confirm:
  post:
    tags: [PaymentIntents]
    operationId: confirmPaymentIntent
    summary: Confirm a payment intent
    parameters:
      - name: paymentIntentId
        in: path
        required: true
        schema:
          type: string
          pattern: '^pi_[A-Za-z0-9]+$'
      - $ref: '#/components/parameters/IdempotencyKey'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmPaymentIntentRequest'
    responses:
      '200':
        description: Payment intent confirmed or current idempotent result returned
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntent'
      '400':
        $ref: '#/components/responses/InvalidRequestError'
      '409':
        $ref: '#/components/responses/ConflictError'
      '503':
        $ref: '#/components/responses/ProviderUnavailableError'

ConfirmPaymentIntentRequest:
  type: object
  required:
    - paymentMethod
  additionalProperties: false
  properties:
    paymentMethod:
      $ref: '#/components/schemas/PaymentMethodInput'
    returnUrl:
      type: string
      format: uri
    clientContext:
      $ref: '#/components/schemas/ClientContext'

PaymentMethodInput:
  oneOf:
    - $ref: '#/components/schemas/CardTokenPaymentMethodInput'
    - $ref: '#/components/schemas/BankTransferPaymentMethodInput'
    - $ref: '#/components/schemas/QrisPaymentMethodInput'
  discriminator:
    propertyName: type
    mapping:
      CARD: '#/components/schemas/CardTokenPaymentMethodInput'
      BANK_TRANSFER: '#/components/schemas/BankTransferPaymentMethodInput'
      QRIS: '#/components/schemas/QrisPaymentMethodInput'

CardTokenPaymentMethodInput:
  type: object
  required: [type, token]
  additionalProperties: false
  properties:
    type:
      type: string
      const: CARD
    token:
      type: string
      pattern: '^tok_[A-Za-z0-9]+$'
    saveForFutureUse:
      type: boolean
      default: false

CapturePaymentIntentRequest:
  type: object
  required:
    - amountToCapture
    - finalCapture
  additionalProperties: false
  properties:
    amountToCapture:
      $ref: '#/components/schemas/Money'
    finalCapture:
      type: boolean
      description: Whether this capture should release any remaining uncaptured authorization amount.
    captureReference:
      type: string
      minLength: 1
      maxLength: 128

amountToCapture <= amountCapturable

CreateRefundRequest:
  type: object
  required:
    - paymentIntentId
    - amount
    - reason
  additionalProperties: false
  properties:
    paymentIntentId:
      type: string
      pattern: '^pi_[A-Za-z0-9]+$'
    amount:
      $ref: '#/components/schemas/Money'
    reason:
      $ref: '#/components/schemas/RefundReason'
    referenceId:
      type: string
      maxLength: 128
    metadata:
      $ref: '#/components/schemas/Metadata'

RefundReason:
  type: string
  enum:
    - REQUESTED_BY_CUSTOMER
    - DUPLICATE
    - FRAUDULENT
    - PRODUCT_UNAVAILABLE
    - MERCHANT_REQUESTED
    - OTHER

Refund:
  type: object
  required:
    - id
    - object
    - paymentIntentId
    - status
    - amount
    - createdAt
    - updatedAt
  additionalProperties: false
  properties:
    id:
      type: string
      pattern: '^rf_[A-Za-z0-9]+$'
    object:
      type: string
      const: refund
    paymentIntentId:
      type: string
    status:
      $ref: '#/components/schemas/RefundStatus'
    amount:
      $ref: '#/components/schemas/Money'
    failureCode:
      type: [string, 'null']
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time

CursorPage:
  type: object
  required:
    - hasMore
  additionalProperties: false
  properties:
    nextCursor:
      type: [string, 'null']
    hasMore:
      type: boolean

PaymentIntentList:
  type: object
  required: [data, page]
  additionalProperties: false
  properties:
    data:
      type: array
      items:
        $ref: '#/components/schemas/PaymentIntent'
    page:
      $ref: '#/components/schemas/CursorPage'

cur_eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTAyVDA4OjAwOjAwWiIsImlkIjoicGlfLi4uIn0

MerchantEvent:
  type: object
  required:
    - id
    - object
    - type
    - apiVersion
    - createdAt
    - data
  additionalProperties: false
  properties:
    id:
      type: string
      pattern: '^evt_[A-Za-z0-9]+$'
    object:
      type: string
      const: event
    type:
      $ref: '#/components/schemas/MerchantEventType'
    apiVersion:
      type: string
      examples: ['2026-07-02']
    createdAt:
      type: string
      format: date-time
    data:
      $ref: '#/components/schemas/MerchantEventData'

MerchantEventData:
  type: object
  required: [object]
  additionalProperties: false
  properties:
    object:
      oneOf:
        - $ref: '#/components/schemas/PaymentIntent'
        - $ref: '#/components/schemas/Refund'

MerchantEventType:
  type: string
  enum:
    - payment_intent.created
    - payment_intent.requires_action
    - payment_intent.processing
    - payment_intent.authorized
    - payment_intent.succeeded
    - payment_intent.failed
    - payment_intent.canceled
    - refund.created
    - refund.processing
    - refund.succeeded
    - refund.failed

/provider-webhooks/{providerCode}:
  post:
    tags: [ProviderWebhooks]
    operationId: ingestProviderWebhook
    summary: Ingest a provider webhook payload
    parameters:
      - name: providerCode
        in: path
        required: true
        schema:
          type: string
          pattern: '^[a-z0-9_]+$'
      - name: Payment-Provider-Signature
        in: header
        required: false
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    responses:
      '202':
        description: Webhook accepted for processing

NormalizedProviderEvent:
  type: object
  required:
    - providerCode
    - providerEventId
    - providerReference
    - eventType
    - observedAt
    - rawPayloadReference
  additionalProperties: false
  properties:
    providerCode:
      type: string
    providerEventId:
      type: string
    providerReference:
      type: string
    eventType:
      type: string
    normalizedStatus:
      type: string
    observedAt:
      type: string
      format: date-time
    rawPayloadReference:
      type: string

Generate API interfaces + DTOs.
Implement interfaces manually in resource adapter.
Map DTOs to domain commands.
Never put business logic in generated classes.

payment-api-generated/
  src/main/java/com/example/payment/api/generated/
    model/
    resource/
payment-api-server/
  src/main/java/com/example/payment/api/resource/
    PaymentIntentResourceImpl.java
    RefundResourceImpl.java
  src/main/java/com/example/payment/api/mapper/
    PaymentIntentApiMapper.java
payment-domain/
  src/main/java/com/example/payment/domain/

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>${openapi.generator.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/../contracts/openapi/public-v1.yaml</inputSpec>
        <generatorName>jaxrs-jersey</generatorName>
        <apiPackage>com.example.payment.api.generated.resource</apiPackage>
        <modelPackage>com.example.payment.api.generated.model</modelPackage>
        <generateSupportingFiles>false</generateSupportingFiles>
        <configOptions>
          <sourceFolder>src/gen/java</sourceFolder>
          <dateLibrary>java8</dateLibrary>
          <interfaceOnly>true</interfaceOnly>
          <useJakartaEe>true</useJakartaEe>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

public interface PaymentIntentsApi {
    Response createPaymentIntent(
        String idempotencyKey,
        CreatePaymentIntentRequest request
    );

    Response getPaymentIntent(String paymentIntentId);

    Response confirmPaymentIntent(
        String paymentIntentId,
        String idempotencyKey,
        ConfirmPaymentIntentRequest request
    );
}

public final class PaymentIntentsResource implements PaymentIntentsApi {
    private final PaymentIntentApplicationService service;
    private final PaymentIntentApiMapper mapper;
    private final RequestContextFactory contextFactory;

    @Override
    public Response createPaymentIntent(String idempotencyKey, CreatePaymentIntentRequest request) {
        RequestContext context = contextFactory.create(idempotencyKey);
        var command = mapper.toCreateCommand(request, context);
        var result = service.create(command);
        return Response.status(201).entity(mapper.toApi(result)).build();
    }

    @Override
    public Response confirmPaymentIntent(
        String paymentIntentId,
        String idempotencyKey,
        ConfirmPaymentIntentRequest request
    ) {
        RequestContext context = contextFactory.create(idempotencyKey);
        var command = mapper.toConfirmCommand(paymentIntentId, request, context);
        var result = service.confirm(command);
        return Response.ok(mapper.toApi(result)).build();
    }
}

{
  "amount": {
    "currency": "USD",
    "valueMinor": 1000
  }
}

{
  "error": {
    "type": "INVALID_REQUEST",
    "code": "CURRENCY_NOT_SUPPORTED_FOR_MERCHANT",
    "message": "Merchant mrc_... does not support USD payments.",
    "requestId": "req_..."
  }
}

@Test
void createPaymentIntentResponseMustMatchOpenApiSchema() {
    var response = client.createPaymentIntent(validRequest());

    assertThat(response.statusCode()).isEqualTo(201);
    openApiValidator.assertResponseMatches(
        "createPaymentIntent",
        201,
        response.body()
    );
}

rules:
  operation-operationId-required: true
  operation-tags: true
  path-params-defined: true
  no-ambiguous-payment-status:
    description: Payment status must reference PaymentIntentStatus schema.
  idempotency-required-for-financial-commands:
    description: POST commands that create financial effects must include Idempotency-Key.
  no-float-money:
    description: Money schemas must use integer valueMinor, never number/double.
  error-response-required:
    description: 4xx and 5xx responses must use ErrorResponse.
  no-additional-properties-public-response:
    description: Public response schemas must set additionalProperties false.

A technically non-breaking schema change can still be financially breaking if it changes meaning.

{
  "merchantId": "mrc_01JZ8X1A2B3C4D5E6F7G8H9J0K",
  "referenceType": "ORDER",
  "referenceId": "ord_20260702_0001",
  "amount": {
    "currency": "IDR",
    "valueMinor": 15000000
  },
  "captureMethod": "AUTOMATIC",
  "allowedPaymentMethods": ["CARD", "QRIS"]
}

example payload -> schema validation -> pass

signed_payload = timestamp + "." + raw_body
signature = HMAC_SHA256(endpoint_secret, signed_payload)

PaymentSignature:
  name: Payment-Signature
  in: header
  required: true
  schema:
    type: string
  description: HMAC signature over timestamp and raw request body.

PaymentEventId:
  name: Payment-Event-Id
  in: header
  required: true
  schema:
    type: string

public boolean verify(String header, String rawBody, String secret, Clock clock) {
    SignatureHeader parsed = SignatureHeader.parse(header);
    Instant timestamp = parsed.timestamp();

    if (Duration.between(timestamp, clock.instant()).abs().toMinutes() > 5) {
        return false;
    }

    String signedPayload = parsed.timestampEpochSeconds() + "." + rawBody;
    String expected = hmacSha256Hex(secret, signedPayload);
    return constantTimeEquals(expected, parsed.signature());
}

hypothesis -> contract proposal -> example -> review -> generated code -> implementation -> tests -> release

x-payment-sandbox-behavior:
  testCards:
    - token: tok_card_success
      result: SUCCEEDED
    - token: tok_card_requires_3ds
      result: REQUIRES_ACTION
    - token: tok_card_declined
      result: FAILED
    - token: tok_card_timeout_unknown
      result: UNKNOWN

Money.valueMinor must be integer.
Currency must be uppercase ISO 4217 code.
Financial commands require Idempotency-Key.
HTTP error response must use ErrorResponse.
Payment status must be from normalized internal lifecycle.
Provider raw status must not be exposed as primary status.
Sensitive authentication data must not appear in public payload.
Webhook events must have id, type, apiVersion, createdAt, data.object.
Retrieve endpoints must be safe and idempotent.
Command endpoints must document legal state conflict behavior.

Do not use an OpenAPI feature in public contract unless your validation, codegen, documentation, and SDK pipeline all support it correctly.

# ADR-001: Use OpenAPI 3.1.1 as Canonical Payment API Contract

## Status
Accepted

## Context
Payment APIs require stable, machine-readable, auditable contracts for merchant integration, generated Java interfaces, schema validation, and compatibility governance.

## Decision
Use OpenAPI 3.1.1 as canonical source-of-truth. Generate Java JAX-RS interfaces and DTOs from this contract. Domain model remains separate from generated DTOs.

## Consequences
- API changes require contract review.
- Generator version must be pinned.
- CI must validate examples and breaking changes.
- Some advanced JSON Schema features may be avoided if tooling support is weak.

contracts/
  public-v1.yaml
  merchant-webhook-v1.yaml
  provider-webhook-v1.yaml
  examples/
    create-payment-intent-request.json
    payment-intent-response-succeeded.json
    confirm-payment-intent-requires-action.json
    create-refund-request.json
    merchant-webhook-payment-succeeded.json

Money
Metadata
PaymentIntent
PaymentIntentStatus
PaymentAttemptSummary
PaymentMethodInput
NextAction
Refund
RefundStatus
ApiError
ErrorResponse
CursorPage
MerchantEvent

PaymentIntentsApi
RefundsApi
EventsApi
PaymentIntent model
Refund model
ErrorResponse model