Payouts

With a verified business, an account or wallet, and, for external payouts, a registered counterparty in place, sending money is mostly a matter of combining those IDs into a single API call.

Choosing a transfer type

• Internal transfer - moving funds between two accounts or wallets you already control inside Fuze, such as sweeping a Named IBAN balance into an operating wallet. Use Create internal transfer.
• External transfer (payout) - sending funds out to a registered counterparty's external account or external wallet. Use Create external transfer.

Internal and external transfers move funds in a single currency. A cross-currency payout needs the Trading or Receiving Funds capabilities instead of the Transfer endpoints directly. See Transfers for the full data model.

Creating a transfer

1. Confirm source and destination currencies with List account currencies or List wallet currencies.
   JSON

   {
     "code": 200,
     "error": null,
     "data": [
       {
         "currency": "USD"
       },
       {
         "currency": "USDC"
       },
       {
         "currency": "USD"
       }
     ]
   }

2. For an internal move, call Create internal transfer with a transferId you generate plus the source and destination.

{
  "code": 200,
  "error": null,
  "data": {
    "from": {
      "orgUserId": "sherlock_holmes"
    },
    "to": {
      "orgUserId": "john_watson",
      "currency": "USDC",
      "amount": 1000
    },
    "referenceId": "123e4567-ea9b-12d3-a456-426614174000",
    "transferId": "123e4567-ea9b-12d3-a456-426614174000",
    "status": "COMPLETED",
    "type": "WITHDRAWAL",
    "createdAt": "2023-10-01T00:00:00Z",
    "updatedAt": "2023-10-01T00:00:00Z"
  }
}

3. For a payout, confirm the destination is a verified counterparty, then call Create external transfer; while it is still in the CREATED state you can amend it with Update external transfer, and some rails need a follow-up Confirm external transfer to release it.
   JSON

   {
     "code": 200,
     "error": null,
     "data": {
       "from": {
         "orgUserId": "sherlock_holmes",
         "currency": "USD",
         "amount": 1000
       },
       "to": {
         "counterPartyId": "john_watson",
         "accountId": "123e4567-ea9b-12d3-a456-426614174000",
         "currency": "USD",
         "amount": 1000,
         "finalAmount": 1000
       },
       "transferId": "123e4567-ea9b-12d3-a456-426614174000",
       "referenceId": "REF-123456789",
       "status": "COMPLETED",
       "type": "WITHDRAWAL",
       "createdAt": "2023-10-01T00:00:00Z",
       "updatedAt": "2023-10-01T00:00:00Z",
       "gasFee": 0.0005
     }
   }

4. Always generate a unique transferId per attempt and reuse it on retries - this keeps retries idempotent and prevents duplicate payments. See Understanding Idempotency for more.

Tracking and managing the lifecycle

A transfer moves through a small set of statuses: PENDING, PROCESSING, COMPLETED, FAILED, and ACTION_REQUIRED. Fuze reports status changes via webhooks in real time. See User Lifecycle & Webhooks for event details.

• ACTION_REQUIRED - inspect the transfer to see what's outstanding; Fuze resumes automatically once it's resolved.
• FAILED - check the failure reason, fix the underlying issue, and retry with a new transferId; never reuse a failed transferId expecting it to be re-processed.
• Reversals - to pull back funds after a transfer has completed, use Create reversal transaction rather than creating a new transfer in the opposite direction.

Store the transferId, current status, and last-updated timestamp for every transfer. Treat webhooks as the fast path and polling as the fallback, so a missed webhook never leaves your records silently out of date.

{
"transferId": "wire_2XJrDbWNdssIggB6dIUPMlT9u27","type": "WITHDRAWAL",
"status": "COMPLETED","from": { "accountId": "acc_7c1e4b2a9f3d" },
"to": { "counterPartyId": "cp_4a1d8e2f6b90", "externalAccountId": "eacc_8b3f1c0a2d7e" }}