> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get transaction

> Retrieves a transactions



## OpenAPI

````yaml https://raw.githubusercontent.com/bushaHQ/openapi/refs/heads/main/openapi-spec.yaml get /v1/transactions/{id}
openapi: 3.0.0
info:
  title: Busha API
  contact:
    email: developers@busha.co
  description: >
    ## Introduction

    The **Busha API** is designed to provide businesses with tools for
    borderless financial transactions and operations, enabling modern, global
    money management. It serves as the backbone for facilitating:

    - Creation and management of multi-currency balances

    - Retrieval of real-time cryptocurrency rates

    - Substantial data insights for business owners


    Whether you’re a product-driven fintech or a developer building
    integrations, this API significantly accelerates implementation while
    reducing financial complexities.

    For detailed guides on API integration, visit our [official
    documentation]().



    ## Authentication

    All API requests require a **Bearer Token** for authentication, passed in
    the `Authorization` header.

    Your authorization value is a base64 encoded value of your api key and your
    secret key.

    You can obtain API tokens via your Busha user or business account.
    Authentication is mandatory to ensure secure and authorized interactions
    with the API.

    The API keys from the dashboard provides a base64 encoding of the your
    authorization tokens.


    Your generated Key should look like this:

    `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=`


    Example Header:

    ``` curl

    Authorization: Bearer
    VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=

    ```


    ## Error Handling

    #Standardized error responses ensure predictable interactions. Errors are
    detailed for easy debugging and understanding:

    | **Error Code** | **HTTP Status Code** | **Description** |

    | --- | --- | --- |

    | `bad_request` | 400 | Invalid input or malformed request |

    | `unauthorized` | 401 | Invalid or missing authentication |

    | `not_found` | 404 | Resource not found |

    | `service_unavailable` | 503 | Server error |


    Basic Error Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      }
    }

    ```


    Schema Error Body Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "schema": {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
        "fix": "Ensure that the object being submitted, matches the schema correctly"
      }
    }

    ```


    Field Error Body Example:

    ``` json

    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "fields": {
        "field1": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          },
        ],
        "field2": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          }
        ],
      }
    }

    ```


    ## Pagination

    Pagination uses cursors provided as:

    The API supports **cursor-based pagination** for endpoints with large
    datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in
    the response.

    Example Response Format:

    ``` json

    {
      "current_entries_size": 10,
      "next_cursor": "base64_cursor_value",
      "previous_cursor": "base64_previous_cursor_value"
    }

    ```


    ## Rate Limiting

    Rate limits determine how many API calls can be made in a rolling minute.
    This ensures fair and optimized use of system resources.


    The rate limits allowed by each resource will be provided with the header:

    ```curl

    x-rate-limit 100

    ```

    If this header does not exist, then the rate limit is set at a default 100
    req/min


    Requests exceeding the allocated quota will receive a `429 Too Many
    Requests` response.


    ##  Common Parameters

    Common parameters enhance consistency across endpoints:
      | **Parameter Name** | **Location** | **Description** | **Example** |
      | --- | --- | --- | --- |
      | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` |
      | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` |
      | `cursor` | Query | Pagination cursor | `base64_cursor_string` |

    #### Paginated Response Example
      ``` json
      {
        "status": "success",
        "message": "Data retrieved",
        "pagination": {
          "next_cursor": "value_for_next_page",
          "current_entries_size": 20
        },
        "data": [...]
      }
      ```
  version: 1.0.0
servers:
  - url: https://api.sandbox.busha.so
    description: Sandbox Environment
  - url: https://api.busha.io
    description: Production Environment
