Create a Transfer V2

POST

transactions

transfer-payout

curl --request POST \
  --url https://sandbox.api.fin.com/v2/transactions/transfer-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "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"
  }
}

{
  "message": "Authentication failed"
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

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.

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Body

application/json

beneficiary_id

string<uuid>

required

Example:

"e710eb60-f1cd-4e70-94df-6b99a7fcf58d"

reference_id

string

required

Your own identifier for this transfer.

Example:

"REF-12345-ABC"

source_currency

enum<string>

required

Currency the funds are debited in.

Available options:

USD,

USDC

Example:

"USD"

deduct_from

enum<string>

required

Where the funds are drawn from. Only PREFUNDED_BALANCE transfers are eligible for refunds if they fail.

Available options:

PREFUNDED_BALANCE,

LIQUIDATION_ADDRESS

Example:

"PREFUNDED_BALANCE"

remarks

string

required

Example:

"Monthly payment for services"

source_amount

integer

Amount to debit, in cents (e.g. 850 = $8.50). Minimum 500 cents. Send this or destination_amount, never both.

Required range: x >= 500

Example:

850

destination_amount

integer

Amount the beneficiary receives, in cents of the beneficiary's currency. Send this or source_amount, never both.

Example:

77350

attachments

object[]

Minimum array length: 1

Show child attributes

Response

Transfer created successfully

data

object

Show child attributes

⌘I

curl --request POST \
  --url https://sandbox.api.fin.com/v2/transactions/transfer-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "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"
  }
}

{
  "message": "Authentication failed"
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

Authentication

Customers

Beneficiaries

Virtual Accounts

Transactions

Balances

Fees & FX Rates

Catalogue

Crypto Orchestration

Webhooks

Create a Transfer V2

What changed from V1

Authorizations

Body

Response

​What changed from V1

Authorizations

Body

Response

What changed from V1