api.yaml

openapi: 3.1.0
info:
  title: OffBlocks API 1.0
  version: 1.0.0
servers:
  - url: https://api.offblocks.xyz/v1
  - url: https://api.sandbox.offblocks.xyz/v1
tags:
  - name: Authentication
  - name: Customers
  - name: Accounts
  - name: Cards
  - name: Transactions
  - name: Webhooks
  - name: Engine
paths:
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Initial Authentication
      description: Retrieve authentication token using API credentials
      operationId: getToken
      requestBody:
        content:
          application/json:
            schema:
              required:
                - apiKey
                - apiSecret
              type: object
              properties:
                apiKey:
                  type: string
                  format: uuid
                  description: Unique API key used to identify your API integration. Note this can be different for live and sandbox environments
                  examples: ["d04953b7-5878-4fd0-8970-0a5f77fbce59"]
                apiSecret:
                  type: string
                  description: API secret
                  examples: ["64ec977db2e585887c80ed62fe9997994aed8093"]
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '400':
          description: Invalid request
        '401':
          description: Invalid credentials
        '500':
          description: Internal error
  /auth/signing:
    put:
      tags:
        - Authentication
      summary: Update signing key
      description: Update public key used to sign API requests. When you upload your public key, a unique key ID is returned in response. This is different to your public key itself, and is required to sign your requests
      operationId: updateSigningKey
      requestBody:
        content:
          application/json:
            schema:
              required:
                - signingKeyId
                - signingKey
              type: object
              properties:
                signingKeyId:
                  type: string
                  format: uuid
                  description: Unique ID of your key. This is different to your public key itself, and is required to sign your requests
                  examples: ["86b59965-6cf1-4633-9148-92848330fd1b"]
                signingKey:
                  type: string
                  format: byte
                  description: Base64 encoded public key used for signing requests. Requirements for cryptographic algorithms and more details can be found in our documentation
                  examples: ["LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="]
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    delete:
      tags:
        - Authentication
      summary: Delete signing key
      description: Delete public key used to sign API requests
      operationId: deleteSigningKey
      requestBody:
        content:
          application/json:
            schema:
              required:
                - signingKeyId
              type: object
              properties:
                signingKeyId:
                  type: string
                  format: uuid
                  description: Unique ID of your key. This is different to your public key itself, and is required to sign your requests
                  examples: ["86b59965-6cf1-4633-9148-92848330fd1b"]
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /auth/credentials:
    put:
      tags:
        - Authentication
      summary: Update API credentials
      description: Add or update API credentials. If credentials are updated this action invalidates all issued tokens and active sessions
      operationId: updateCredentials
      requestBody:
        content:
          application/json:
            schema:
              required:
                - apiKey
                - apiSecret
              type: object
              properties:
                apiKey:
                  type: string
                  format: uuid
                  description: Unique API key used to identify your API integration. Note this can be different for live and sandbox environments
                  examples: ["d04953b7-5878-4fd0-8970-0a5f77fbce59"]
                apiSecret:
                  type: string
                  description: API secret
                  examples: ["64ec977db2e585887c80ed62fe9997994aed8093"]
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    delete:
      tags:
        - Authentication
      summary: Delete API credentials
      description: Delete existing API credentials. This invalidates all issued tokens and active sessions
      operationId: deleteCredentials
      requestBody:
        content:
          application/json:
            schema:
              required:
                - apiKey
              type: object
              properties:
                apiKey:
                  type: string
                  format: uuid
                  description: Unique API key used to identify your API integration. Note this can be different for live and sandbox environments
                  examples: ["d04953b7-5878-4fd0-8970-0a5f77fbce59"]
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /chains:
    get:
      tags:
        - Engine
      summary: Retrieve supported blockchains
      description: Retrieves supported blockchains
      operationId: getChains
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Blockchain'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /assets:
    get:
      tags:
        - Engine
      summary: Retrieve supported assets
      description: Retrieves supported assets
      operationId: getAssets
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - in: query
          name: chain
          schema:
            type: string
            examples: ["eip155:1", "starknet:SN_MAIN"]
          description: Optional filter by blockchain
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers:
    post:
      tags:
        - Customers
      summary: Create new customer
      description: Creates new customer and generates a cryptographic challenge to verify ownership of blockchain account
      operationId: createCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: 
                - chainId
                - externalId
              properties:
                chainId:
                  description: Unique customer ID in a form of a valid on-chain address. This would normally correspond to customer's EOA wallet address
                  $ref: '#/components/schemas/BlockchainAccountId'
                externalId:
                  description: Unique customer ID in a form of an external identifier. This would normally correspond to customer's ID in your system
                  type: string
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Customer'
                  - $ref: '#/components/schemas/OwnerChallenge'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '409':
          description: Customer already exists
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    get:
      tags:
        - Customers
      summary: Retrieve customers
      description: Retrieves customers' details
      operationId: getCustomers
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}:
    get:
      tags:
        - Customers
      summary: Retrieve customer
      description: Retrieves customer's details
      operationId: getCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: customerId
          in: path
          description: ID of customer to be retrieved
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}/challenge:
    get:
      tags:
        - Customers
      summary: Retrieve customer challenge
      description: Retrieves challenge to verify customer's ownership of their blockchain account
      operationId: getCustomerChallenge
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: customerId
          in: path
          description: ID of customer to be challenged
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerChallenge'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}/challenge/sign:
    post:
      tags:
        - Customers
      summary: Sign previously issued customer challenge
      description: Signs previously issued challenge to verify customer's ownership of their blockchain account
      operationId: signCustomerChallenge
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
        - name: customerId
          in: path
          description: ID of customer to be challenged
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerSignature'
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '409':
          description: Challenge already signed
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}/deactivate:
    patch:
      tags:
        - Customers
      summary: Deactivate customer
      description: Deactivates customer and all associated resources
      operationId: deactivateCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: customerId
          in: path
          description: ID of customer to be deactivated
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}/activate:
    patch:
      tags:
        - Customers
      summary: Activate customer
      description: Activates customer and all associated resources
      operationId: activateCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: customerId
          in: path
          description: ID of customer to be activated
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /customers/{customerId}/accounts:
    post:
      tags:
        - Accounts
      summary: Create new customer account
      description: Creates new account for the customer and generates a challenge to be signed in order to create a related blockchain account
      operationId: createCustomerAccount
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
        - name: customerId
          in: path
          description: ID of customer
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - currencies
              properties:
                type:
                  $ref: '#/components/schemas/AccountType'
                currencies:
                  type: array
                  description: Currencies of the account, at least one is required (ISO-4217)
                  items:
                    type: string
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Account'
                  - $ref: '#/components/schemas/OwnerChallenge'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    get:
      tags:
        - Accounts
      summary: Retrieve customer accounts
      description: Retrieves customer's accounts
      operationId: getCustomerAccounts
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: customerId
          in: path
          description: ID of the customer
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts:
    get:
      tags:
        - Accounts
      summary: Retrieve accounts
      description: Retrieves accounts' details
      operationId: getAccounts
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}:
    get:
      tags:
        - Accounts
      summary: Retrieve account
      description: Retrieves account's details
      operationId: getAccount
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: accountId
          in: path
          description: ID of account to be retrieved
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    delete:
      tags:
        - Accounts
      summary: Close account
      description: Closes account and generates a challenge to be signed in order to delete related blockchain account
      operationId: closeAccount
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: accountId
          in: path
          description: ID of account to be closed
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/challenge:
    get:
      tags:
        - Accounts
      summary: Retrieve account challenge
      description: Retrieves challenge to sign account creation or deletion transaction on-chain. This operation invalidates any previously issued challenges for the account
      operationId: getAccountChallenge
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: accountId
          in: path
          description: ID of account to be challenged
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerChallenge'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/challenge/sign:
    post:
      tags:
        - Accounts
      summary: Sign previously issued account challenge
      description: Signs previously issued challenge to sign account creation or deletion transaction on-chain
      operationId: signAccountChallenge
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
        - name: accountId
          in: path
          description: ID of account to be challenged
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerSignature'
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Challenge already signed
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/deactivate:
    patch:
      tags:
        - Accounts
      summary: Deactivate account
      description: Deactivates account and all associated resources
      operationId: deactivateAccount
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: accountId
          in: path
          description: ID of account to be deactivated
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/activate:
    patch:
      tags:
        - Accounts
      summary: Activate account
      description: Activates account and all associated resources
      operationId: activateAccount
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: accountId
          in: path
          description: ID of account to be activated
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/cards:
    post:
      tags:
        - Cards
      summary: Create new card
      description: Creates new card for the account
      operationId: createAccountCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
        - name: accountId
          in: path
          description: ID of account
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - billingAddress
              properties:
                type:
                  $ref: '#/components/schemas/CardType'
                billingAddress:
                  description: Billing address of a cardholder
                  $ref: '#/components/schemas/Address'
                shippingAddress:
                  description: Shipping address for the card. Required for physical cards
                  $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    get:
      tags:
        - Cards
      summary: Retrieve account cards
      description: Retrieves account's cards
      operationId: getAccountCards
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: accountId
          in: path
          description: ID of the account
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /cards:
    get:
      tags:
        - Cards
      summary: Retrieve cards
      description: Retrieves cards' details
      operationId: getCards
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /cards/{cardId}:
    get:
      tags:
        - Cards
      summary: Retrieve card
      description: Retrieves card's details
      operationId: getCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: cardId
          in: path
          description: ID of a card to be retrieved
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    delete:
      tags:
        - Cards
      summary: Terminate card
      description: Terminates card
      operationId: deleteCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: cardId
          in: path
          description: ID of a card to be closed
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /cards/{cardId}/deactivate:
    patch:
      tags:
        - Cards
      summary: Deactivate card
      description: Deactivates card and all associated resources
      operationId: deactivateCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: cardId
          in: path
          description: ID of card to be deactivated
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /cards/{cardId}/activate:
    patch:
      tags:
        - Cards
      summary: Activate card
      description: Activates card and all associated resources
      operationId: activateCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: cardId
          in: path
          description: ID of card to be activated
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '409':
          description: Invalid state transition
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /accounts/{accountId}/transactions:
    get:
      tags:
        - Transactions
      summary: Retrieve account transactions
      description: Retrieves account's transactions
      operationId: getAccountTransactions
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: accountId
          in: path
          description: ID of the account
          required: true
          schema:
            $ref: '#/components/schemas/AccountId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Account not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /cards/{cardId}/transactions:
    get:
      tags:
        - Transactions
      summary: Retrieve card transactions
      description: Retrieves card's transactions
      operationId: getCardTransactions
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: cardId
          in: path
          description: ID of the card
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Retrieve transaction details
      description: Retrieves transaction's details
      operationId: getTransactionDetails
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: transactionId
          in: path
          description: ID of the transaction
          required: true
          schema:
            $ref: '#/components/schemas/TransactionId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Transaction not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /authorisations/{authorisationId}:
    get:
      tags:
        - Authorisations
      summary: Retrieve authorisation details
      description: Retrieves authorisation's details
      operationId: getAuthorisationDetails
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: authorisationId
          in: path
          description: ID of the authorisation
          required: true
          schema:
            $ref: '#/components/schemas/AuthorisationId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorisation'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Authorisation not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: Retrieve all active webhooks
      description: Retrieves all active webhooks
      operationId: getWebhooks
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    put:
      tags:
        - Webhooks
      summary: Create new or update an existing webhook
      description: Creates new webhook subscription or updates an existing one
      operationId: saveWebhook
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - callbackUrl
                - types
              properties:
                id:
                  description: Unique ID of the webhook to be updated
                  $ref: '#/components/schemas/WebhookId'
                callbackUrl:
                  $ref: '#/components/schemas/URL'
                  description: URL to be subscribed for receiving events
                types:
                  type: array
                  description: Types of events to be received by the callback
                  items:
                    $ref: '#/components/schemas/WebhookType'
      callbacks:
        webhook:
          '{$request.body#/callbackUrl}':
            post:
              parameters:
                - $ref: '#/components/parameters/SignatureHeader'
                - $ref: '#/components/parameters/SignatureInputHeader'
              requestBody:
                description: Updates for entities based on subscribed scope
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/WebhookEvent'
              responses:
                '200':
                  description: Return a 200 status to indicate that the data was received successfully
                  content: 
                    application/json:
                      schema:
                        $ref: '#/components/schemas/WebhookResponse'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /webhooks/{webhookId}:
    get:
      tags:
        - Webhooks
      summary: Retrieve webhook subscription information
      description: Retrieves webhook subscription information
      operationId: getWebhook
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - name: webhookId
          in: path
          description: ID for a webhook to be retrieved
          required: true
          schema:
            $ref: '#/components/schemas/WebhookId'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Webhook not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
    delete:
      tags:
        - Webhooks
      summary: Remove webhook subscription
      description: Removes webhook subscription
      operationId: deleteWebhook
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: webhookId
          in: path
          description: ID for a webhook to be removed
          required: true
          schema:
            $ref: '#/components/schemas/WebhookId'
      responses:
        '204':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Webhook not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /webhooks/verification-key:
    get:
      tags:
        - Webhooks
      summary: Retrieve webhook verification key
      description: Retrieves webhook verification key
      operationId: getWebhookVerificationKey
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationKey'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/customers/{customerId}/verify:
    patch:
      tags:
        - Simulator
      summary: Verify customer
      description: Simulates customer verification success
      operationId: simulateVerifyCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: customerId
          in: path
          description: ID of customer to be verified
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/customers/{customerId}/reject:
    patch:
      tags:
        - Simulator
      summary: Reject customer
      description: Simulates customer verification rejection
      operationId: simulateRejectCustomer
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: customerId
          in: path
          description: ID of customer to be rejected
          required: true
          schema:
            $ref: '#/components/schemas/CustomerId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Customer not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/cards/{cardId}/issue:
    patch:
      tags:
        - Simulator
      summary: Issue card
      description: Simulates card issuing success
      operationId: simulateIssueCard
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: cardId
          in: path
          description: ID of card to be issued
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/cards/{cardId}/fail:
    patch:
      tags:
        - Simulator
      summary: Fail card issuance
      description: Simulates card issuing failure
      operationId: simulateCardFail
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: cardId
          in: path
          description: ID of card to be failed
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/cards/{cardId}/authorisation:
    post:
      tags:
        - Simulator
      summary: Initiate card authorisation
      description: Simulates card authorisation
      operationId: simulateCardAuthorisation
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - $ref: '#/components/parameters/ContentDigestHeader'
        - name: cardId
          in: path
          description: ID of card
          required: true
          schema:
            $ref: '#/components/schemas/CardId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - capture
              properties:
                amount:
                  description: Amount to be authorised
                  $ref: '#/components/schemas/Decimal'
                currency:
                  type: string
                  description: Authorisation currency (ISO-4217)
                  examples: ["EUR"]
                capture:
                  type: boolean
                  default: true
                  description: Whether to capture the authorisation immediately
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorisation'
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Card not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/authorisations/{authorisationId}/capture:
    patch:
      tags:
        - Simulator
      summary: Capture card authorisation
      description: Simulates card authorisation capture
      operationId: simulateCardAuthorisationCapture
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: authorisationId
          in: path
          description: ID of authorisation to be captured
          required: true
          schema:
            $ref: '#/components/schemas/AuthorisationId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Authorisation not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
  /simulator/authorisations/{authorisationId}/release:
    patch:
      tags:
        - Simulator
      summary: Release card authorisation
      description: Simulates card authorisation release
      operationId: simulateCardAuthorisationRelease
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
        - name: authorisationId
          in: path
          description: ID of authorisation to be released
          required: true
          schema:
            $ref: '#/components/schemas/AuthorisationId'
      responses:
        '202':
          description: Successful operation
        '400':
          description: Invalid request
        '401':
          description: Not authorised
        '404':
          description: Authorisation not found
        '500':
          description: Internal error
      security:
        - bearerAuth: []
