Fin Transactions API

openapi: 3.1.0
info:
  title: Fin.com Authentication Transactions API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Transactions
  description: Transaction history and management for beneficiaries
paths:
  /v2/transactions:
    get:
      summary: List Customer Transactions
      description: Returns a paginated list of transactions for a customer, optionally filtered by transaction type.
      x-mint:
        content: '```

          GET /v2/transactions?customer_id=765d498e-a267-4154-9d2f-9e411a0b50dd&type=CRYPTO_WITHDRAWAL&current_page=1&per_page=10

          ```

          '
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: customer_id
        in: query
        required: true
        schema:
          type: string
        description: The customer ID to fetch transactions for.
        example: 765d498e-a267-4154-9d2f-9e411a0b50dd
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - ONRAMP
          - OFFRAMP
          - CRYPTO_WITHDRAWAL
          - CRYPTO_DEPOSIT
        description: Filter transactions by type.
        example: CRYPTO_WITHDRAWAL
      - $ref: '#/components/parameters/CurrentPageParam'
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: Number of results per page. Must be between 1 and 100.
        example: 10
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 2
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: 8c92e9dd-6456-4aee-a441-1861144f1d8b
                            transaction_type:
                              type: string
                              enum:
                              - ONRAMP
                              - OFFRAMP
                              - CRYPTO_WITHDRAWAL
                              - CRYPTO_DEPOSIT
                              example: CRYPTO_WITHDRAWAL
                            customer_id:
                              type: string
                              format: uuid
                              example: 1a8e3bdc-05c9-4486-bdef-93464d24c9af
                            beneficiary_id:
                              type: string
                              format: uuid
                              example: 6af8d598-36a5-477d-9320-d7c5ba309107
                            hash:
                              type: string
                              description: On-chain transaction hash.
                              example: '0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9'
                            status:
                              type: string
                              example: COMPLETED
                            source_currency:
                              type: string
                              example: USDC
                            destination_currency:
                              type: string
                              example: USDC
                            source_amount:
                              type: number
                              example: 5
                            destination_amount:
                              type: number
                              example: 4.98535
                            total_fee:
                              type: number
                              example: 0.014649
                            created_at:
                              type: string
                              format: date-time
                              example: '2026-04-29T09:56:14.906031Z'
                            updated_at:
                              type: string
                              format: date-time
                              example: '2026-04-29T09:56:58.631047Z'
              example:
                data:
                  pagination:
                    current_page: 1
                    per_page: 10
                    total_page: 1
                    total: 2
                  transactions:
                  - id: 8c92e9dd-6456-4aee-a441-1861144f1d8b
                    transaction_type: CRYPTO_WITHDRAWAL
                    customer_id: 1a8e3bdc-05c9-4486-bdef-93464d24c9af
                    beneficiary_id: 6af8d598-36a5-477d-9320-d7c5ba309107
                    hash: '0xd2a3d65ce04c24c7af2b4ab86ac8c3ca525d010c600733bb062be74ee3899ec9'
                    status: COMPLETED
                    source_currency: USDC
                    destination_currency: USDC
                    source_amount: 5
                    destination_amount: 4.98535
                    total_fee: 0.014649
                    created_at: '2026-04-29T09:56:14.906031Z'
                    updated_at: '2026-04-29T09:56:58.631047Z'
                  - id: 2b7b52cd-20df-4a03-83a0-bc6d989fd6ad
                    transaction_type: CRYPTO_WITHDRAWAL
                    customer_id: 1a8e3bdc-05c9-4486-bdef-93464d24c9af
                    beneficiary_id: b6a1d0c1-c202-43a8-a8c9-4d09ac5eb8f2
                    hash: '0x03eebd78faba32e5e04b03fa0e163de557d77de7e4e25b935d992964fa0b05db'
                    status: COMPLETED
                    source_currency: USDC
                    destination_currency: USDC
                    source_amount: 5.1
                    destination_amount: 4.996173
                    total_fee: 0.103826
                    created_at: '2026-04-25T20:50:34.759464Z'
                    updated_at: '2026-04-25T20:51:22.070885Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      summary: Execute Quote
      description: Executes a quote returned from the Create Quote endpoint, initiating a crypto withdrawal to the beneficiary's external wallet.
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - quote_id
              properties:
                quote_id:
                  type: string
                  format: uuid
                  description: The quote ID returned from the Create Quote endpoint.
                  example: 9ba7d6db-ac78-4a41-acae-f787ee6b1f24
            example:
              quote_id: 9ba7d6db-ac78-4a41-acae-f787ee6b1f24
      responses:
        '200':
          description: Quote executed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transaction_id:
                        type: string
                        format: uuid
                        example: 8c92e9dd-6456-4aee-a441-1861144f1d8b
                      beneficiary_id:
                        type: string
                        format: uuid
                        example: 6af8d598-36a5-477d-9320-d7c5ba309107
                      created_at:
                        type: string
                        format: date-time
                        example: '2026-04-29T09:56:14.906031567Z'
              example:
                data:
                  transaction_id: 8c92e9dd-6456-4aee-a441-1861144f1d8b
                  beneficiary_id: 6af8d598-36a5-477d-9320-d7c5ba309107
                  created_at: '2026-04-29T09:56:14.906031567Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/beneficiaries/{beneficiary_id}/transactions:
    get:
      summary: List Beneficiary Transactions
      description: Retrieve a paginated list of all transactions for a specific beneficiary
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: beneficiary_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 10
                          total_page:
                            type: integer
                            example: 1
                          total:
                            type: integer
                            example: 1
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: f656afd1-7735-43b0-b630-04f0ff7158b3
                            transaction_type:
                              type: string
                              example: OFFRAMP
                            beneficiary_id:
                              type: string
                              format: uuid
                            hash:
                              type: string
                              nullable: true
                            transaction_ref_id:
                              type: string
                            from_amount:
                              type: number
                              example: 3
                            payout_amount:
                              type: number
                              example: 4.35
                            processing_amount:
                              type: number
                              example: 3
                            status:
                              type: string
                              enum:
                              - CREATED
                              - PENDING
                              - COMPLETED
                              - FAILED
                              example: COMPLETED
                            fx_rate:
                              type: number
                              example: 1.45
                            developer_fee:
                              type: number
                              example: 0
                            developer_fee_percentage:
                              type: number
                              example: 0.45
                            developer_fee_fixed:
                              type: number
                              example: 1.25
                            from_currency:
                              type: string
                              example: USDC
                            payout_currency:
                              type: string
                              example: AUD
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/transactions/transfer-payout:
    post:
      summary: Create a Transfer
      description: 'Initiate a transfer payout to a beneficiary.


        **Validation Rules:**

        - Minimum amount: 500 cents (5.00 in major currency units)

        - Attachments array is optional, but if provided must contain at least one item

        '
      x-mint:
        content: "<Note>\n  This endpoint can only be used with beneficiaries created with `auto_settlement` set to `true`.\n</Note>\n"
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - beneficiary_id
              - reference_id
              - amount
              - remarks
              properties:
                beneficiary_id:
                  type: string
                  format: uuid
                  example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                reference_id:
                  type: string
                  example: REF-12345-ABC
                amount:
                  type: integer
                  description: Amount in cents (multiply by 100). Minimum 500 cents required.
                  example: 10000
                  minimum: 500
                remarks:
                  type: string
                  example: Monthly payment for services
                attachments:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - remark
                    - uri
                    properties:
                      remark:
                        type: string
                        example: Invoice PDF DOC
                      uri:
                        type: string
                        example: /XUOdWacK_Invoice.pdf
      responses:
        '200':
          description: Transfer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      transfer_id:
                        type: string
                        format: uuid
                        example: c78dee10-7c46-4ad5-8ac8-070e39d87ff1
                      reference_id:
                        type: string
                        example: REF-12345-ABC
                      deposit_instruction:
                        type: object
                        properties:
                          liquidation_address:
                            type: string
                            example: '0x203061afd3f3dd5f5756cec992d1d247f7668384'
                          currency:
                            type: string
                            example: USDC
                          rail:
                            type: string
                            example: POLYGON
                      quotation:
                        type: object
                        properties:
                          currency:
                            type: string
                            example: EUR
                          to_amount:
                            type: integer
                            example: 108
                          developer_fee:
                            type: integer
                            example: 67
                      created_at:
                        type: string
                        format: date-time
                        example: '2026-01-01T07:35:53Z'
                      expire_at:
                        type: string
                        format: date-time
                        example: '2026-01-01T07:45:53Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/transactions/transfer-payout/settle:
    post:
      summary: Settle a Transfer
      description: Settle a previously created transfer payout
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - transfer_id
              properties:
                transfer_id:
                  type: string
                  example: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
      responses:
        '200':
          description: Transfer settled successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - transaction_id
                    properties:
                      transaction_id:
                        type: string
                        example: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/batch/transactions/commit:
    post:
      summary: Execute Batch Transfer
      description: Execute multiple transfer payouts in a single batch operation.
      x-mint:
        content: "<Note>\n  This endpoint can only be used with beneficiaries created with `auto_settlement` set to `true`.\n</Note>\n\n**Amount Specification:**\n- Each transaction must include exactly one of `source_amount` or `destination_amount` (not both)\n- `source_amount`: Minimum 500 cents (e.g. 500 = $5.00)\n- Only `PREFUNDED_BALANCE` transactions are eligible for refunds if they fail\n"
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - beneficiary_id
                - source_currency
                - deduct_from
                properties:
                  beneficiary_id:
                    type: string
                    format: uuid
                    example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                  source_amount:
                    type: number
                    minimum: 500
                    description: Amount in cents (e.g. 530 = $5.30). Minimum 500 cents.
                    example: 530
                  destination_amount:
                    type: number
                    example: 62000
                  source_currency:
                    type: string
                    example: USD
                  deduct_from:
                    type: string
                    enum:
                    - PREFUNDED_BALANCE
                    - LIQUIDATION_ADDRESS
                  remarks:
                    type: string
                    example: Monthly salary payment
            examples:
              With source amount:
                value:
                - beneficiary_id: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                  source_amount: 530
                  source_currency: USD
                  deduct_from: PREFUNDED_BALANCE
                  remarks: Monthly salary payment
              With destination amount:
                value:
                - beneficiary_id: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                  destination_amount: 62000
                  source_currency: USD
                  deduct_from: PREFUNDED_BALANCE
                  remarks: Monthly salary payment
      responses:
        '201':
          description: Batch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 3b1d73c0-0000-0000-0000-51aa2461f1
              examples:
                With source amount:
                  value:
                    data:
                      id: 3b1d73c0-0000-0000-0000-51aa2461f1
                With destination amount:
                  value:
                    data:
                      id: 3b1d73c0-0000-0000-0000-51aa2461f1
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v1/batch/transactions/commit/{batch_id}:
    get:
      summary: Fetch Batch Details
      description: Retrieve detailed information about a batch transaction including all items and their statuses
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: ad1a0a29-5a7f-4982-98cc-3f4416724660
      responses:
        '200':
          description: Batch details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - batch_id
                    - items
                    properties:
                      batch_id:
                        type: string
                        format: uuid
                        example: ad1a0a29-5a7f-4982-98cc-3f4416724660
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            beneficiary_id:
                              type: string
                              format: uuid
                            source_amount:
                              type: number
                              example: 456
                            source_currency:
                              type: string
                              enum:
                              - USD
                            deduct_from:
                              type: string
                              enum:
                              - PREFUNDED_BALANCE
                              - LIQUIDATION_ADDRESS
                            remarks:
                              type: string
                            reason:
                              type: string
                              nullable: true
                            status:
                              type: string
                              enum:
                              - PENDING
                              - PROCESSING
                              - COMPLETED
                              - FAILED
                              - REFUNDED
                              example: PROCESSING
                            transaction_id:
                              type: string
                              format: uuid
                            exchange_rate:
                              type: number
                              example: 135
                            destination_currency:
                              type: string
                              example: BDT
                            destination_amount:
                              type: number
                              example: 261
                            developer_fee:
                              type: object
                              properties:
                                fixed:
                                  type: number
                                percentage:
                                  type: number
                                total:
                                  type: number
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v2/transactions/quote:
    post:
      summary: Create Quote
      description: Returns fee and receivable amount estimations for a crypto withdrawal from a Fin.com internal wallet to a customer's external crypto wallet.
      x-mint:
        content: "<Note>\n  The source wallet and destination wallet must share the same blockchain rail and currency. For example, if the source wallet is on POLYGON with USDC, the beneficiary's destination wallet must also be on POLYGON with USDC.\n</Note>\n"
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - beneficiary_id
              - amount
              - source
              properties:
                type:
                  type: string
                  enum:
                  - CRYPTO_WITHDRAWAL
                  description: Transaction type for the quote.
                  example: CRYPTO_WITHDRAWAL
                beneficiary_id:
                  type: string
                  format: uuid
                  description: ID of the destination beneficiary.
                  example: 6af8d598-36a5-477d-9320-d7c5ba309107
                amount:
                  type: number
                  description: Amount to send in the source currency.
                  example: 5
                source:
                  type: object
                  required:
                  - crypto_wallet_id
                  properties:
                    crypto_wallet_id:
                      type: string
                      format: uuid
                      description: ID of the Fin.com internal crypto wallet to send from.
                      example: c92dfe1d-220e-4446-a5e4-cd7d46031ba5
            example:
              type: CRYPTO_WITHDRAWAL
              beneficiary_id: 6af8d598-36a5-477d-9320-d7c5ba309107
              amount: 5
              source:
                crypto_wallet_id: c92dfe1d-220e-4446-a5e4-cd7d46031ba5
      responses:
        '200':
          description: Quote generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      quote_id:
                        type: string
                        format: uuid
                        description: Unique identifier for this quote. Use this to create a transaction.
                        example: 9ba7d6db-ac78-4a41-acae-f787ee6b1f24
                      expire_at:
                        type: string
                        format: date-time
                        description: Timestamp at which the quote expires.
                        example: '2026-04-29T10:09:33.524075766Z'
                      amount:
                        type: number
                        description: Source amount quoted.
                        example: 5
                      destination_details:
                        type: object
                        properties:
                          address:
                            type: string
                            example: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E'
                          currency:
                            type: string
                            example: USDC
                          rail:
                            type: string
                            example: POLYGON
                      quote_estimation:
                        type: object
                        properties:
                          developer_fee_fixed:
                            type: number
                            example: 0.01
                          developer_fee_percentage:
                            type: number
                            example: 0.0005
                          network_fee:
                            type: number
                            example: 0.004149
                          total_fee:
                            type: number
                            example: 0.014649
                          receivable_amount:
                            type: number
                            example: 4.98535
                          ata_fee_applied:
                            type: boolean
                            example: false
              example:
                data:
                  quote_id: 9ba7d6db-ac78-4a41-acae-f787ee6b1f24
                  expire_at: '2026-04-29T10:09:33.524075766Z'
                  amount: 5
                  destination_details:
                    address: '0xD2Ba7d0DaBd36498df5906fC7B054Fa9EfA9843E'
                    currency: USDC
                    rail: POLYGON
                  quote_estimation:
                    developer_fee_fixed: 0.01
                    developer_fee_percentage: 0.0005
                    network_fee: 0.004149
                    total_fee: 0.014649
                    receivable_amount: 4.98535
                    ata_fee_applied: false
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
  /v2/transactions/{transaction_id}:
    get:
      operationId: getTransactionByIdV2
      summary: Fetch Transaction Details V2
      description: Returns full details for a transaction by ID, including status, amounts, fees, and settlement data. The populated fields vary based on the transaction type.
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 8c92e9dd-6456-4aee-a441-1861144f1d8b
      responses:
        '200':
          description: Transaction details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    oneOf:
                    - title: Onramp
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          example: 8fe1ca7c-4e6e-44c6-8706-87ac74c22554
                        transaction_type:
                          type: string
                          example: ONRAMP
                        customer_id:
                          type: string
                          format: uuid
                          nullable: true
                          example: 80fd79d6-ad3d-4797-ad61-fc2dd1b7639d
                        beneficiary_id:
                          type: string
                          format: uuid
                          nullable: true
                          example: null
              

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-transactions-api-openapi.yml