Yokoy Transaction API

openapi: 3.0.0
info:
  description: Public API of the Yokoy Application
  title: Yokoy Card account Transaction API
  version: 1.41.0
servers:
- description: API server scoped to organization with ID `organizationId`
  url: https://api.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
- description: API test server scoped to organization with ID `organizationId`
  url: https://api.test.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
tags:
- description: 'A transaction is a cleared payment that is made using a credit, debit, or prepaid card. The card issuer can be either Yokoy or a third party that has been integrated with Yokoy.

    '
  name: Transaction
paths:
  /transactions:
    get:
      description: Retrieves all transactions for the organization.
      operationId: listTransactions
      parameters:
      - $ref: '#/components/parameters/QueryFilter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  transactions:
                    items:
                      $ref: '#/components/schemas/Transaction'
                    type: array
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/InvalidFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: List all transactions
      tags:
      - Transaction
    post:
      description: Creates a new card transaction in Yokoy that is associated with a specific company card, scoped to a legal entity.
      operationId: addTransaction
      parameters:
      - $ref: '#/components/parameters/YokoyAuthMethod'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
          description: OK.
        '400':
          description: The request was not valid.
        '401':
          description: The server was unable to establish the identity of the client.
        '409':
          description: Unable to process the request.
        '429':
          description: The request cannot be processed by the server due to too many concurrent requests.
      summary: Create a card transaction
      tags:
      - Transaction
  /transactions/{transactionId}:
    get:
      description: Retrieves a transaction identified by its unique ID.
      operationId: getTransaction
      parameters:
      - description: Yokoy unique ID of the transaction.
        example: aB9jQoE3HE
        in: path
        name: transactionId
        required: true
        schema:
          pattern: '[\w-]+'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Get transaction by ID
      tags:
      - Transaction
components:
  schemas:
    Transaction:
      properties:
        billingAmount:
          description: Amount of the transaction, expressed in the billing currency.
          example: '23.88'
          exclusiveMinimum: true
          minimum: 0
          type: number
        billingCurrency:
          description: Billing currency of the transaction. ISO 4217 three-letter code.
          example: EUR
          pattern: \W{3}
          type: string
        bookingDate:
          description: Date when the transaction was booked, also known as posting date. Expressed in ISO 8601 format. Coordinated Universal Time (UTC).
          example: '2025-02-24T15:38:02Z'
          format: date-time
          nullable: true
          type: string
        cardId:
          description: Yokoy unique ID of the card to which the transaction is associated.
          example: Y6c2p3G0x
          pattern: '[\w-]+'
          type: string
        country:
          description: Code of the country where the transaction took place. Expressed as an ISO 3166 Alpha-2 code.
          example: CH
          nullable: true
          pattern: \W{2}
          type: string
        created:
          description: Timestamp (date and time) when the transaction was created. Expressed in ISO 8601 format. Coordinated Universal Time (UTC).
          example: '2025-03-01T11:08:45.478Z'
          format: date-time
          readOnly: true
          type: string
        expenseId:
          description: Yokoy unique ID of the expense to which the transaction is associated.
          example: aB9jQoE3HE
          nullable: true
          pattern: '[\w-]+'
          readOnly: true
          type: string
        expenseStatus:
          description: "Read-only field.\nWhenever a transaction is matched to an expense, this attribute indicates the status of the associated expense:\n - `0`: Expense is not ready for export.\n - `1`: Expense is ready for export.\n - `2`: Expense is exported.\n"
          enum:
          - 0
          - 1
          - 2
          example: 1
          nullable: true
          readOnly: true
          type: number
        id:
          description: Yokoy unique ID of a transaction.
          example: 2OAxBAFT9
          pattern: '[\w-]+'
          readOnly: true
          type: string
        isCreditNote:
          description: Indicates whether the transaction is a credit note or a refund.
          nullable: false
          type: boolean
        legalEntityId:
          description: Yokoy unique ID of the legal entity to which the transaction is assigned.
          example: wrOWz6e_33I0vNzQPMWyY
          pattern: '[\w-]+'
          type: string
        matchingStatus:
          description: "Indicates whether a transaction document is matched with an expense document.\n - `0`: Transaction is not matched.\n - `1`: Transaction is matched.\n - `2`: [deprecated] Transaction is private.\n - `5`: Transaction is archived. Archived transactions cannot be matched against expenses and are ignored by Yokoy in auto-matching.\n"
          enum:
          - 0
          - 1
          - 2
          - 5
          example: 1
          readOnly: true
          type: number
        mccSicCode:
          description: Merchant category transaction classification. ISO 18245.
          example: '9999'
          nullable: true
          pattern: \d{4}
          type: string
        merchant:
          description: Merchant or description of the transaction.
          example: Store XYZ. Street 0, City, Country
          pattern: '[\w-]+'
          type: string
        sourceAmount:
          description: Amount of the transaction, expressed in the source currency.
          example: '25.00'
          exclusiveMinimum: true
          minimum: 0
          nullable: true
          type: number
        sourceCurrency:
          description: Source currency of the transaction (i.e. a foreign currency). ISO 4217 three-letter code.
          example: USD
          nullable: true
          pattern: \W{3}
          type: string
        statementReference:
          description: External reference to the associated statement. Depending on the provider, this information may or may not be provided. Not available for Yokoy's Platinum Visa and Business Mastercard products.
          example: abc_ABC-09
          pattern: '[\w-]+'
          readOnly: true
          type: string
        transactionDate:
          description: Date when the transaction occurred. Expressed in `YYYY-MM-DD` format.
          example: '2025-02-24'
          pattern: \d{4}-\d{2}-\d{2}
          type: string
      required:
      - transactionDate
      - legalEntityId
      - cardId
      - merchant
      - billingAmount
      - billingCurrency
      type: object
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
  parameters:
    QueryFilter:
      description: Filter string used to restrict the data returned. You can use [SCIM specification](https://tools.ietf.org/html/rfc7644#section-3.4.2.2) filters.
      example: created ge 2024-03-02T09:00.000Z and customInformation.customField eq foo
      in: query
      name: filter
      schema:
        type: string
    YokoyAuthMethod:
      example: yokoy
      in: header
      name: X-Yk-Auth-Method
      required: true
      schema:
        enum:
        - yokoy
        type: string
  responses:
    Forbidden:
      content:
        application/json:
          example:
            code: 403
            message: User not authorized to access organization
          schema:
            $ref: '#/components/schemas/Error'
      description: The client is not authorized to perform the requested operation.
    Unauthorized:
      content:
        application/json:
          example:
            code: 401
            message: Token expired
          schema:
            $ref: '#/components/schemas/Error'
      description: The server was unable to establish the identity of the client.
    InvalidFilter:
      content:
        application/json:
          example:
            code: 400
            message: 'Invalid filter string: foo e bar'
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was not valid.
    TooManyRequests:
      content:
        application/json:
          example:
            code: 429
            message: Too many requests
          schema:
            $ref: '#/components/schemas/Error'
      description: The request cannot be processed by the server due to too many concurrent requests.
    InternalError:
      content:
        application/json:
          example:
            code: 500
            message: Server error
          schema:
            $ref: '#/components/schemas/Error'
      description: An internal error occurred.
    NotFound:
      content:
        application/json:
          example:
            code: 404
            message: Resource not found
          schema:
            $ref: '#/components/schemas/Error'
      description: The specified resource was not found.
    GatewayError:
      content:
        application/json:
          example:
            code: 502
            message: Gateway error
          schema:
            $ref: '#/components/schemas/Error'
      description: An issue occurred in a downstream service. Please try again later.
    ServiceUnavailable:
      content:
        application/json:
          example:
            code: 503
            message: Service unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: The server is unavailable. Please try again later
  securitySchemes:
    OAuth2:
      description: "Authentication to the Yokoy API relies on the standard OAuth2 client credentials flow.\n\n**1. Obtain an access token**\n\nPerform a `POST` request to\n`https://accounts.yokoy.ai/oauth2/token`. Pass the client ID\nand client secret as username and password in a basic auth\nheader. Set the content-type to\n`application/x-www-form-urlencoded` and specify\n`grant_type=client_credentials` in the body.\n\n> Note: For the Yokoy test environment, use `https://accounts.test.yokoy.ai/oauth2/token` instead.\n\nExample request for the client ID `ClientId` and client\nsecret `ClientSecret`:\n```\nPOST https://accounts.yokoy.ai/oauth2/token\nAuthorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0\nContent-Type: application/x-www-form-urlencoded\ngrant_type=client_credentials\n```\nIn this example, the string `Q2xpZW50SWQ6Q2xpZW50U2VjcmV0` is\nobtained by base64-encoding the string\n`ClientId:ClientSecret`, as required for basic access authentication.\n\n> Note: Yokoy does not require or use scopes.\n\n\nThe JSON response contains the access token in the attribute\n`access_token`. The response also contains the expiration in\nseconds.\n\nExample response:\n```\n{\n    \"access_token\": \"SOME_KEY\",\n    \"expires_in\": 3900,\n    \"token_type\": \"Bearer\"\n}\n```\n\n**2. Pass the bearer token**\n\nPass the access token from step 1 as a bearer token in subsequent requests to the API.\n\nExample header field for the example response from step 1:\n```\nAuthorization: Bearer 4lDvPkrBF87WHuyvlINQD\n```\n\nFor more information, see (Authentication & authorization)[https://developer.yokoy.ai/docs/overview/authentication].\n"
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://accounts[.test].yokoy.ai/oauth2/token
      type: oauth2