openapi: 3.2.0
info:
  title: Zepto Bank Accounts API
  contact:
    email: support@zepto.com.au
  description: Zepto allows you to make, get and manage payments using nothing but bank accounts.
  version: '1.0'
servers:
- url: https://api.sandbox.zeptopayments.com
  description: Sandbox API server
- url: https://api.zeptopayments.com
  description: Production API server
security:
- bearerAuth: []
tags:
- name: Bank Accounts
  description: 'Your currently linked up bank accounts.

    '
paths:
  /bank_accounts:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    get:
      tags:
      - Bank Accounts
      summary: List all Bank Accounts
      description: 'By default, all Bank Accounts will be returned.

        '
      operationId: ListAllBankAccounts
      responses:
        '200':
          description: OK
          headers:
            Link:
              $ref: '#/components/headers/Link'
            Per-Page:
              $ref: '#/components/headers/Per-Page'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllBankAccountsResponse'
  /bank_accounts/{id}:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    get:
      tags:
      - Bank Accounts
      summary: Get a Bank Account
      description: Returns a specified Bank or Float Account owned by your account. For a Float Account, the response includes its current `available_balance`.
      operationId: GetABankAccount
      parameters:
      - name: id
        in: path
        description: Bank Account ID (`BankAccount.data.id`), single value, exact match
        required: true
        style: simple
        schema:
          type: string
          format: uuid
        example: ab3de19b-709b-4a41-82a5-3b43b3dc58c9
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetABankAccountResponse'
        '403':
          description: Forbidden - the access token does not have the `bank_accounts` scope
        '404':
          description: Not Found - the Bank Account is unavailable or is not owned by the authenticated account
  /bank_accounts/{bank_account_id}/entries:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    get:
      tags:
      - Bank Accounts
      summary: List Float Account entries
      description: 'Lists the settled ledger entries applied to a Float Account. Transactions and Transfers describe business operations; entries describe what was posted to this Float Account and changed its available balance. An entry may result from a payment, transfer, refund, recovery, return, fee, or manual adjustment, making this endpoint the complete account-level record within the availability window for reconciliation.


        Float Account entries are available through this API for a rolling 24-month period, calculated from the time of the request. Entries created before the start of that window are not returned. Requests with either created-at filter before the start of the window return `422 Unprocessable Entity`.


        Entries are returned in descending order by `created_at` and then `id`. The ID is a deterministic tie-breaker; entries with the same timestamp are not guaranteed to be returned in their original balance-application order.


        `amount` is expressed in cents. Positive values credit the Float Account and negative values debit it.'
      operationId: ListFloatAccountEntries
      parameters:
      - name: bank_account_id
        in: path
        description: Bank Account ID (`BankAccount.data.id`), single value, exact match
        required: true
        style: simple
        schema:
          type: string
          format: uuid
        example: ab3de19b-709b-4a41-82a5-3b43b3dc58c9
      - name: min_created_date
        in: query
        description: Filter by minimum `created_at`. The value must not be earlier than the start of the rolling 24-month availability window. Date/time UTC ISO 8601 format, single value, exact match.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-07-01T00:00:00Z'
      - name: max_created_date
        in: query
        description: Filter by maximum `created_at`. The value must not be earlier than the start of the rolling 24-month availability window. Date/time UTC ISO 8601 format, single value, exact match.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-07-31T23:59:59Z'
      - name: per_page
        in: query
        description: Number of entries to return. Defaults to 20 and is constrained to 1–100.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 20
      - name: starting_after
        in: query
        description: ID of the final entry from the previous page. Return the value from the `Link` header unchanged.
        required: false
        schema:
          type: string
          format: uuid
        example: 019c8814-c767-753c-82f7-3daac44d8662
      responses:
        '200':
          description: OK
          headers:
            Link:
              schema:
                type: string
              description: Contains the next-page URL when another page exists
              example: </bank_accounts/ab3de19b-709b-4a41-82a5-3b43b3dc58c9/entries?per_page=20&starting_after=019c8814-c767-753c-82f7-3daac44d8662>; rel="next"
            Per-Page:
              schema:
                type: integer
              description: Contains the maximum number of entries requested for this page. Defaults to 20.
              example: 20
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFloatAccountEntriesResponse'
        '400':
          description: Bad Request - `per_page` is not an integer
        '403':
          description: Forbidden - the access token does not have the `bank_accounts` scope
        '404':
          description: Not Found - the Bank Account is unavailable or is not a Float Account
        '422':
          description: Unprocessable Entity - `starting_after` is not an available entry in this Float Account, or a `created_at` filter is invalid or outside the rolling 24-month availability window
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      required:
                      - title
                      - detail
                      properties:
                        title:
                          type: string
                        detail:
                          type: string
              examples:
                Minimum created date outside availability window:
                  value:
                    errors:
                    - title: Validation Failed
                      detail: min_created_date must not be earlier than the start of the 24-month availability window
                Maximum created date outside availability window:
                  value:
                    errors:
                    - title: Validation Failed
                      detail: max_created_date must not be earlier than the start of the 24-month availability window
  /bank_accounts/{bank_account_id}/entries/{entry_id}:
    parameters:
    - $ref: '#/components/parameters/ZeptoAPIVersion'
    get:
      tags:
      - Bank Accounts
      summary: Get a Float Account entry
      description: 'Gets one settled entry applied to a Float Account.


        Float Account entries are available through this API for a rolling 24-month period, calculated from the time of the request.'
      operationId: GetFloatAccountEntry
      parameters:
      - name: bank_account_id
        in: path
        description: Bank Account ID (`BankAccount.data.id`), single value, exact match
        required: true
        style: simple
        schema:
          type: string
          format: uuid
        example: ab3de19b-709b-4a41-82a5-3b43b3dc58c9
      - name: entry_id
        in: path
        description: Float Account entry ID (`FloatAccountEntry.data.id`), single value, exact match
        required: true
        style: simple
        schema:
          type: string
          format: uuid
        example: 019c8814-c767-753c-82f7-3daac44d8662
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFloatAccountEntryResponse'
        '403':
          description: Forbidden - the access token does not have the `bank_accounts` scope
        '404':
          description: Not Found - the Bank Account or entry is unavailable, the entry is outside the rolling 24-month availability window, or the Bank Account is not a Float Account
