openapi.delegate_payment.yaml

openapi: 3.1.0
info:
  title: Agentic Commerce — Delegate Payment API
  version: "2026-01-30"
  description: |
    Delegate a payment using a provided payment method and allowance.
servers:
  - url: https://merchant.example.com
security:
  - bearerAuth: []
tags:
  - name: DelegatePayment
    description: Create delegated payment tokens
paths:
  /agentic_commerce/delegate_payment:
    post:
      tags: [DelegatePayment]
      summary: Create a delegated payment token
      operationId: delegatePayment
      description: |
        Tokenizes a credential for controlled usage by the merchant's PSP per the **Allowance** constraints.
        Exactly one credential type is currently supported: **card**.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ContentType"
        - $ref: "#/components/parameters/AcceptLanguage"
        - $ref: "#/components/parameters/UserAgent"
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/RequestId"
        - $ref: "#/components/parameters/Signature"
        - $ref: "#/components/parameters/Timestamp"
        - $ref: "#/components/parameters/APIVersion"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DelegatePaymentRequest"
            examples:
              card_success:
                summary: Card (FPAN) — success
                value:
                  payment_method:
                    type: card
                    card_number_type: fpan
                    number: "4242424242424242"
                    exp_month: "11"
                    exp_year: "2026"
                    name: "Jane Doe"
                    cvc: "223"
                    checks_performed: ["avs", "cvv"]
                    iin: "424242"
                    display_card_funding_type: credit
                    display_brand: "visa"
                    display_last4: "4242"
                    metadata: { "issuing_bank": "temp" }
                  allowance:
                    reason: one_time
                    max_amount: 2000
                    currency: usd
                    checkout_session_id: "csn_01HV3P3..."
                    merchant_id: "acme"
                    expires_at: "2025-10-09T07:20:50.52Z"
                  billing_address:
                    name: "John Doe"
                    line_one: "123 Fake St."
                    line_two: "Unit 1"
                    city: "San Francisco"
                    state: "CA"
                    country: "US"
                    postal_code: "12345"
                  risk_signals:
                    - type: card_testing
                      score: 10
                      action: manual_review
                  metadata: { "campaign": "q4" }
      responses:
        "201":
          description: Created
          headers:
            Request-Id:
              description: Echo of the request correlation ID
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DelegatePaymentResponse"
              examples:
                created:
                  value:
                    id: "vt_01J8Z3WXYZ9ABC"
                    created: "2025-09-29T11:00:00Z"
                    metadata:
                      source: "agent_checkout"
                      merchant_id: "acme"
                      idempotency_key: "idem_abc123"
        "400":
          description: Bad Request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                invalid_request_missing_field:
                  value:
                    error:
                      type: invalid_request
                      code: invalid_card
                      message: "card field is required when payment_method.type=card"
                      param: "payment_method.number"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                unauthorized:
                  value:
                    error:
                      type: unauthorized
                      code: unauthorized
                      message: "Unauthorized"
        "409":
          description: Idempotency conflict
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                idem_conflict:
                  value:
                    error:
                      type: invalid_request
                      code: idempotency_conflict
                      message: "Same Idempotency-Key used with different parameters"
        "422":
          description: Semantic validation error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                invalid_request:
                  value:
                    error:
                      type: invalid_request
                      code: invalid_card
                      message: "Invalid card expiration month"
                      param: "payment_method.exp_month"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                rate_limit_exceeded:
                  value:
                    error:
                      type: rate_limit_exceeded
                      code: rate_limit_exceeded
                      message: "Rate limit exceeded"
        "500":
          description: Processing error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                internal_server_error:
                  value:
                    error:
                      type: internal_server_error
                      code: internal_server_error
                      message: "Internal server error"
        "503":
          description: Service unavailable
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              examples:
                service_unavailable:
                  value:
                    error:
                      type: service_unavailable
                      code: service_unavailable
                      message: "Service unavailable"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      description: 	Bearer token for API authentication (e.g., Bearer sk_live_123)
      schema:
        type: string
        example: "Bearer api_key_123"
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: "Must be application/json"
      schema:
        type: string
        example: "application/json"
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      description: "Preferred language for response messages (e.g., en-US)"
      schema:
        type: string
        example: "en-us"
    UserAgent:
      name: User-Agent
      in: header
      required: false
      description: "Client application identifier"
      schema:
        type: string
        example: "ChatGPT/2.0"
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: "Unique key to safely retry requests without duplicate token creation"
      schema:
        type: string
        example: "idem_abc123"
    RequestId:
      name: Request-Id
      in: header
      required: false
      description: "Unique identifier for request tracking and debugging"
      schema:
        type: string
        example: "req_123"
    Signature:
      name: Signature
      in: header
      required: false
      description: "Detached JSON signature for request verification"
      schema:
        type: string
        example: "ZXltZX..." # detached signature over canonical JSON
    Timestamp:
      name: Timestamp
      in: header
      required: false
      description: "ISO 8601 timestamp for request timing validation"
      schema:
        type: string
        format: date-time
        example: "2025-09-29T10:30:00Z"
    APIVersion:
      name: API-Version
      in: header
      required: true
      description: "API version date in format YYYY-MM-DD (e.g., 2026-01-30)"
      schema:
        type: string
        example: "2025-09-29"

  schemas:
    DelegatePaymentRequest:
      type: object
      additionalProperties: false
      properties:
        payment_method:
          $ref: "#/components/schemas/PaymentMethodCard"
          description: "The card payment method to tokenize for delegated use"
        allowance:
          $ref: "#/components/schemas/Allowance"
          description: "Constraints on how the payment method can be used"
        billing_address:
          $ref: "#/components/schemas/Address"
          description: "Billing address associated with the payment method"
        risk_signals:
          type: array
          minItems: 1
          description: "List of risk assessment signals from fraud detection"
          items: { $ref: "#/components/schemas/RiskSignal" }
        metadata:
          type: object
          description: "Additional metadata for the request"
          additionalProperties: { type: string }
      required: [payment_method, allowance, risk_signals, metadata]
      example:
        payment_method:
          type: "card"
          card_number_type: "fpan"
          number: "4242424242424242"
          exp_month: "11"
          exp_year: "2026"
          name: "Jane Doe"
          cvc: "223"
          checks_performed: ["avs", "cvv"]
          iin: "424242"
          display_card_funding_type: "credit"
          display_brand: "visa"
          display_last4: "4242"
          metadata: {}
        allowance:
          reason: "one_time"
          max_amount: 5000
          currency: "usd"
          checkout_session_id: "cs_01HV3P3ABC123"
          merchant_id: "acme_corp"
          expires_at: "2026-02-13T12:00:00Z"
        billing_address:
          name: "Jane Doe"
          line_one: "185 Berry Street"
          line_two: "Suite 550"
          city: "San Francisco"
          state: "CA"
          country: "US"
          postal_code: "94107"
        risk_signals:
          - type: "card_testing"
            score: 5
            action: "authorized"
        metadata:
          session_id: "sess_abc123"
          user_agent: "ChatGPT/2.0"

    PaymentMethodCard:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [card]
          description: "Payment method type, always 'card'"
        card_number_type:
          type: string
          enum: [fpan, network_token]
          description: "Whether the number is a raw card number (fpan) or a network token"
        number:
          type: string
          description: "network token or fallback fpan value"
        exp_month:
          type: string
          maxLength: 2
          description: "Two-digit expiration month (01-12)"
        exp_year:
          type: string
          maxLength: 4
          description: "Four-digit expiration year (e.g., 2026)"
        name:
          type: string
          description: "Cardholder name as it appears on the card"
        cvc:
          type: string
          maxLength: 4
          description: "Card verification code (3 or 4 digits)"
        cryptogram:
          type: string
          description: "Dynamic cryptogram for tokenized card transactions"
        eci_value:
          type: string
          maxLength: 2
          description: "Electronic Commerce Indicator for 3DS authentication status"
        checks_performed:
          type: array
          description: "List of verification checks performed on the card"
          items:
            type: string
            enum: [avs, cvv, ani, auth0]
        iin:
          type: string
          maxLength: 6
          description: "Issuer Identification Number (first 6 digits of card)"
        display_card_funding_type:
          type: string
          enum: [credit, debit, prepaid]
          description: "Card funding type for display purposes"
        display_wallet_type:
          type: string
          description: "Digital wallet provider if card is from a wallet (e.g., Apple Pay, Google Pay)"
        display_brand:
          type: string
          description: "Card brand for display purposes (e.g., visa, mastercard)"
        display_last4:
          type: string
          minLength: 4
          maxLength: 4
          pattern: "^[0-9]{4}$"
          description: "Last 4 digits of card number for display purposes"
        metadata:
          type: object
          description: "Additional metadata about the payment method"
          additionalProperties: { type: string }
        virtual:
          type: boolean
          description: "Whether this is a virtual card number"
      required: [type, card_number_type, number, display_card_funding_type, metadata]
      example:
        type: "card"
        card_number_type: "fpan"
        number: "4242424242424242"
        exp_month: "12"
        exp_year: "2027"
        name: "John Smith"
        cvc: "123"
        checks_performed: ["avs", "cvv"]
        iin: "424242"
        display_card_funding_type: "credit"
        display_brand: "visa"
        display_last4: "4242"
        metadata:
          card_origin: "manual_entry"

    Address:
      type: object
      additionalProperties: false
      properties:
        name: 
          type: string
          maxLength: 256
          description: "Full name of the person at this address"
        line_one: 
          type: string
          maxLength: 60
          description: "Street address line 1 (e.g., street and number)"
        line_two: 
          type: string
          maxLength: 60
          description: "Street address line 2 (e.g., apartment, suite, unit)"
        city: 
          type: string
          maxLength: 60
          description: "City or locality"
        state: 
          type: string
          description: "State, province, or region"
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: "ISO-3166-1 alpha-2 country code"
        postal_code: 
          type: string
          maxLength: 20
          description: "ZIP or postal code"
      required: [name, line_one, city, state, country, postal_code]
      example:
        name: "John Smith"
        line_one: "555 Golden Gate Avenue"
        line_two: "Apt 401"
        city: "San Francisco"
        state: "CA"
        country: "US"
        postal_code: "94102"

    Allowance:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          enum: [one_time]
          description: "Usage pattern for this allowance; currently only one_time is supported"
        max_amount:
          type: integer
          description: "Maximum charge amount in minor units (e.g. 100 cents for $1.00 or 100 for ¥100)"
        currency:
          type: string
          pattern: "^[a-z]{3}$"
          description: "ISO-4217 three-letter lowercase currency code (e.g., usd)"
        checkout_session_id:
          type: string
          description: "Identifier of the checkout session this payment is for"
        merchant_id:
          type: string
          maxLength: 256
          description: "Unique identifier for the merchant authorized to use this token"
        expires_at:
          type: string
          format: date-time
          description: "ISO 8601 timestamp when this allowance expires"
      required:
        [
          reason,
          max_amount,
          currency,
          checkout_session_id,
          merchant_id,
          expires_at,
        ]
      example:
        reason: "one_time"
        max_amount: 100000
        currency: "usd"
        checkout_session_id: "csn_01HV3P3XYZ789"
        merchant_id: "merchant_12345"
        expires_at: "2026-02-15T18:30:00Z"

    RiskSignal:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [card_testing]
          description: "Type of risk signal detected"
        score:
          type: integer
          description: "Risk score indicating severity level"
        action:
          type: string
          enum: [blocked, manual_review, authorized]
          description: "Recommended action based on risk assessment"
      required: [type, score, action]
      example:
        type: "card_testing"
        score: 15
        action: "manual_review"

    DelegatePaymentResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: "Unique vault token identifier (vt_...)"
        created:
          type: string
          format: date-time
          description: "ISO 8601 timestamp when the token was created"
        metadata:
          type: object
          description: "Metadata echoed from the request plus system-added fields"
          additionalProperties: { type: string }
      required: [id, created, metadata]
      example:
        id: "vt_01J8Z3WXYZ9ABC123"
        created: "2026-02-12T14:30:00Z"
        metadata:
          source: "agent_checkout"
          merchant_id: "acme_corp"
          idempotency_key: "idem_xyz789"

    Error:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            [
              invalid_request,
              rate_limit_exceeded,
              processing_error,
              service_unavailable,
            ]
          description: "High-level error category"
        code:
          type: string
          enum: [invalid_card, duplicate_request, idempotency_conflict, too_many_requests]
          description: "Specific error code for programmatic handling"
        message:
          type: string
          description: "Human-readable error message"
        param:
          type: string
          description: "JSONPath of offending field"
      required: [type, code, message]
      example:
        type: "invalid_request"
        code: "invalid_card"
        message: "Invalid card expiration year"
        param: "$.payment_method.exp_year"