---
title: "Create a payout instruction set"
method: POST
path: "/payments/payout"
tags: ["Payments - Payout"]
---

# Create a payout instruction set

`POST /payments/payout`

## Request

- Base URL: `https://api.fireblocks.io/v1`
- URL: `https://api.fireblocks.io/v1/payments/payout`
- Auth: none declared
- TypeScript: <https://skmtc.dev/fireblocks/apis/fireblocks-api/docs/payments/payout/post.ts> (a function with typed inputs; its response is checked against the schema)

**Note:** The reference content in this section documents the Payments
Engine endpoint. The Payments Engine endpoints include APIs available only
for customers with Payments Engine enabled on their accounts.

These endpoints are currently in beta and might be subject to
changes.

If you want to learn more about Fireblocks Payments Engine, please
contact your Fireblocks Customer Success Manager or email
CSM@fireblocks.com.

**Create a payout instruction set.**

A payout instruction set is a set of instructions for distributing payments
from a single payment account to a list of payee accounts.

The instruction set defines:

- the payment account and its account type (vault, exchange, or fiat).
- the account type (vault account, exchange account, whitelisted address,
  network connection, fiat account, or merchant account), the amount, and the
  asset of payment for each payee account.

Learn more about Fireblocks Payments - Payouts in the following
[guide](https://developers.fireblocks.com/docs/create-payouts).

Endpoint Permission: Admin, Non-Signing Admin.

## Headers

- `Idempotency-Key` string

## Request body

- CreatePayoutRequest
  - `paymentAccount` PaymentAccount, required
    - `id` string, required
    - `type` 'VAULT_ACCOUNT' | 'EXCHANGE_ACCOUNT' | 'FIAT_ACCOUNT', required
  - `instructionSet` PayoutInstruction[], required
    - `id` string
    - `payeeAccount` PayeeAccount, required
      - `id` string, required
      - `type` 'VAULT_ACCOUNT' | 'EXCHANGE_ACCOUNT' | 'INTERNAL_WALLET' | 'EXTERNAL_WALLET' | 'NETWORK_CONNECTION' | 'FIAT_ACCOUNT', required: - VAULT_ACCOUNT a native Fireblocks vault account - EXCHANGE_ACCOUNT a third-party exchange account - INTERNAL_WALLET a whitelisted address marked as internal to the workspace/organization - EXTERNAL_WALLET a whitelisted address marked as external - NETWORK_CONNECTION a member of the Fireblocks network - FIAT_ACCOUNT a third-party account of a fiat bank (Signature, BCB, etc)
    - `amount` InstructionAmount, required
      - `amount` string, required
      - `assetId` string, required

## Response `200`

The payout instruction set creation succeeded and returns the generated instruction set with a unique payout IDThe payout ID will be used for executing the payout and checking the payout status.

- PayoutResponse
  - `payoutId` string, required
  - `paymentAccount` PaymentAccountResponse, required
    - `id` string
    - `type` 'VAULT_ACCOUNT' | 'EXCHANGE_ACCOUNT' | 'FIAT_ACCOUNT'
  - `createdAt` number, required
  - `state` 'CREATED' | 'FILE_FOUND' | 'REQUESTED' | 'TRANSLATED' | 'PROCESSING' | 'SUBMITTED' | 'FINALIZED' | 'INSUFFICIENT_BALANCE' | 'FAILED', required: - CREATED - payout instruction set created with all its details - FILE_FOUND - new file found in the FTP - REQUESTED - payout requested with all its details - TRANSLATED - payout instruction account IDs identified and translated - PROCESSING - payout instruction set executed and is processing - SUBMITTED - transactions submitted for payout instructions - FINALIZED - payout finished processing, all transactions processed successfully - INSUFFICIENT_BALANCE - insufficient balance in the payment account (can be a temporary state) - FAILED - one or more of the payout instructions failed
  - `status` 'REGISTERED' | 'VERIFYING' | 'IN_PROGRESS' | 'DONE' | 'INSUFFICIENT_BALANCE' | 'FAILED', required: - REQUESTED payout requested with all its details - VERIFIED payout instruction set details were verified - PROCESSING payout instruction set executed and is processing - FINALIZED payout done (all payout instructions completed successfully) - INSUFFICIENT_BALANCE insufficient balance in the payment account (can be a temporary state) - FAILED one or more of the payout instructions failed
  - `reasonOfFailure` string: - INSUFFICIENT_BALANCE - SOURCE_TRANSLATION - SOURCE_NOT_UNIQUE - SOURCE_NOT_FOUND - SOURCE_TYPE_NOT_SUPPORTED - EMPTY_SOURCE - DESTINATION_TRANSLATION - DESTINATION_NOT_UNIQUE - DESTINATION_NOT_FOUND - EMPTY_DESTINATION - PARSING - UNKNOWN - FIREBLOCKS_CLIENT - TRANSACTION_SUBMISSION
  - `initMethod` 'FILE' | 'API'
  - `instructionSet` PayoutInstructionResponse[], required
    - `id` string
    - `payeeAccount` PayeeAccountResponse, required
      - `id` string
      - `type` 'VAULT_ACCOUNT' | 'EXCHANGE_ACCOUNT' | 'INTERNAL_WALLET' | 'EXTERNAL_WALLET' | 'NETWORK_CONNECTION' | 'FIAT_ACCOUNT': - VAULT_ACCOUNT a native Fireblocks vault account - EXCHANGE_ACCOUNT a third-party exchange account - INTERNAL_WALLET a whitelisted address marked as internal to the workspace/organization - EXTERNAL_WALLET a whitelisted address marked as external - NETWORK_CONNECTION a member of the Fireblocks network - FIAT_ACCOUNT a third-party account of a fiat bank (Signature, BCB, etc)
    - `amount` InstructionAmount, required
      - `amount` string, required
      - `assetId` string, required
    - `state` 'NOT_STARTED' | 'TRANSACTION_SENT' | 'COMPLETED' | 'FAILED' | 'TRANSLATION_ERROR' | 'SKIPPED', required: - NOT_STARTED - waiting to start - TRANSACTION_SENT - an underlying transaction was sent - COMPLETED - completed successfully - FAILED - failed - TRANSLATION_ERROR -lookup of the destination failed (due to changes in the underlying whitelisted external wallet or similar) - SKIPPED- no transaction(s) created for this instruction
    - `transactions` Transaction[], required
      - `id` string, required
      - `state` 'SUBMITTED' | 'QUEUED' | 'PENDING_AUTHORIZATION' | 'PENDING_SIGNATURE' | 'BROADCASTING' | 'PENDING_3RD_PARTY_MANUAL_APPROVAL' | 'PENDING_3RD_PARTY' | 'PENDING' | 'CONFIRMING' | 'CONFIRMED' | 'COMPLETED' | 'PARTIALLY_COMPLETED' | 'PENDING_AML_SCREENING' | 'CANCELLING' | 'CANCELLED' | 'REJECTED' | 'BLOCKED' | 'FAILED' | 'TIMEOUT', required
      - `timestamp` number
      - `instructionId` string
  - `reportUrl` string

## Other responses

- `400`: Bad request
- `401`: Unauthorized. Missing / invalid JWT token in Authorization header.
- `5XX`: Internal error.

---

[API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)