Create a payout instruction set

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.

Endpoint Permission: Admin, Non-Signing Admin.

POST

payments

payout

TypeScript

const response: Promise<FireblocksResponse<PayoutResponse>> = fireblocks.paymentsPayout.createPayout(paymentsPayoutApiCreatePayoutRequest);

{
  "payoutId": "1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7",
  "paymentAccount": {
    "id": "EX_SUB2",
    "type": "EXCHANGE_ACCOUNT"
  },
  "createdAt": 1645365800,
  "state": "REQUESTED",
  "status": "REGISTERED",
  "initMethod": "API",
  "instructionSet": [
    {
      "id": "6ea4a016-536b-49af-b1a0-40b343ccf879",
      "name": "payee-wallet-name",
      "payeeAccount": {
        "id": "bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3",
        "type": "EXTERNAL_WALLET"
      },
      "amount": {
        "amount": "43",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED",
      "transactions": []
    },
    {
      "id": "e783a79b-6acc-4d18-885d-ed533cad8eeb",
      "name": "payee-by-network",
      "payeeAccount": {
        "id": "3adc1f92-e791-44a8-9aee-7f31c2108b78",
        "type": "NETWORK_CONNECTION"
      },
      "amount": {
        "amount": "4423.23",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED",
      "transactions": []
    }
  ]
}

Headers

Idempotency-Key

string

A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.

Body

application/json

paymentAccount

object

required

Show child attributes

instructionSet

object[]

required

Show child attributes

Response

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.

payoutId

string

required

paymentAccount

object

required

Show child attributes

createdAt

number

required

state

enum<string>

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

Available options:

CREATED,

FILE_FOUND,

REQUESTED,

TRANSLATED,

PROCESSING,

SUBMITTED,

FINALIZED,

INSUFFICIENT_BALANCE,

FAILED

status

enum<string>

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

Available options:

REGISTERED,

VERIFYING,

IN_PROGRESS,

DONE,

INSUFFICIENT_BALANCE,

FAILED

instructionSet

object[]

required

Show child attributes

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

enum<string>

Available options:

FILE,

API

reportUrl

string

Execute a payout instruction set**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. **Execute a payout instruction set.** The instruction set will be verified and executed. **Source locking** If you are executing a payout instruction set from a payment account with an already active payout the active payout will complete before the new payout instruction set can be executed. You cannot execute the same payout instruction set more than once.

⌘I

TypeScript

const response: Promise<FireblocksResponse<PayoutResponse>> = fireblocks.paymentsPayout.createPayout(paymentsPayoutApiCreatePayoutRequest);

{
  "payoutId": "1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7",
  "paymentAccount": {
    "id": "EX_SUB2",
    "type": "EXCHANGE_ACCOUNT"
  },
  "createdAt": 1645365800,
  "state": "REQUESTED",
  "status": "REGISTERED",
  "initMethod": "API",
  "instructionSet": [
    {
      "id": "6ea4a016-536b-49af-b1a0-40b343ccf879",
      "name": "payee-wallet-name",
      "payeeAccount": {
        "id": "bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3",
        "type": "EXTERNAL_WALLET"
      },
      "amount": {
        "amount": "43",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED",
      "transactions": []
    },
    {
      "id": "e783a79b-6acc-4d18-885d-ed533cad8eeb",
      "name": "payee-by-network",
      "payeeAccount": {
        "id": "3adc1f92-e791-44a8-9aee-7f31c2108b78",
        "type": "NETWORK_CONNECTION"
      },
      "amount": {
        "amount": "4423.23",
        "assetId": "USDC"
      },
      "state": "NOT_STARTED",
      "transactions": []
    }
  ]
}