openapi: 3.0.1
info:
  title: Okra API
  description: >-
    Specification of the Okra open-finance API. Okra connected applications to
    Nigerian bank accounts to retrieve authentication details, balances,
    transactions, identity, and income, and to initiate bank-to-bank payments.
    All product and query endpoints are POST requests authenticated with a
    Bearer secret key. NOTE: Okra wound down operations in May 2025; endpoints
    are documented as they were publicly published and may no longer be live.
  termsOfService: https://okra.ng/terms
  contact:
    name: Okra Support
    email: support@okra.ng
  version: '2.0'
servers:
  - url: https://api.okra.ng/v2
    description: Production
  - url: https://api.okra.ng/v2/sandbox
    description: Sandbox
security:
  - bearerAuth: []
tags:
  - name: Auth
    description: Account authentication records and Link.
  - name: Balance
    description: Account balances.
  - name: Accounts
    description: Linked bank accounts.
  - name: Transactions
    description: Transaction history and spending patterns.
  - name: Identity
    description: KYC identity on file with the bank.
  - name: Income
    description: Income verification.
  - name: Payments
    description: Bank-to-bank payments.
  - name: Webhooks
    description: Callback management.
paths:
  /products/auths:
    post:
      operationId: getAuths
      tags:
        - Auth
      summary: Retrieve all auth records
      description: >-
        Returns authentication records (account and NUBAN numbers across
        current, savings, and domiciliary accounts) for all of your customers,
        optionally as a PDF.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/getById:
    post:
      operationId: getAuthById
      tags:
        - Auth
      summary: Retrieve an auth record by id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/getByCustomer:
    post:
      operationId: getAuthByCustomer
      tags:
        - Auth
      summary: Retrieve auth records by customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/getByDate:
    post:
      operationId: getAuthByDate
      tags:
        - Auth
      summary: Retrieve auth records by date range
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DateRangeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/getByBank:
    post:
      operationId: getAuthByBank
      tags:
        - Auth
      summary: Retrieve auth records by bank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/balances:
    post:
      operationId: getBalances
      tags:
        - Balance
      summary: Retrieve all balance records
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /balance/getById:
    post:
      operationId: getBalanceById
      tags:
        - Balance
      summary: Retrieve a balance record by id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /balance/getByCustomer:
    post:
      operationId: getBalanceByCustomer
      tags:
        - Balance
      summary: Retrieve balances by customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /balance/getByAccount:
    post:
      operationId: getBalanceByAccount
      tags:
        - Balance
      summary: Retrieve balances by account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /balance/getByType:
    post:
      operationId: getBalanceByType
      tags:
        - Balance
      summary: Retrieve balances by type and value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceTypeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/accounts:
    post:
      operationId: getAccounts
      tags:
        - Accounts
      summary: Retrieve all linked accounts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/transactions:
    post:
      operationId: getTransactions
      tags:
        - Transactions
      summary: Retrieve all transaction records
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transaction/getByCustomer:
    post:
      operationId: getTransactionsByCustomer
      tags:
        - Transactions
      summary: Retrieve transactions by customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transaction/getByAccount:
    post:
      operationId: getTransactionsByAccount
      tags:
        - Transactions
      summary: Retrieve transactions by account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transaction/getByDate:
    post:
      operationId: getTransactionsByDate
      tags:
        - Transactions
      summary: Retrieve transactions by date range
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DateRangeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transaction/getByBank:
    post:
      operationId: getTransactionsByBank
      tags:
        - Transactions
      summary: Retrieve transactions by bank
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/transactions/spending-pattern:
    post:
      operationId: getSpendingPattern
      tags:
        - Transactions
      summary: Retrieve a customer's spending pattern
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  description: The Okra customer id.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/identities:
    post:
      operationId: getIdentities
      tags:
        - Identity
      summary: Retrieve all identity records
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /identity/getById:
    post:
      operationId: getIdentityById
      tags:
        - Identity
      summary: Retrieve an identity record by id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /identity/getByCustomer:
    post:
      operationId: getIdentityByCustomer
      tags:
        - Identity
      summary: Retrieve identity by customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /identity/getByDate:
    post:
      operationId: getIdentityByDate
      tags:
        - Identity
      summary: Retrieve identity records by date range
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DateRangeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/income:
    post:
      operationId: getIncome
      tags:
        - Income
      summary: Retrieve income records
      description: >-
        Returns income verification data derived from a record's connected
        accounts, optionally as a PDF.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfFlagRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /income/getByCustomer:
    post:
      operationId: getIncomeByCustomer
      tags:
        - Income
      summary: Retrieve income by customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/pay:
    post:
      operationId: initiatePayment
      tags:
        - Payments
      summary: Initiate a bank-to-bank payment
      description: >-
        Creates an instant one-time bank-to-bank payment (debit) from a
        customer's connected account to a configured beneficiary account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pay/verify:
    post:
      operationId: verifyPayment
      tags:
        - Payments
      summary: Verify a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payment_id
              properties:
                payment_id:
                  type: string
                  description: The Okra payment id to verify.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pay/getById:
    post:
      operationId: getPaymentById
      tags:
        - Payments
      summary: Retrieve a payment by id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /callback/trigger:
    post:
      operationId: triggerCallback
      tags:
        - Webhooks
      summary: Re-trigger webhook callbacks
      description: >-
        Re-triggers webhook callbacks for the supplied record ids, optionally
        redirecting the callbacks to a different URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recordIds
              properties:
                recordIds:
                  type: array
                  items:
                    type: string
                  description: Record ids to re-trigger callbacks for.
                url:
                  type: string
                  format: uri
                  description: Optional URL to redirect the webhooks to.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Okra secret API key supplied as a Bearer token.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PdfFlagRequest:
      type: object
      properties:
        pdf:
          type: boolean
          default: false
          description: When true, return the records rendered as a PDF.
    IdRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The Okra record id.
    CustomerRequest:
      type: object
      required:
        - customer
      properties:
        customer:
          type: string
          description: The Okra customer id.
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 20
    AccountRequest:
      type: object
      required:
        - account
      properties:
        account:
          type: string
          description: The Okra account id.
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 20
    BankRequest:
      type: object
      required:
        - bank
      properties:
        bank:
          type: string
          description: The Okra bank id.
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 20
    DateRangeRequest:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date
          description: Start date (YYYY-MM-DD).
        to:
          type: string
          format: date
          description: End date (YYYY-MM-DD).
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 20
    BalanceTypeRequest:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          description: The balance type to filter on (e.g. available, ledger).
        value:
          type: number
          description: The threshold value to compare against.
        page:
          type: integer
          default: 1
        limit:
          type: integer
          default: 20
    PaymentRequest:
      type: object
      required:
        - amount
        - currency
        - account
      properties:
        amount:
          type: number
          description: Amount to debit, in the smallest currency unit.
        currency:
          type: string
          default: NGN
        account:
          type: string
          description: Source account id to debit.
        customer:
          type: string
          description: Customer id the payment is for.
        callback_url:
          type: string
          format: uri
          description: URL to receive the payment webhook callback.
    Pagination:
      type: object
      properties:
        totalPages:
          type: integer
        currentPage:
          type: integer
        nextPage:
          type: integer
        previousPage:
          type: integer
        total:
          type: integer
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        nuban:
          type: string
        type:
          type: string
        bank:
          type: string
        currency:
          type: string
    Balance:
      type: object
      properties:
        id:
          type: string
        account:
          type: string
        customer:
          type: string
        ledger_balance:
          type: number
        available_balance:
          type: number
        currency:
          type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        account:
          type: string
        customer:
          type: string
        amount:
          type: number
        type:
          type: string
        notes:
          type: string
        trans_date:
          type: string
          format: date-time
    Identity:
      type: object
      properties:
        id:
          type: string
        customer:
          type: string
        fullname:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          type: string
        bvn:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        currency:
          type: string
        status:
          type: string
        account:
          type: string
        customer:
          type: string
    GenericResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          additionalProperties: true
    AuthListResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            auths:
              type: array
              items:
                $ref: '#/components/schemas/Account'
            pagination:
              $ref: '#/components/schemas/Pagination'
    AccountListResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            accounts:
              type: array
              items:
                $ref: '#/components/schemas/Account'
            pagination:
              $ref: '#/components/schemas/Pagination'
    BalanceListResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            balances:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
            pagination:
              $ref: '#/components/schemas/Pagination'
    TransactionListResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            transaction:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
            pagination:
              $ref: '#/components/schemas/Pagination'
    IdentityListResponse:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            identity:
              type: array
              items:
                $ref: '#/components/schemas/Identity'
            pagination:
              $ref: '#/components/schemas/Pagination'
    PaymentResponse:
      type: object
      properties:
        status:
          type: string
        data:
          $ref: '#/components/schemas/Payment'
    Error:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string