> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Transfer V2
> Initiate a transfer payout to a beneficiary.
**Validation Rules:**
- Send exactly one of `source_amount` or `destination_amount`, never both
- `source_amount` minimum: 500 cents (5.00 in major currency units)
- Attachments array is optional, but if provided must contain at least one item
This endpoint can only be used with beneficiaries created with `auto_settlement` set to `false`.
## What changed from V1
| **V1** | **V2** |
| :------------ | :---------------------------------------------------------------------- |
| `amount` | Replaced by `source_amount` and `destination_amount`. Send exactly one. |
| Not available | `source_currency`, either `USD` or `USDC`. |
| Not available | `deduct_from`, either `PREFUNDED_BALANCE` or `LIQUIDATION_ADDRESS`. |
V2 lets you fix either end of the transfer. Send `source_amount` to debit a known amount and let the beneficiary receive whatever it converts to, or send `destination_amount` to guarantee what the beneficiary receives and let the debit float. Sending both is rejected.
`deduct_from` decides where the money comes from. Only `PREFUNDED_BALANCE` transfers are eligible for refunds if they fail.
The response is unchanged from V1.
V1 remains available at `POST /v1/transactions/transfer-payout`. Transfers created on V2 must be settled with [Settle a Transfer V2](/api-reference/transactions/settle-a-transfer-v2).
## OpenAPI
````yaml POST /v2/transactions/transfer-payout
openapi: 3.1.0
info:
title: Fin.com API
version: 1.0.0
description: >-
A simple API specification for Fin.com, a financial services platform that
provides a range of banking and payment solutions for businesses and
individuals. This API allows developers to integrate Fin.com's services into
their applications, enabling functionalities such as customer management,
transaction processing, and access to financial data.
servers:
- url: https://sandbox.api.fin.com
description: Sandbox server
- url: https://api.fin.com
description: Production server
security: []
tags:
- name: Authentication
description: A modified OAuth 2.0 Client Credential Flow
- name: Customers
description: Customer management and document upload operations
- name: Balances
description: Retrieve wallet balance information
- name: Catalogue
description: |
A set of endpoints to retrieve contextual data to assemble requests
to fin.com's API
- name: Beneficiaries
description: Manage beneficiary accounts for payments and transfers
- name: Transactions
description: Transaction history and management for beneficiaries
- name: Virtual Accounts
description: Create and manage virtual accounts for USD to USDC conversions
- name: Fees & FX Rates
description: Retrieve fees and foreign exchange rates
- name: Crypto Orchestration
description: >-
Accept crypto deposits from exchange and external wallets and settle them
to a destination wallet
paths:
/v2/transactions/transfer-payout:
post:
tags:
- Transactions
summary: Create a Transfer V2
description: >
Initiate a transfer payout to a beneficiary.
**Validation Rules:**
- Send exactly one of `source_amount` or `destination_amount`, never
both
- `source_amount` minimum: 500 cents (5.00 in major currency units)
- Attachments array is optional, but if provided must contain at least
one item
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- beneficiary_id
- reference_id
- source_currency
- deduct_from
- remarks
properties:
beneficiary_id:
type: string
format: uuid
example: e710eb60-f1cd-4e70-94df-6b99a7fcf58d
reference_id:
type: string
description: Your own identifier for this transfer.
example: REF-12345-ABC
source_amount:
type: integer
minimum: 500
description: >-
Amount to debit, in cents (e.g. 850 = $8.50). Minimum 500
cents. Send this or `destination_amount`, never both.
example: 850
destination_amount:
type: integer
description: >-
Amount the beneficiary receives, in cents of the
beneficiary's currency. Send this or `source_amount`, never
both.
example: 77350
source_currency:
type: string
enum:
- USD
- USDC
description: Currency the funds are debited in.
example: USD
deduct_from:
type: string
enum:
- PREFUNDED_BALANCE
- LIQUIDATION_ADDRESS
description: >-
Where the funds are drawn from. Only `PREFUNDED_BALANCE`
transfers are eligible for refunds if they fail.
example: PREFUNDED_BALANCE
remarks:
type: string
example: Monthly payment for services
attachments:
type: array
minItems: 1
items:
type: object
required:
- remark
- uri
properties:
remark:
type: string
example: Here is the INVOICE
uri:
type: string
example: /wNXjOoqF_testdoc6.jpg
examples:
With source amount:
summary: Debit a fixed source amount
value:
beneficiary_id: e710eb60-f1cd-4e70-94df-6b99a7fcf58d
reference_id: REF-12345-ABC
source_amount: 850
source_currency: USD
deduct_from: PREFUNDED_BALANCE
remarks: Monthly payment for services
attachments:
- remark: Here is the INVOICE
uri: /wNXjOoqF_testdoc6.jpg
With destination amount:
summary: Deliver a fixed destination amount
value:
beneficiary_id: e710eb60-f1cd-4e70-94df-6b99a7fcf58d
reference_id: REF-12345-ABD
destination_amount: 77350
source_currency: USDC
deduct_from: LIQUIDATION_ADDRESS
remarks: Monthly payment for services
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: BDT
to_amount:
type: integer
example: 77350
developer_fee:
type: integer
example: 50
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'
example:
data:
transfer_id: c78dee10-7c46-4ad5-8ac8-070e39d87ff1
reference_id: REF-12345-ABC
deposit_instruction:
liquidation_address: '0x203061afd3f3dd5f5756cec992d1d247f7668384'
currency: USDC
rail: POLYGON
quotation:
currency: BDT
to_amount: 77350
developer_fee: 50
created_at: '2026-01-01T07:35:53Z'
expire_at: '2026-01-01T07:45:53Z'
'401':
$ref: '#/components/responses/AuthenticationError'
'422':
$ref: '#/components/responses/ValidationError'
security:
- bearerAuth: []
components:
responses:
AuthenticationError:
description: Authentication failed due to invalid credentials
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Authentication failed
ValidationError:
description: Failed due to a formatting error.
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
errors:
type: array
items:
type: object
additionalProperties:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer token authentication. Obtain token from [Issue a
Token](https://developer.fin.com/api-reference/authentication/issue-a-token)
endpoint
````