webhooks:
  '{callbackUrl}':
    post:
      parameters:
        - $ref: '#/components/parameters/SignatureHeader'
        - $ref: '#/components/parameters/SignatureInputHeader'
      requestBody:
        description: Webhook events based on subscribed types
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
components:
  schemas:
    Authentication:
      required:
        - token
        - expiresAt
        - tokenType
      type: object
      properties:
        token:
          type: string
          description: JWT token that can be used for further requests to authenticated endpoints
          examples: ["eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"]
        expiresAt:
          type: integer
          description: "`token` expiration time (UNIX timestamp)"
          examples: [1699974342]
        tokenType:
          type: string
          description: '`token` type. Must be "Bearer"'
          examples: ["Bearer"]
    Customer:
      required:
        - id
        - externalId
        - chainId
        - status
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CustomerId'
        externalId:
          type: string
          description: Unique customer ID in a form of an external ID
        chainId:
          description: Unique customer ID in a form of a valid on-chain address. This would normally correspond to customer's EOA wallet address
          $ref: '#/components/schemas/BlockchainAccountId'
        status:
          $ref: '#/components/schemas/CustomerStatus'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this customer was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this customer was updated (ISO-8601)
    CustomerId:
      description: Unique customer ID
      $ref: '#/components/schemas/UUID'
    CustomerStatus:
      type: string
      description: Customer status
      enum:
        - initiating
        - screening
        - verifying
        - rejected
        - active
        - inactive

    CustomerInfo:
      type: object
      required:
        - name
        - dateOfBirth
        - address
      properties:
        name:
          type: string
          description: Full first and last name of the customer (not initials)
        email:
          type: string
          format: email
          description: The email address of the customer according to RFC 2822. One of email/phone is required
        phone:
          type: string
          description: The phone number of the customer in formats recommended by ITU. The country calling code must be included and prefixed with a +. One of email/phone is required
        dateOfBirth:
          type: string
          format: date
          description: The date of birth of the customer, in YYYY-MM-DD format.
        address:
          $ref: '#/components/schemas/Address'

    Account:
      required:
        - id
        - customerId
        - status
        - type
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AccountId'
        customerId:
          $ref: '#/components/schemas/CustomerId'
        chainId:
          description: Unique account ID in a form of a valid on-chain address. This would normally correspond to account's SCA address
          $ref: '#/components/schemas/BlockchainAccountId'
        status:
          $ref: '#/components/schemas/AccountStatus'
        type:
          $ref: '#/components/schemas/AccountType'
        currencies:
          type: array
          description: Currencies of the account, at least one is required (ISO-4217)
          items:
            type: string
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this account was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this account was updated (ISO-8601)
    AccountId:
      description: Unique account ID
      $ref: '#/components/schemas/UUID'
    AccountStatus:
      type: string
      description: Account status
      enum:
        - initiating
        - pending
        - active
        - inactive
        - closed
        - failed
    AccountType:
      type: string
      description: Type of the account
      enum:
        - card_account

    Card:
      required:
        - id
        - accountId
        - type
        - status
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CardId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        type:
          $ref: '#/components/schemas/CardType'
        name:
          type: string
          description: Name on the card
          examples: ["John Carter"]
        network:
          $ref: '#/components/schemas/CardNetwork'
        maskedPan:
          type: string
          description: Card PAN masked according to regulations
          examples: ["530518******9871"]
        expirationDate:
          type: string
          description: Expiration date of the card in MM/YYYY format
          examples: ["10/2028"]
        billingAddress:
          $ref: '#/components/schemas/Address'
          description: Billing address of a cardholder
        status:
          $ref: '#/components/schemas/CardStatus'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this card was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this card was updated (ISO-8601)
    CardId:
      description: Unique card ID
      $ref: '#/components/schemas/UUID'
    CardStatus:
      type: string
      description: Card status
      enum:
        - issuing
        - issue_failed
        - active
        - inactive
        - blocked
        - suspended
        - terminated
    CardType:
      type: string
      description: Card type
      enum:
        - virtual
        - physical
    CardNetwork:
      type: string
      description: Card network
      enum:
        - visa
        - mastercard

    Address:
      type: object
      required:
        - firstLine
        - city
        - country
        - postCode
      properties:
        firstLine:
          type: string
          description: First line of address
          examples: ["Flat G"]
        secondLine:
          type: string
          description: Second line of address (optional)
          examples: ["321 West End Lane"]
        city:
          type: string
          description: City
          examples: ["London"]
        state:
          type: string
          description: State or province (optional)
        country:
          type: string
          description: Country code (ISO 3166-1)
          examples: ["GB"]
        postCode:
          type: string
          description: Postal or ZIP code
          examples: ["NW6 2FG"]

    Merchant:
      type: object
      required:
        - id
        - name
        - mcc
        - country
        - city
      description: Merchant information
      properties: 
        id:
          type: string
          description: ID of the merchant
        name:
          type: string
          description: Name of the merchant
        mcc:
          type: integer
          description: Merchant Category Code
        country:
          type: string
          description: Country code of the merchant location (ISO 3166-1)
        city:
          type: string
          description: City of the merchant location

    Fee:
      type: object
      required:
        - type
        - tokenAmount
      description: Fee information for token transactions
      properties: 
        type:
          $ref: '#/components/schemas/FeeType'
        tokenAmount:
          description: Token amount expressed as a decimal number
          $ref: '#/components/schemas/Decimal'

    FeeType:
      type: string
      description: Fee type
      enum:
        - partner
        - service
        - network

    ChainTransaction:
      type: object
      required:
        - chainId
        - createdAt
      properties:
        chainId:
          description: Unique transaction ID on-chain
          $ref: '#/components/schemas/BlockchainTransactionId'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this transaction was created (ISO-8601)

    Transaction:
      required:
        - id
        - accountId
        - status
        - direction
        - amount
        - currency
        - merchantAmount
        - merchantCurrency
        - exchangeRate
        - merchant
        - tokenAmount
        - token
        - fees
        - chainTransactions
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TransactionId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        cardId:
          $ref: '#/components/schemas/CardId'
        authorisationId:
          $ref: '#/components/schemas/AuthorisationId'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        direction:
          $ref: '#/components/schemas/TransactionDirection'
        amount:
          description: Transaction amount expressed as a decimal number
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
          description: Currency of the transaction (ISO-4217)
          examples: ["EUR"]
        merchantAmount:
          description: Total authorised amount in origin (merchant) currency expressed as a decimal number
          $ref: '#/components/schemas/Decimal'
        merchantCurrency:
          type: string
          description: Origin currency of the merchant (ISO-4217)
          examples: ["EUR"]
        exchangeRate:
          description: Exchange rate for authorisation if merchant currency is different to account currency expressed as a decimal number. If merchant currency is the same as account currency, exchange rate is 1.0
          $ref: '#/components/schemas/Decimal'
        merchant:
          $ref: '#/components/schemas/Merchant'
        tokenAmount:
          description: Token amount expressed as a decimal number
          $ref: '#/components/schemas/Decimal'
        token:
          description: Token contract address
          $ref: '#/components/schemas/BlockchainAssetId'
        fees:
          type: array
          description: Fees for the transaction
          items:
            $ref: '#/components/schemas/Fee'
        chainTransactions:
          type: array
          description: On-chain transactions associated with this transaction
          items:
            $ref: '#/components/schemas/ChainTransaction'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this transaction was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this transaction was updated (ISO-8601)
    TransactionId:
      description: Unique transaction ID
      $ref: '#/components/schemas/UUID'
    TransactionStatus:
      type: string
      description: Transaction status
      enum:
        - processing
        - processed
        - reversing
        - reversed
    TransactionDirection:
      type: string
      description: Direction of the transaction
      enum:
        - debit
        - credit

    Authorisation:
      required:
        - id
        - accountId
        - status
        - amount
        - currency
        - merchantAmount
        - merchantCurrency
        - exchangeRate
        - merchant
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AuthorisationId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        cardId:
          $ref: '#/components/schemas/CardId'
        status:
          $ref: '#/components/schemas/AuthorisationStatus'
        amount:
          description: Total authorised amount expressed as a decimal number
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
          description: Currency of the account (ISO-4217)
          examples: ["EUR"]
        merchantAmount:
          description: Total authorised amount in origin (merchant) currency expressed as a decimal number
          $ref: '#/components/schemas/Decimal'
        merchantCurrency:
          type: string
          description: Origin currency of the merchant (ISO-4217)
          examples: ["EUR"]
        exchangeRate:
          description: Exchange rate for authorisation if merchant currency is different to account currency expressed as a decimal number. If merchant currency is the same as account currency, exchange rate is 1.0
          $ref: '#/components/schemas/Decimal'
        merchant:
          $ref: '#/components/schemas/Merchant'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this authorisation was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this authorisation was updated (ISO-8601)
    AuthorisationId:
      description: Unique authorisation ID
      $ref: '#/components/schemas/UUID'
    AuthorisationStatus:
      type: string
      description: Authorisation status
      enum:
        - pending
        - capturing
        - captured
        - releasing
        - released

    Blockchain:
      required:
        - id
        - name
      type: object
      properties:
        id:
          $ref: '#/components/schemas/BlockchainId'
        name:
          type: string
          description: Name of the blockchain
          examples: ["Ethereum"]

    Asset:
      required:
        - id
        - blockchain
        - name
        - symbol
      type: object
      properties:
        id:
          $ref: '#/components/schemas/BlockchainAssetId'
        blockchain:
          $ref: '#/components/schemas/BlockchainId'
        name:
          type: string
          description: Name of the asset
          examples: ["Ethereum"]
        symbol:
          type: string
          description: Symbol of the asset
          examples: ["ETH"]

    BlockchainId:
      description: Universal unique identifier of the blockchain following CAIP-2 specification
      type: string
      x-go-type: blockchain.ChainId
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/blockchain
      examples: ["eip155:1", "starknet:SN_MAIN"]

    BlockchainAccountId:
      description: Universal unique on-chain identifier of the account following CAIP-10 specification
      type: string
      x-go-type: blockchain.AccountId
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/blockchain
      examples: ["eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb", "starknet:SN_MAIN:0x02dd1b492765c064eac4039e3841aa5f382773b598097a40073bd8b48170ab57"]

    BlockchainTransactionId:
      description: Universal unique on-chain identifier of the transaction with chain identification part following CAIP-2 specification
      type: string
      x-go-type: blockchain.TransactionId
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/blockchain
      examples: ["eip155:1:0xa3847d82245abb63692bded9da859af0b73b1bfd2409502291c39795eb14954f", "starknet:SN_MAIN:0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d"]

    BlockchainAssetId:
      description: Universal unique on-chain identifier of the asset following CAIP-19 specification
      type: string
      x-go-type: blockchain.AssetId
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/blockchain
      examples: ["eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f", "starknet:SN_MAIN:0x02dd1b492765c064eac4039e3841aa5f382773b598097a40073bd8b48170ab57"]

    OwnerChallenge:
      type: object
      required:
        - challenge
      description: Cryptographic challenge generated to be signed by owner's EOA private key according to chain-specific algorithm. Challenge is used for verifying ownership of the account and signing on-chain transactions such as creating a new account, authorising a recurring payment or setting up spending limits
      properties:
        challenge:
          type: string
          format: byte
          description: Base64 encoded message provided by this API for owner to sign
          examples: ["LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="]

    OwnerSignature:
      type: object
      required:
        - ownerId
        - challenge
        - signature
      description: Cryptographic signature generated using owner's EOA private key according to chain-specific algorithm. Signature is used for signing on-chain transactions such as creating a new account, authorising a recurring payment or setting up spending limits
      properties:
        ownerId:
          description: Unique signer account ID in a form of a valid on-chain address
          $ref: '#/components/schemas/BlockchainAccountId'
        challenge:
          type: string
          format: byte
          description: Original base64 encoded challenge provided by this API for owner to sign
          examples: ["LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="]
        signature:
          type: string
          format: byte
          description: Base64 encoded signature
          examples: ["IfvwaW1eCqLvQaK0/7YjvK8HBGHWHPclHHQWH4L+w6Q3CFS8CjSzq0h8G8AhzTGMc0xRrik3TyvrDm8t1JtL9Bw="]
    
    Webhook:
      type: object
      required:
        - id
        - callbackUrl
        - types
        - createdAt
        - updatedAt
      description: Webhook details for subscribed callback URL receiving entity update events
      properties:
        id:
          $ref: '#/components/schemas/WebhookId'
        callbackUrl:
          $ref: '#/components/schemas/URL'
          description: URL to be subscribed for receiving events
        types:
          type: array
          description: Types of events to be received by the callback
          items:
            $ref: '#/components/schemas/WebhookType'
        createdAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this webhook was created (ISO-8601)
        updatedAt:
          $ref: '#/components/schemas/DateTime'
          description: Date this webhook was last updated (ISO-8601)
    WebhookId:
      description: Unique webhook ID
      $ref: '#/components/schemas/UUID'

    WebhookType:
      type: string
      description: Entity type
      enum:
        - customer.updated
        - account.updated
        - card.updated
        - authorisation.updated
        - transaction.updated

    WebhookEventBase:
      type: object
      required:
        - eventId
        - webhookType
      description: Event object representing webhook updates used in webhook callbacks
      properties: 
        eventId:
          description: Unique event ID
          $ref: '#/components/schemas/UUID'
        webhookType:
          $ref: '#/components/schemas/WebhookType'

    WebhookEvent:
      description: Event object representing webhook updates used in webhook callbacks
      oneOf: 
        - $ref: "#/components/schemas/CustomerUpdate"
        - $ref: "#/components/schemas/AccountUpdate"
        - $ref: "#/components/schemas/CardUpdate"
        - $ref: "#/components/schemas/AuthorisationUpdate"
        - $ref: "#/components/schemas/TransactionUpdate"
      discriminator:
        propertyName: webhookType
        mapping:
          customer.updated: "#/components/schemas/CustomerUpdate"
          account.updated: "#/components/schemas/AccountUpdate"
          card.updated: "#/components/schemas/CardUpdate"
          authorisation.updated: "#/components/schemas/AuthorisationUpdate"
          transaction.updated: "#/components/schemas/TransactionUpdate"
  
    CustomerUpdate:
      description: Event object representing customer update used in webhook callbacks
      allOf: 
        - $ref: '#/components/schemas/WebhookEventBase'
        - $ref: '#/components/schemas/Customer'
  
    AccountUpdate:
      description: Event object representing account update used in webhook callbacks
      allOf: 
        - $ref: '#/components/schemas/WebhookEventBase'
        - $ref: '#/components/schemas/Account'
  
    CardUpdate:
      description: Event object representing card update used in webhook callbacks
      allOf: 
        - $ref: '#/components/schemas/WebhookEventBase'
        - $ref: '#/components/schemas/Card'
  
    TransactionUpdate:
      description: Event object representing transaction update used in webhook callbacks
      allOf: 
        - $ref: '#/components/schemas/WebhookEventBase'
        - $ref: '#/components/schemas/Transaction'
  
    AuthorisationUpdate:
      description: Event object representing authorisation update used in webhook callbacks
      allOf: 
        - $ref: '#/components/schemas/WebhookEventBase'
        - $ref: '#/components/schemas/Authorisation'

    EmptyResponse:
      type: object
      description: Empty response for webhook notifications
    
    WebhookResponse:
      oneOf:
        - $ref: '#/components/schemas/EmptyResponse'

    VerificationKey:
      type: object
      required:
        - keyId
        - key
      description: Webhook verification key
      properties:
        keyId:
          $ref: '#/components/schemas/UUID'
          description: Unique ID of verification key
        key:
          type: string
          format: byte
          description: Base64 encoded public key used for verifying webhook notifications. Requirements for cryptographic algorithms and more details can be found in our documentation

    UUID:
      type: string
      format: uuid
      x-go-type: types.UUID
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/types

    Decimal:
      type: string
      format: decimal
      x-go-type: types.Decimal
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/types
      description: Decimal number
      examples: ["10.0"]

    DateTime:
      type: string
      format: date-time
      x-go-type: types.Time
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/types
      description: ISO-8601 timestamp

    URL:
      type: string
      format: uri
      x-go-type: types.URL
      x-go-type-import:
        path: github.com/offblocks/offblocks-common/types
      description: URL
      examples: ["https://example.com/callback"]

  parameters:
    SignatureHeader:
      in: header
      name: Signature
      required: true
      description: HTTP message signature
      schema:
        type: string
    SignatureInputHeader:
      in: header
      name: Signature-Input
      required: true
      description: HTTP message signature input
      schema:
        type: string
    ContentDigestHeader:
      in: header
      name: Content-Digest
      required: true
      description: Content digest
      schema:
        type: string
    IdempotencyKeyHeader:
      in: header
      name: Idempotency-Key
      required: true
      description: Idempotency key (UUID)
      schema:
        $ref: '#/components/schemas/UUID'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT