openapi: 3.0.3
info:
  title: Admin Account / Address Adyen API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Adyen
paths:
  /api/v2/storefront/adyen/payment_sessions:
    post:
      summary: Create an Adyen Payment Session
      description: Create a new Adyen payment session with the specified amount. Adyen support is currently in private beta. [Please contact us](https://spreecommerce.org/contact) to get access.
      tags:
      - Adyen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_session:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: The payment amount
                      example: 80.99
                    channel:
                      type: string
                      default: Web
                      enum:
                      - Web
                      - Android
                      - iOS
                    return_url:
                      type: string
                      default: https://{host}/adyen/payment_sessions/redirect
                      description: URL to return back to store after payment with redirect flow like Klarna or iDEAL. The URL must not include personally identifiable information (PII), for example name or email address.
                  required:
                  - amount
              required:
              - payment_session
            example:
              payment_session:
                amount: 80.99
                channel: Android
                return_url: my-app://your.package.name
      operationId: create-adyen-payment-session
      responses:
        '200':
          $ref: '#/components/responses/AdyenPaymentSession'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
  /api/v2/storefront/adyen/payment_sessions/{id}/complete:
    post:
      summary: Complete an Adyen payment session and order
      description: Complete an Adyen payment session and order. Adyen support is currently in private beta. [Please contact us](https://spreecommerce.org/contact) to get access.
      tags:
      - Adyen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_result:
                  type: string
                  description: The Adyen payment session result
              required:
              - session_result
            example:
              session_result: AdyenResultData
      operationId: complete-adyen-payment-session
      responses:
        '200':
          $ref: '#/components/responses/AdyenPaymentSession'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
  /api/v2/storefront/adyen/payment_sessions/{id}:
    get:
      summary: Get Adyen Payment Session
      description: Retrieve An Adyen payment session information. Adyen support is currently in private beta. [Please contact us](https://spreecommerce.org/contact) to get access.
      tags:
      - Adyen
      operationId: get-adyen-payment-session
      responses:
        '200':
          $ref: '#/components/responses/AdyenPaymentSession'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
      security:
      - orderToken: []
components:
  responses:
    403Forbidden:
      description: 403 Forbidden - You are not authorized to access this page.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: You are not authorized to access this page.
                default: You are not authorized to access this page.
          examples:
            403 Example:
              value:
                error: You are not authorized to access this page.
    404NotFound:
      description: 404 Not Found - Resource not found.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: The resource you were looking for could not be found.
                default: The resource you were looking for could not be found.
          examples:
            404 Example:
              value:
                error: The resource you were looking for could not be found.
    AdyenPaymentSession:
      description: 200 Success - Returns the Adyen Payment Session with session data and payment amount.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                    example: '3'
                  type:
                    type: string
                    default: adyen_payment_session
                  attributes:
                    type: object
                    properties:
                      adyen_id:
                        type: string
                        description: The Adyen session ID
                        example: CS3E6B43783787E79B
                      amount:
                        type: string
                        description: The payment amount
                        example: '80.99'
                      currency:
                        type: string
                        description: The payment currency
                        example: USD
                      client_key:
                        type: string
                        description: The Adyen client key
                        example: your_client_key
                      adyen_data:
                        type: string
                        description: The Adyen session data required for payment processing
                      channel:
                        type: string
                        default: Web
                        enum:
                        - Web
                        - Android
                        - iOS
                        description: The channel of the payment session
                        example: Android
                      return_url:
                        type: string
                        description: URL to return back to store after payment with redirect flow like Klarna or iDEAL. The URL must not include personally identifiable information (PII), for example name or email address.
                        example: https://{host}/adyen/payment_sessions/redirect
                      status:
                        type: string
                        description: The status of the payment session
                        example: initial
                      expires_at:
                        type: string
                        format: date-time
                        description: The expiration date and time of the payment session
                        example: '2025-07-24T14:40:45.000Z'
                  relationships:
                    type: object
                    properties:
                      order:
                        type: object
                        properties:
                          data:
                            type: object
                            properties:
                              id:
                                type: string
                                example: '4'
                              type:
                                type: string
                                example: cart
                      payment_method:
                        type: object
                        properties:
                          data:
                            type: object
                            properties:
                              id:
                                type: string
                                example: '4'
                              type:
                                type: string
                                example: payment_method
                      user:
                        type: object
                        properties:
                          data:
                            nullable: true
          examples:
            Adyen Payment Session:
              value:
                data:
                  id: '3'
                  type: adyen_payment_session
                  attributes:
                    adyen_id: CS3E6B43783787E79B
                    amount: '80.99'
                    currency: USD
                    channel: iOS
                    adyen_data: Ab02b4c0!BQABAgCNxadId3f9NXF6OMYGXsZAoAwcnOdgINKAypoyo8GUq8UqjnT/7J8K4kNhl6tjWOpGY6t+r+4QQVVfo4IHFWtjzNkj2k9dnTS4932UyCznLC+gHbzPHcfN6rNiHBIpQo523a94EvV2Sq1Gh/3j6N2aNCjfV2TDWynQJU11uOhalgwhAnVrD3HmFtbVqM60kGiPRBfE4LwLuQ7f+7S/cdVx8HzWizvafndeRnx5lM3RQNibNRbimJ3G6YZh/HI9FwZYbxkUoq8dQl8dgdquNKAxsSO0BcC6UpTU2Z8d/z3lAsm0UlX1+YiryRut4Ipg9YqJbVt3gnj7Kh4kZFRO1hZM8NDeD9PshE8riBXDpUwJ84m+9I+cfbnwYWgfZaGuxfGG+IiiliQBWIjHefd6ukUATLWsPX6ufUL7BT3rSMx/5QMmdNrE/zMA9B1tFg5Tm8t88S6WQcSZ/vIgOv+peDml5j44OcEth6iEqxRwsmT3T0nZUhYwYUSTEykrpY9+Ly2+NWpTE+sgvXhld6SZubbbG9gIBad6TIwaKkUO0kJOx6Zvk37uU2D0z8mnWIktimBZIqhegsdBXutVyUe93xSighf/C41n69COSjALE3KCcXGCmR4NsdwJ7LesJMYLu1S4gDOObvkuW5IY2k8r6pptUWgsOxcyUvbpPMlQrjRTHAwRPxcnk0SJrSL29HwASnsia2V5IjoiQUYwQUFBMTAzQ0E1MzdFQUVEODdDMjRERDUzOTA5QjgwQTc4QTkyM0UzODIzRDY4REFDQzk0QjlGRjgzMDVEQyJ9JcDZ7NsVaMwwHpvV0vX/5b7P9FS/1TfuFbQRmlFX4vCQOLxSiyAf5P4uN7Hb2Zw4dplBl4oSEBBUvrKk5TCqjGoS1azHS8Fv5LCcl2yCDH6WBtQKzJnT6NmXl29+ILYCxETtyF9K8LwgJyu8sHs2jQnnLujLBqqjIZqDFa8TORtGiwvhtS3UMtagkkg0SkCaaaOjqtZdWrTy7C9Gy9nFZNYEfmurFZmgLRROTB3jRNwmveWvayFJl4TTtub14l+RZJDx2VgjAwqRU8btN/0xnrT9m2kg6LOyW4F9TkauPgAzY3Gu//HQOGW7VDBPq6y83mzP7iNp8Whe14NQSu29i9rBricl0f6RoWin87jRD7AtZx0MxlhNxUF579COCwNHAMhs310nntoSY5U8s13of9Wn2lDcBcg2QmSNOixMMIcBkjHpEQEZAeGzfi8OvJtjoi9TVY0VzrpSbR1dcx8MNjOUeY37H+XlWkdEkd3457zbeOuSlEbjvuDYW7tYHYWipsd4fNllXiMzKW+w6YxL2Kqj0M5B+3ihuEKg7VS3b/XKs+OS7eHGZSImAt9e4tGltEqYzdRHzm4S6pnJytaoPp7+OswEm+JQTi739w4CJeNWxr1t9dot2k9OQw3vZabeI7OTrwBc2IwtUYZ9oPlBVOibMoUwCIVmSPrSgF8nCj9S2RdZgamLNnyg1srQmWnNxtOLMnvTnWedICtoE48rMG2Q+cDrEjy11TCGK3R+LHE+LaqPv96yk3ztsHomOF7XstAvLvUAIH3Z/X5+ePNcDzV7OZkS9xcLkqGqeqR04iHGZZfLw3q4rauZMWLyxb+NkGKfgTtGhe7nq+Z7bGXWxzQh694dJf+59oGCslmfJ44cd8SX3o2JjSZ7Ew7LgQt7fj6z+yif1Bs8SH3QNZN9POsfxJggCwRIhvaPmZR7hsV75+b4jC+wU2LAHik8Nr1pt48NpCxULtKNw6ZPUbJwMVWK7gmZtqa39l7OmIs2PE54vgeZk38XBi6K1UFqoZlV667GrnwOgscob3DFPMcjZhCBYOWJNLjxjqP6pw3zf7OB/ZA1m4F6yv4LVka19rlQk0esAqfTy36KbJggRYNJdGYgDr6u2zz3NblMfZpys5mtpW8ncoBdsOeWlL+cspDGig9HINHT2CnrL9+N7oU=
                    client_key: test_ECRHWDLSER123456HMT57VW7XGOUDA23
                    status: initial
                    expires_at: '2025-07-24T14:40:45.000Z'
                    return_url: https://example.com/adyen/payment_sessions/redirect
                  relationships:
                    order:
                      data:
                        id: '4'
                        type: cart
                    payment_method:
                      data:
                        id: '4'
                        type: payment_method
                    user:
                      data: null
    422UnprocessableEntity:
      description: 422 Unprocessable Entity
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            422 Example:
              value:
                error: Example is invalid
                errors:
                  example:
                  - Example is invalid
  schemas:
    Error:
      x-internal: false
      title: Error
      type: object
      properties:
        error:
          type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Products & Catalog
  tags:
  - Products
  - Variants
  - Option Types
  - Custom Fields
  - Channels
- name: Pricing
  tags:
  - Pricing
  - Markets
- name: Orders & Fulfillment
  tags:
  - Orders
  - Payments
  - Fulfillments
  - Refunds
- name: Customers
  tags:
  - Customers
  - Customer Groups
- name: Promotions & Gift Cards
  tags:
  - Promotions
  - Gift Cards
- name: Data
  tags:
  - Exports
- name: Configuration
  tags:
  - Settings
  - Stock Locations
  - Payment Methods
  - Staff
  - API Keys
  - Allowed Origins
  - Webhooks