Fin

Fin Transactions API

Transaction history and management for beneficiaries

GitHub OpenAPI

Operations 6

GET /v1/beneficiaries/{beneficiary_id}/ List Transactions for Beneficiary #
GET /v1/beneficiaries/{beneficiary_id}/transactions/{transaction_id} Fetch Transaction Details #
POST /v1/transactions/transfer-payout Create a Transfer #
POST /v1/transactions/transfer-payout/settle Settle a Transfer #
POST /v1/batch/transactions/commit Execute Batch Transfer #
GET /v1/batch/transactions/commit/{batch_id} Fetch Batch Details #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/fin:fin-transactions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

fin-transactions-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Fin.com Transactions API
  version: 1.0.0
  description: A simple API specification
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:
  /v1/beneficiaries/{beneficiary_id}/:
    get:
      summary: List Transactions for Beneficiary
      description: Retrieve paginated transaction history for a specific beneficiary
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
        description: API version
        example: v1
      - name: beneficiary_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier for the beneficiary
      - name: per_page
        in: query
        required: false
        schema:
          type: string
          default: '2'
        description: Number of transactions per page (default 10)
      - name: current_page
        in: query
        required: false
        schema:
          type: string
          default: '1'
        description: Page number to retrieve (starts from 1)
      - name: transaction_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - DEBIT
          - CREDIT
        description: Filter by transaction type
      responses:
        '200':
          description: Transaction list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                            default: 0
                          per_page:
                            type: integer
                            example: 5
                            default: 0
                          total_page:
                            type: integer
                            example: 1
                            default: 0
                          total:
                            type: integer
                            example: 1
                            default: 0
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              example: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
                            transaction_type:
                              type: string
                              example: DEBIT
                            beneficiary_id:
                              type: string
                              format: uuid
                              example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                            hash:
                              type: string
                              example: '0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2'
                            transaction_ref_id:
                              type: string
                              example: cd25866b-265a-4e39-9
                            from_amount:
                              type: integer
                              example: 3
                              default: 0
                            payout_amount:
                              type: number
                              example: 1.748682
                              default: 0
                            processing_amount:
                              type: number
                              example: 2.335
                              default: 0
                            status:
                              type: string
                              example: PENDING
                            fx_rate:
                              type: number
                              example: 0.7489
                              default: 0
                            developer_fee:
                              type: number
                              example: 0.665
                              default: 0
                            developer_fee_percentage:
                              type: number
                              example: 0.5
                              default: 0
                            developer_fee_fixed:
                              type: number
                              example: 0.65
                              default: 0
                            from_currency:
                              type: string
                              example: USDC
                            payout_currency:
                              type: string
                              example: GBP
                            created_at:
                              type: string
                              format: date-time
                              example: '2025-10-26T09:38:45.641823Z'
                            updated_at:
                              type: string
                              format: date-time
                              example: '2025-10-26T09:39:04.013728Z'
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      pagination:
                        current_page: 1
                        per_page: 5
                        total_page: 1
                        total: 1
                      transactions:
                      - id: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
                        transaction_type: DEBIT
                        beneficiary_id: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                        hash: '0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2'
                        transaction_ref_id: cd25866b-265a-4e39-9
                        from_amount: 3
                        payout_amount: 1.748682
                        processing_amount: 2.335
                        status: PENDING
                        fx_rate: 0.7489
                        developer_fee: 0.665
                        developer_fee_percentage: 0.5
                        developer_fee_fixed: 0.65
                        from_currency: USDC
                        payout_currency: GBP
                        created_at: '2025-10-26T09:38:45.641823Z'
                        updated_at: '2025-10-26T09:39:04.013728Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
      operationId: getV1BeneficiariesByBeneficiaryId
      x-operation-id-source: derived
  /v1/beneficiaries/{beneficiary_id}/transactions/{transaction_id}:
    get:
      summary: Fetch Transaction Details
      description: Retrieve detailed information for a specific transaction by transaction ID or hash
      tags:
      - Transactions
      security:
      - bearerAuth: []
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
        description: API version
        example: v1
      - name: beneficiary_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier for the beneficiary
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
        description: Transaction identifier (can be transaction ID or hash depending on 'by' parameter)
      - name: by
        in: query
        required: true
        schema:
          type: string
          enum:
          - TRX_ID
          - TRX_HASH
        description: Specify whether to query by transaction ID or the deposit transaction hash
      responses:
        '200':
          description: OK - Transaction details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        example: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
                      transaction_type:
                        type: string
                        example: DEBIT
                      beneficiary_id:
                        type: string
                        format: uuid
                        example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                      hash:
                        type: string
                        example: '0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2'
                      transaction_ref_id:
                        type: string
                        example: cd25866b-265a-4e39-9
                      from_amount:
                        type: integer
                        example: 3
                        default: 0
                      payout_amount:
                        type: number
                        example: 1.748682
                        default: 0
                      processing_amount:
                        type: number
                        example: 2.335
                        default: 0
                      status:
                        type: string
                        example: COMPLETED
                      fx_rate:
                        type: number
                        example: 0.7489
                        default: 0
                      developer_fee:
                        type: number
                        example: 0.665
                        default: 0
                      developer_fee_percentage:
                        type: number
                        example: 0.5
                        default: 0
                      developer_fee_fixed:
                        type: number
                        example: 0.65
                        default: 0
                      source_chain:
                        type: string
                        example: POLYGON
                      from_currency:
                        type: string
                        example: USDC
                      payout_currency:
                        type: string
                        example: GBP
                      created_at:
                        type: string
                        format: date-time
                        example: '2025-10-26T09:38:45.641823Z'
                      updated_at:
                        type: string
                        format: date-time
                        example: '2025-10-26T09:44:01.963307Z'
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      id: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
                      transaction_type: DEBIT
                      beneficiary_id: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                      hash: '0x58083dc1851a288496263cc1a4688a5abead5fd4f66b80516afaa27e5b3879d2'
                      transaction_ref_id: cd25866b-265a-4e39-9
                      from_amount: 3
                      payout_amount: 1.748682
                      processing_amount: 2.335
                      status: COMPLETED
                      fx_rate: 0.7489
                      developer_fee: 0.665
                      developer_fee_percentage: 0.5
                      developer_fee_fixed: 0.65
                      source_chain: POLYGON
                      from_currency: USDC
                      payout_currency: GBP
                      created_at: '2025-10-26T09:38:45.641823Z'
                      updated_at: '2025-10-26T09:44:01.963307Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
      operationId: getV1BeneficiariesByBeneficiaryIdTransactionsByTransactionId
      x-operation-id-source: derived
  /v1/transactions/transfer-payout:
    post:
      summary: Create a Transfer
      description: Initiate a transfer payout to a beneficiary
      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
                  description: Unique identifier for the beneficiary
                  example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                reference_id:
                  type: string
                  description: Unique identifier in your system
                  example: REF-12345-ABC
                amount:
                  type: integer
                  description: Amount in cents (multiply by 100)
                  example: 10000
                remarks:
                  type: string
                  description: Message for compliance purposes, if the customer needs to explain anything
                  example: Monthly payment for services
      responses:
        '200':
          description: Transfer created successfully
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: postV1TransactionsTransferPayout
      x-operation-id-source: derived
  /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
                  description: Unique identifier for the transfer to settle
                  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
                        description: Unique identifier for the settled transaction
                        example: 9ac6872b-8904-4ea5-beb7-d5a936ffee10
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: postV1TransactionsTransferPayoutSettle
      x-operation-id-source: derived
  /v1/batch/transactions/commit:
    post:
      summary: Execute Batch Transfer
      description: Execute multiple transfer payouts in a single batch operation
      tags:
      - Transactions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - beneficiary_id
                - source_amount
                - source_currency
                - deduct_from
                properties:
                  beneficiary_id:
                    type: string
                    format: uuid
                    description: Unique identifier for the beneficiary
                    example: d6ae4ea6-0482-47ab-a895-02e50ea6358b
                  source_amount:
                    type: string
                    description: Amount to transfer
                    example: '100.50'
                  source_currency:
                    type: string
                    description: Source currency code
                    example: USD
                  deduct_from:
                    type: string
                    enum:
                    - PREFUNDED_BALANCE
                    - LIQUIDATION_ADDRESS
                    description: Source of funds for the transfer
                  remarks:
                    type: string
                    description: Any remarks for the compliance team or notes for the transaction. If passing remarks are supported for a corridor then the system will automatically pass it along with the transaction
                    example: Monthly salary payment
      responses:
        '201':
          description: Batch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      batch_id:
                        type: string
                        format: uuid
                        description: Unique identifier for the batch
                        example: 16940644-438d-4134-ab19-d195dda46124
              examples:
                Created:
                  summary: Created
                  value:
                    data:
                      batch_id: 16940644-438d-4134-ab19-d195dda46124
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: postV1BatchTransactionsCommit
      x-operation-id-source: derived
  /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
        description: Unique identifier for the batch
        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
                        description: Unique identifier for the batch
                        example: ad1a0a29-5a7f-4982-98cc-3f4416724660
                      items:
                        type: array
                        items:
                          type: object
                          required:
                          - source_currency
                          - source_amount
                          - deduct_from
                          - remarks
                          - transaction_id
                          - status
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Unique identifier for the batch item
                              example: 04df867e-fc99-40b3-a159-04d6f586bb95
                            beneficiary_id:
                              type: string
                              format: uuid
                              description: Unique identifier for the beneficiary
                              example: 86236e92-b6a9-4775-9ae9-99654ba87fde
                            source_amount:
                              type: number
                              description: Source amount for the transaction
                              example: 456
                            source_currency:
                              type: string
                              enum:
                              - USD
                              description: Source currency code
                            deduct_from:
                              type: string
                              enum:
                              - PREFUNDED_BALANCE
                              - LIQUIDATION_ADDRESS
                              description: Source of funds for the transaction
                            remarks:
                              type: string
                              description: Transaction remarks
                              example: auto settle false CAN
                            reason:
                              type: string
                              nullable: true
                              description: Reason for status (if applicable)
                            status:
                              type: string
                              enum:
                              - PENDING
                              - PROCESSING
                              - COMPLETED
                              - FAILED
                              - REFUNDED
                              description: Current status of the transaction
                              example: PROCESSING
                            transaction_id:
                              type: string
                              format: uuid
                              description: Unique identifier for the transaction
                              example: d6ae5ea0-3817-4740-bf04-05aec73e7b80
              examples:
                OK:
                  summary: OK
                  value:
                    data:
                      batch_id: ad1a0a29-5a7f-4982-98cc-3f4416724660
                      items:
                      - id: 04df867e-fc99-40b3-a159-04d6f586bb95
                        beneficiary_id: 86236e92-b6a9-4775-9ae9-99654ba87fde
                        source_amount: 456
                        source_currency: USD
                        deduct_from: PREFUNDED_BALANCE
                        remarks: auto settle false CAN
                        reason: null
                        status: PROCESSING
                        transaction_id: d6ae5ea0-3817-4740-bf04-05aec73e7b80
                      - id: d4247163-75d0-4ae0-90da-21cdedbc4453
                        beneficiary_id: 921ee210-4e5c-481e-b15a-69d036886598
                        source_amount: 289
                        source_currency: USD
                        deduct_from: PREFUNDED_BALANCE
                        remarks: auto settle true CAN
                        reason: null
                        status: PROCESSING
                        transaction_id: 6b7e6286-a361-47e3-aef3-3385071b166b
                      - id: a3847f4d-47b5-489a-8f4e-21ef67b7e78d
                        beneficiary_id: 12901f5e-2fd6-4cc7-9bd5-f7a4c092b87a
                        source_amount: 373
                        source_currency: USD
                        deduct_from: PREFUNDED_BALANCE
                        remarks: auto settle true CAN
                        reason: null
                        status: PROCESSING
                        transaction_id: 1be9d918-77b1-448d-b97d-c309f4389721
                      - id: 3678c596-bf2e-486a-a09a-1124f6486e73
                        beneficiary_id: 8faa89dc-9528-4aa0-9331-89b8b81f6560
                        source_amount: 199
                        source_currency: USD
                        deduct_from: PREFUNDED_BALANCE
                        remarks: auto settle false CAN
                        reason: null
                        status: PROCESSING
                        transaction_id: 116f4dc8-6288-43e2-b20e-5414a7f6d7b7
        '401':
          $ref: '#/components/responses/AuthenticationError'
      operationId: getV1BatchTransactionsCommitByBatchId
      x-operation-id-source: derived
components:
  responses:
    ValidationError:
      description: Failed due to a formatting error.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            properties:
              message:
                type: string
                description: An error message describing what went wrong.
              errors:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string
                    example: Appropriate client_secret required.
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: The error message
                example: Authentication failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication. Obtain token from /v1/oauth/token endpoint
x-provenance:
  method: harvested
  publisher: Fin
  source: https://developer.fin.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)