Create a Transfer V3

POST

transactions

transfer-payout

curl --request POST \
  --url https://sandbox.api.fin.com/v3/transactions/transfer-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --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 V2

V2	V3
No idempotency header	`X-Idempotency-Key` header required.

Send a unique X-Idempotency-Key (up to 255 characters) with every new request. A UUID works well:

X-Idempotency-Key: 3f1c9a2e-7b4d-4e8a-9c21-5d6f0b8e1a47

The request body and response are unchanged.

V2 remains available at POST /v2/transactions/transfer-payout. Transfers created on V3 must be settled with Settle a Transfer V3.

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Headers

X-Idempotency-Key

string

required

Unique key that identifies this request. Use a new key for each new request. Maximum 255 characters.

Maximum string length: 255

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/v3/transactions/transfer-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --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 V3

What changed from V2

Authorizations

Headers

Body

Response

​What changed from V2

Authorizations

Headers

Body

Response

What changed from V2