openapi: 3.0.3
info:
  title: PSP Hosted Checkout API
  version: 1.0.0
  description: |
    Consumer checkout for an existing Gateway PaymentIntent. Use the
    psp_checkout_url returned by the Invoice API. Checkout access requires a
    token bound to the payment and tenant in X-Checkout-Session-Token or ?t=.
    Merchant Gateway credentials do not apply.
servers:
  - url: https://checkout.psp.example.com
    description: Example host; obtain the actual Checkout host from PSP
tags:
  - name: Hosted Checkout
paths:
  /checkout/hosted/payments/{payment_id}:
    get:
      tags: [Hosted Checkout]
      summary: Read hosted payment and saved instructions
      parameters:
        - $ref: '#/components/parameters/PaymentID'
        - $ref: '#/components/parameters/SessionToken'
        - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Hosted payment detail and instructions
  /checkout/hosted/payments/{payment_id}/status:
    get:
      tags: [Hosted Checkout]
      summary: Read payment status
      parameters:
        - $ref: '#/components/parameters/PaymentID'
        - $ref: '#/components/parameters/SessionToken'
        - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Payment status
  /checkout/hosted/payments/{payment_id}/success-redirect:
    get:
      tags: [Hosted Checkout]
      summary: Read the validated return redirect
      parameters:
        - $ref: '#/components/parameters/PaymentID'
        - $ref: '#/components/parameters/SessionToken'
        - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Redirect decision
  /checkout/creditcard/payment-intents/{payment_id}/pay:
    post:
      tags: [Hosted Checkout]
      summary: Submit hosted credit card payment
      parameters:
        - $ref: '#/components/parameters/PaymentID'
        - $ref: '#/components/parameters/SessionToken'
        - $ref: '#/components/parameters/TokenQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardPaymentRequest'
      responses:
        '200':
          description: Payment submitted
  /checkout/creditcard/payment-intents/{payment_id}/complete-3ds:
    post:
      tags: [Hosted Checkout]
      summary: Complete card 3DS authentication
      parameters:
        - $ref: '#/components/parameters/PaymentID'
        - $ref: '#/components/parameters/SessionToken'
        - $ref: '#/components/parameters/TokenQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [authorization_id, transaction_id, auth_value, eci, cres_nonce]
              properties:
                authorization_id: { type: string, format: uuid }
                transaction_id: { type: string }
                auth_value: { type: string }
                eci: { type: string }
                cres_nonce: { type: string }
      responses:
        '200':
          description: 3DS completed
components:
  parameters:
    PaymentID:
      name: payment_id
      in: path
      required: true
      schema: { type: string, format: uuid }
    SessionToken:
      name: X-Checkout-Session-Token
      in: header
      description: Checkout token; provide this header or t.
      schema: { type: string }
    TokenQuery:
      name: t
      in: query
      description: Checkout token; provide this parameter or X-Checkout-Session-Token.
      schema: { type: string }
  schemas:
    CardPaymentRequest:
      type: object
      description: Supply card_token with card_cvv or one-time card_info.
      properties:
        card_token: { type: string }
        card_cvv: { type: string }
        card_info:
          type: object
          required: [card_number, cvv, expiry_month, expiry_year, cardholder_name]
          properties:
            card_number: { type: string }
            cvv: { type: string }
            expiry_month: { type: integer, minimum: 1, maximum: 12 }
            expiry_year: { type: integer }
            cardholder_name: { type: string }
        billing_address: { type: object, additionalProperties: true }
        payer_info:
          type: object
          properties:
            name: { type: string }
            email: { type: string, format: email }
            phone: { type: string }
        require_3ds: { type: boolean }