Fin Transactions API
Transaction history and management for beneficiaries
Transaction history and management for beneficiaries
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/fin:fin-transactions-api"
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.
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: 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)