security: []
tags:
  - name: Balances
    description: Handles account balances across different currencies.
    x-displayName: Balances
  - name: Bills
    description: Lorem Ipsum
    x-displayName: Bills
  - name: Cards
    description: Lorem Ipsum
    x-displayName: Cards
  - name: Cashback
    description: Main tag for cashback service endpoints
    x-displayName: Cashback
  - name: Currencies
    description: >
      Endpoints to manage supported currencies, their properties, and network
      details.
    x-displayName: Currencies
  - name: Customers
    x-internal: false
    description: Handle customer requests and responses
    x-displayName: Customers
  - name: Files
    description: Provides APIs to handle files upload
    x-displayName: Files
  - name: Mandate
    x-displayName: Mandate
  - name: Miscellaneous
    description: Provides auxiliary APIs to complement and enhance other services.
    x-displayName: Miscellaneous
  - name: News
    description: News article endpoints
    x-displayName: News
  - name: Pairs
    description: Access trading pair information and rates
    x-displayName: Pairs
  - name: PaymentLinks
    description: Payment Links
    x-displayName: PaymentLinks
  - name: PaymentRequests
    description: Payment request
    x-displayName: PaymentRequests
  - name: Pledges
    description: Customer-authorized pledge lifecycle APIs
    x-displayName: Pledges
  - name: PriceAlerts
    description: Price alert management endpoints
    x-displayName: PriceAlerts
  - name: Quotes
    description: Handle quotes requests and responses
    x-displayName: Quotes
  - name: Recipients
    x-displayName: Recipients
  - name: Transactions
    x-displayName: Transactions
  - name: Transfers
    x-displayName: Transfers
  - name: Widget
    description: Widget operations
    x-displayName: Widget
paths:
  /v1/transactions/{id}:
    get:
      tags:
        - Transactions
      summary: Get transaction
      description: Retrieves a transactions
      operationId: getTransaction
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Transaction'
        4XX:
          $ref: '#/components/responses/TransactionsError4XX'
        5XX:
          $ref: '#/components/responses/TransactionsError5XX'
      security:
        - Auth:
            - transactions:read
            - api:read