components:
  headers:
    Per-Page:
      schema:
        type: integer
      description: Contains the current maximum items in collection. Defaults to 25
      example: 25
    Link:
      schema:
        type: string
      description: Contains pagination link for next page of collection, if next page exists.
      example: <https://api.sandbox.zeptopayments.com/contacts?page=2>; rel="next"
  schemas:
    GetABankAccountResponse:
      title: Get a Bank Account (response)
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BankAccount'
      example:
        data:
          id: ab3de19b-709b-4a41-82a5-3b43b3dc58c9
          account_type: float_account
          branch_code: '802919'
          bank_name: Zepto Float Account
          account_number: '1748212'
          status: active
          title: Float Account
          available_balance: 10000
          payid_configs:
          - email_domain: pay.zepto.com.au
            pooling_state: disabled
            max_pool_size: 10
            current_pool_size: 1
    GetFloatAccountEntryResponse:
      title: Get a Float Account entry (response)
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/FloatAccountEntry'
    FloatAccountEntry:
      title: Float Account entry
      type: object
      required:
      - id
      - created_at
      - description
      - amount
      - available_balance_after
      - links
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the entry
        created_at:
          type: string
          format: date-time
          description: Date and time in UTC when the entry was applied to the Float Account
        description:
          type: string
          description: Description recorded for the entry
        amount:
          type: integer
          format: int64
          description: Signed amount in cents. Positive values are credits and negative values are debits.
        available_balance_after:
          type: integer
          format: int64
          description: Available balance in cents immediately after this entry was applied
        links:
          type: object
          required:
          - self
          properties:
            self:
              type: string
              format: uri
              description: Canonical URL for this entry
      example:
        id: 019c8814-c767-753c-82f7-3daac44d8662
        created_at: '2026-07-21T01:27:50Z'
        description: CT.1uou2c
        amount: -1250
        available_balance_after: 84750
        links:
          self: https://api.sandbox.zeptopayments.com/bank_accounts/ab3de19b-709b-4a41-82a5-3b43b3dc58c9/entries/019c8814-c767-753c-82f7-3daac44d8662
    ListAllBankAccountsResponse:
      title: List all Bank Accounts (response)
      required:
      - data
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
          description: ''
      example:
        data:
        - id: 6a7ed958-f1e8-42dc-8c02-3901d7057357
          account_type: bank_account
          branch_code: '493192'
          bank_name: National Australia Bank
          account_number: '3993013'
          status: active
          title: AU.493192.3993013
          available_balance: null
        - id: 56df206a-aaff-471a-b075-11882bc8906a
          account_type: bank_account
          branch_code: '302193'
          bank_name: National Australia Bank
          account_number: '119302'
          status: active
          title: Trust Account
          available_balance: null
        - id: ab3de19b-709b-4a41-82a5-3b43b3dc58c9
          account_type: float_account
          branch_code: '802919'
          bank_name: Zepto Float Account
          account_number: '1748212'
          status: active
          title: Float Account
          available_balance: 10000
          payid_configs:
          - email_domain: pay.zepto.com.au
            pooling_state: disabled
            max_pool_size: 10
            current_pool_size: 1
    ListFloatAccountEntriesResponse:
      title: List Float Account entries (response)
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FloatAccountEntry'
    BankAccount:
      title: Bank Account
      type: object
      required:
      - account_type
      properties:
        id:
          type: string
          format: uuid
          description: Unique Bank Account ID
        account_type:
          type: string
          description: Distinguishes Float Accounts from other Bank Accounts
          enum:
          - bank_account
          - float_account
        branch_code:
          type: string
          description: Bank State Branch code
        bank_name:
          type: string
          description: Name of the financial institution
        account_number:
          type: string
          description: Bank account number
        status:
          type: string
          description: Current Bank Account status
          enum:
          - active
          - removed
        title:
          type: string
          description: Display title for the Bank Account
        available_balance:
          type:
          - integer
          - 'null'
          format: int64
          description: Current available balance in cents for a Float Account; null for other Bank Accounts
        payid_configs:
          type: array
          description: PayID pooling configurations associated with the Float Account
          items:
            type: object
            properties:
              email_domain:
                type: string
              pooling_state:
                type: string
                enum:
                - disabled
                - enabled
                - paused
              max_pool_size:
                type: integer
              current_pool_size:
                type: integer
  parameters:
    ZeptoAPIVersion:
      name: Zepto-API-Version
      in: header
      required: false
      schema:
        type: string
        pattern: ^\d{8}$
        default: '20250101'
        example: '20260101'
      description: API version in YYYYMMDD format. Defaults to 20250101 (legacy) when omitted.
  securitySchemes:
    bearerAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            public: Access your public information
            contacts: Manage your contacts
            payments: Manage your payments
            payment_requests: Manage your payment requests
            refunds: Manage your refunds
            agreements: Manage your agreements
            transactions: Access your transaction history
            open_agreements: Manage your open agreements
            transfers: Manage your Transfers