components:
  parameters:
    PathParamUUID:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
        x-go-type: string
      x-oapi-codegen-extra-tags:
        validate: required|uuid
    ProfileHeader:
      in: header
      name: X-BU-PROFILE-ID
      required: false
      description: User profile header
      schema:
        type: string
        example: BUS_YOK8tp5Zga01qOKEsqp07
  schemas:
    BaseSchema:
      description: General response Values
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          x-order: 1
          x-go-type: string
          enum:
            - success
            - error
          example: success
        message:
          type: string
          x-order: 2
          example: message for success
    Transaction:
      type: object
      required:
        - id
        - object
        - status
        - created_at
        - reference
        - user_id
        - profile_id
        - type
        - description
        - sub_description
        - amount
        - currency
        - is_fiat
        - is_credit
        - status_description
      properties:
        id:
          x-order: 1
          allOf:
            - $ref: '#/components/schemas/ID'
        object:
          x-order: 2
          type: string
          description: Type of the object
          example: transaction
        status:
          x-order: 3
          type: string
          description: transaction status
          enum:
            - pending
            - completed
            - failed
            - cancelled
            - processing
          example: completed
        created_at:
          x-order: 4
          type: string
          format: date-time
          description: Timestamp when the transaction was created
          example: '2024-05-16T13:06:31.409336+01:00'
        reference:
          x-order: 5
          type: string
          description: transaction reference
          example: ORD_7ain6FEDWB
        user_id:
          x-order: 6
          allOf:
            - $ref: '#/components/schemas/ID'
        profile_id:
          x-order: 7
          allOf:
            - $ref: '#/components/schemas/ID'
        type:
          x-order: 8
          allOf:
            - $ref: '#/components/schemas/TransactionTypes'
          example: buys
        description:
          x-order: 9
          type: string
          description: transaction description
          example: Bought US Dollar
        sub_description:
          x-order: 10
          type: string
          description: transaction sub_description
          example: With USD Token
        amount:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/Decimal'
        currency:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/Currency'
        is_fiat:
          x-order: 13
          type: boolean
          description: tells if transaction is in a fiat currency
        is_credit:
          x-order: 14
          type: boolean
          description: tells if transaction is a credit
        meta:
          x-order: 15
          allOf:
            - $ref: '#/components/schemas/TransactionMeta'
        status_description:
          x-order: 16
          type: string
          description: transaction status_description
          example: This has been processed by Busha
    ID:
      type: string
      x-order: 4
      example: platform_123456
      format: nanoid
      description: A valid id that supports uuid and nanoid
      x-oapi-codegen-extra-tags:
        validate: required|nanoid|string
    TransactionTypes:
      type: string
      description: transaction type
      enum:
        - buys
        - sells
        - converts
        - utilities
        - rewards
        - loans
        - savings
        - savings.withdrawals
        - savings.deposit
        - savings.interests
        - deposits
        - withdrawals
        - sends
        - receives
    Decimal:
      type: string
      description: decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
    Currency:
      type: string
      x-order: 20
      example: BTC
      format: string
      maxLength: 10
      minLength: 1
      description: A valid currency
      x-oapi-codegen-extra-tags:
        validate: required|min_len:1|max_len:10
        filter: trim|upper
    TransactionMeta:
      type: object
      description: Additional transaction metadata
      required:
        - price
        - balance
      properties:
        conversion:
          $ref: '#/components/schemas/TxnMetaConversion'
        price:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/Decimal'
            currency:
              type: string
              description: Fiat currency of user
        balance:
          type: object
          properties:
            total:
              $ref: '#/components/schemas/Decimal'
            available:
              $ref: '#/components/schemas/Decimal'
        source:
          type: object
          description: Source details (for deposits, receives)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - mobile_money
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferSource'
                - $ref: '#/components/schemas/TxnMetaMobileMoneySource'
                - $ref: '#/components/schemas/TxnMetaUsernameSource'
                - $ref: '#/components/schemas/TxnMetaEmailSource'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletSource'
        destination:
          type: object
          description: Destination details (for withdraws, sends)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - wire_transfer
                    - mobile_money
                    - paybill
                    - till
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferDestination'
                - $ref: '#/components/schemas/TxnMetaWireTransferDestination'
                - $ref: '#/components/schemas/TxnMetaMobileMoneyDestination'
                - $ref: '#/components/schemas/TxnMetaUsernameDestination'
                - $ref: '#/components/schemas/TxnMetaEmailDestination'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletDestination'
        savings:
          $ref: '#/components/schemas/TxnMetaSaving'
        service:
          $ref: '#/components/schemas/TxnMetaService'
        third_party_reference:
          type: string
          description: >-
            Reference from external payment service i.e till, paybill,
            mobile_money
        fee:
          $ref: '#/components/schemas/TxnMetaFee'
        amounts:
          $ref: '#/components/schemas/TxnMetaAmounts'
        card_charge:
          $ref: '#/components/schemas/TxnMetaCardCharge'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - name
            - message
          properties:
            name:
              type: string
              x-order: 40
              example: bad_request
            message:
              type: string
              example: Invalid Request
        fields:
          type: object
        schema:
          type: array
          items:
            type: object
      example:
        error:
          name: bad_request
          message: Invalid Request
    TxnMetaConversion:
      type: object
      properties:
        source_currency:
          type: string
          description: Currency being converted from
        source_amount:
          $ref: '#/components/schemas/Decimal'
        target_currency:
          type: string
          description: Currency being converted to
        target_amount:
          $ref: '#/components/schemas/Decimal'
        rate:
          $ref: '#/components/schemas/Decimal'
        rate_explained:
          type: string
          description: Human readable rate explanation
    TxnMetaBankTransferSource:
      type: object
      description: Bank Transfer Source
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaMobileMoneySource:
      type: object
      description: Mobile Money Source
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        paybill:
          type: string
          description: Paybill number
        till_number:
          type: string
          description: Till number
    TxnMetaUsernameSource:
      type: object
      description: Username Source
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailSource:
      type: object
      description: Email Source
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaCryptoWalletSource:
      type: object
      description: Crypto Wallet Source
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        confirmations:
          type: string
          format: integer
          description: Number of confirmations
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    TxnMetaBankTransferDestination:
      type: object
      description: Bank Transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaWireTransferDestination:
      type: object
      description: Wire transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        swift_code:
          type: string
          description: SWIFT code
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        imad:
          type: string
          description: IMAD
        routing_number:
          type: string
          description: Routing number
        address:
          type: string
          description: Address
    TxnMetaMobileMoneyDestination:
      type: object
      description: Mobile Money Destination
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        paybill:
          type: string
          description: Paybill number
        till_number:
          type: string
          description: Till number
    TxnMetaUsernameDestination:
      type: object
      description: Username Destination
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailDestination:
      type: object
      description: Email Destination
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaCryptoWalletDestination:
      type: object
      description: Crypto Wallet Destination
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    TxnMetaSaving:
      type: object
      description: Savings details
      properties:
        action:
          type: string
          description: Savings action type
          enum:
            - deposit
            - withdrawal
            - interest
        id:
          type: string
          description: Savings plan identifier
    TxnMetaService:
      type: object
      description: Service details (for utility transactions)
      properties:
        type:
          type: string
          description: Service type
          enum:
            - airtime
            - data
            - bills
            - voucher
            - betting
            - electricity
            - cable
            - card
        phone_number:
          type: string
          description: Phone number (for airtime)
        network:
          type: string
          description: Network provider
        merchant:
          type: string
          description: Merchant name (for vouchers)
        amount:
          $ref: '#/components/schemas/Decimal'
        logo_url:
          type: string
          format: uri
          description: Logo URL for the service provider
        meter_no:
          type: string
          description: Meter number (for electricity)
        account_type:
          type: string
          description: Meter account type, e.g. prepaid/postpaid (for electricity)
        smartcard_no:
          type: string
          description: Smartcard number (for cable)
        plan_name:
          type: string
          description: Subscription plan name (for cable)
        bundle:
          type: string
          description: Data bundle name (for data)
        account_no:
          type: string
          description: Account number on the biller platform (for betting)
        recipient_email:
          type: string
          description: Recipient email address (for voucher delivery)
        account_name:
          type: string
          description: >-
            Account name returned by recipient validation (for electricity,
            cable, betting)
        account_address:
          type: string
          description: Account address returned by recipient validation (for electricity)
    TxnMetaFee:
      type: object
      description: Fee details
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
          description: Currency of fee
    TxnMetaAmounts:
      description: Transactions amounts explained
      allOf:
        - type: object
          properties:
            fee:
              $ref: '#/components/schemas/Decimal'
        - oneOf:
            - $ref: '#/components/schemas/TxnMetaDepositAmounts'
            - $ref: '#/components/schemas/TxnMetaPayoutAmounts'
    TxnMetaCardCharge:
      type: object
      description: |
        Multi-currency breakdown for a card spend so the detail screen can
        render merchant local + card billing + funding amounts and the
        applicable network/platform rates without joining back to provider
        data.
      properties:
        card_scheme:
          type: string
          description: Card scheme, e.g. mastercard, visa
        card_last4:
          type: string
          description: Last four digits of the card PAN
        merchant:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What the merchant charged in their local currency
        billing:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What the card network billed the card after network FX
        funding:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What was debited from the user's funding wallet
        fee:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: Provider-charged fee in billing currency. Omitted when zero.
        total:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: billing + fee, in billing currency
        rate:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The exchange rate we applied at the time of the charge
            (funding / billing). Omitted when funding currency matches
            billing currency.
        formatted_rate:
          type: string
          description: |
            Human-readable form of `rate`, e.g. "1 USD = 1,350.05 NGN".
            Omitted when `rate` is omitted.
    TxnMetaDepositAmounts:
      type: object
      properties:
        amount_paid:
          $ref: '#/components/schemas/Decimal'
        amount_added:
          $ref: '#/components/schemas/Decimal'
    TxnMetaPayoutAmounts:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        total:
          $ref: '#/components/schemas/Decimal'
    TxnMetaMoneyAmount:
      type: object
      description: Decimal amount paired with its currency code
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
  responses:
    TransactionsError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    TransactionsError5XX:
      description: Server error when processing the transaction request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
  examples:
    DefaultError:
      description: Default error
      value:
        error:
          name: bad_request
          message: Invalid request
    NotFoundError:
      description: Not Found error
      value:
        error:
          name: resource_not_found
          message: Resource Not Found
    UnAuthorizedError:
      description: Unauthorized Error
      value:
        error:
          name: unauthorized
          message: Unauthorized request
    RequestValidationError:
      description: Request Validation error example
      value:
        error:
          name: request_validation
          message: Validation error
        fields:
          field1:
            - reason: One of target and source amount must be set
          field2:
            - reason: One of target and source amount must be set
    SchemaValidationError:
      description: Schema validation error example
      value:
        error:
          name: schema_validation
          message: Error Validating Requests
        schema:
          - reason: >-
              The request body is defined as an object. However, it does not
              meet the schema requirements of the specification
            fix: >-
              Ensure that the object being submitted, matches the schema
              correctly
            schema_validation_error:
              - 'minLength: got 3, want 12'
    InternalServerError:
      description: Internal Server Error
      value:
        error:
          name: internal_server_error
          message: Internal Server Error
    ServiceUnavailableError:
      description: Service Unavailable Error
      value:
        error:
          name: service_unavailable
          message: Service Unavailable
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: Bearer Authentication

````