--- title: "Create a Payout Request" method: POST path: "/api/payouts/payout" tags: ["Payouts"] --- # Create a Payout Request `POST /api/payouts/payout` Creates a Payout Request. The Payout Request can have multiple recipients, each of which can be a fiat or blockchain payout. ## Headers - `on-behalf-of` string - `idempotency-key` string, uuid ## Request body - NewPayoutRequestInput - `memo` string - `payouts` PayoutInfoInput[], required — The list of payouts to be made. Maximum of 350 payouts allowed. - `amount` TokenAmount, required - `tokenAmount` number, required — The token amount. - `tokenSymbol` string, required — The token symbol. - `payoutDetails` union, required - FiatPayoutDetails - `bankAccountOwner` string, required - `bankName` string, required - `developerFee` DeveloperFee - `developerFeePercentage` number - `fiatAndRailDetails` union, required — The fiat and rail details (if applicable) for the payout. This specifies the currency in which the fiat will be delivered. - UsdDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `bankRoutingNumber` string, required - `symbol` 'USD', required - `transferType` 'ACH' | 'WIRE' — The transfer type for USD payouts. Defaults to ACH if not provided. - `type` 'usd', required - CopDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required — The bank account number of the recipient - `documentNumber` string, required — The document number of the recipient - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required — The type of document that the documentNumber corresponds to - `phoneNumber` string, phone, required — The phone number of the recipient - `symbol` 'COP', required - `type` 'cop', required - CopBreBDetails - `keyValue` string, required — Bre-B key value (alphanumeric identifier like @CB...) registered in the real-time payments network - `symbol` 'COP', required - `type` 'cop-bre-b', required - ArsDetails - `bankAccountNumber` string, required - `bankAccountNumberType` 'CVU' | 'CBU' | 'ALIAS', required - `documentNumber` string, required - `symbol` 'ARS', required - `type` 'ars', required - EurDetails - `country` string, alpha2 codes, required — Bank account country. - `iban` string, required — The International Bank Account Number (IBAN) of the recipient - `swiftBic` string, required — The SWIFT / Bank Identifier Code (BIC) of the recipient - `symbol` 'EUR', required - `type` 'eur', required - MxnDetails - `bankAccountNumber` string, required - `symbol` 'MXN', required - `type` 'mxn', required - BrlDetails — Deprecated in favor of the BRL Payment method via the payment method API - `bankAccountNumber` string — Bank account number (EVP key for PIX BANK_ACCOUNT type). Required when pixAccountType is BANK_ACCOUNT or for wire transfers. - `branchCode` string — Branch code. Required for wire transfers (when pixAccountType is not provided). - `documentNumber` string, required - `pixAccountType` 'PHONE' | 'EMAIL' | 'DOCUMENT' | 'BANK_ACCOUNT' — The PIX account type. If not provided, the payout will be processed as a wire transfer. - `pixEmail` string — PIX email key. Required when pixAccountType is EMAIL. - `pixPhone` string — PIX phone number key. Required when pixAccountType is PHONE. - `symbol` 'BRL', required - `type` 'brl', required - ClpDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `symbol` 'CLP', required - `type` 'clp', required - PenDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `symbol` 'PEN', required - `type` 'pen', required - BobDetails - `bankAccountNumber` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `symbol` 'BOB', required - `type` 'bob', required - CrcDetails - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `iban` string, required - `symbol` 'CRC', required - `type` 'crc', required - ZarDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `symbol` 'ZAR', required - `type` 'zar', required - UsdPeruDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `symbol` 'USD', required - `type` 'usd-peru', required - UsdChinaDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `address` string, required - `bankAccountNumber` string, required - `bankName` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `phoneNumber` string, required - `swiftBic` string, required - `symbol` 'USD', required - `type` 'usd-china', required - UsdPanamaDetails - `accountType` 'CHECKING' | 'SAVINGS', required - `bankAccountNumber` string, required - `bankName` string, required - `documentNumber` string, required - `documentType` 'NATIONAL_ID' | 'PASSPORT' | 'RESIDENT_ID' | 'RUC' | 'TAX_ID', required - `symbol` 'USD', required - `type` 'usd-panama', required - UsdHongKongDetails - `bankAccountNumber` string, required - `bankName` string, required - `swiftBic` string, required - `symbol` 'USD', required - `type` 'usd-hong-kong', required - `type` 'fiat', required - BlockchainPayoutDetails - `type` 'blockchain', required - `walletDetails` WalletDetailsInput, required - `blockchain` 'ETHEREUM' | 'POLYGON' | 'BASE' | 'CELO' | 'PLASMA' | 'SOLANA', required — The blockchain network for this payout. SOLANA is accepted only for USD payouts. - `walletAddress` string, required — The destination wallet address. Accepts EVM addresses (0x-prefixed, 40 hex chars, e.g. `0x0000000000000000000000000000000000000000`) or Solana addresses (base58-encoded 32-byte pubkey, e.g. `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`). Must match the selected blockchain. - CounterpartyPayoutMethodDetails — This payout details type can only be used for counterparty payouts. The recipient must be a counterparty. - `developerFee` DeveloperFee - `developerFeePercentage` number - `payoutMethodId` string, uuid, required — The ID of the payout method to use - `type` 'counterpartyPayoutMethod', required - `recipientInfo` union, required - IndividualRecipientInfo - `email` string, email — Email address for the recipient. Some destination rails (for example Colombian COP payouts) require an email — if missing for those rails, payout-request creation will fail with `additional_recipient_information_required` listing the missing fields. - `firstName` string, required — The first name of the individual - `lastName` string, required — The last name of the individual - `physicalAddress` PhysicalAddressInput, required - `address1` string, required - `address2` string - `city` string, required - `country` string, required — ISO 3166-1 alpha-2 country code. See: GET /utilities/countries/{fiatRailCode} - `state` string, required — State or province. ISO 3166-2 subdivision code (minus the country prefix) for the state. See: GET /utilities/countries/{fiatRailCode} - `zip` string, required - `type` 'individual', required - BusinessRecipientInfo - `email` string, email — Email address for the recipient. Some destination rails (for example Colombian COP payouts) require an email — if missing for those rails, payout-request creation will fail with `additional_recipient_information_required` listing the missing fields. - `name` string, required - `physicalAddress` PhysicalAddressInput, required - `address1` string, required - `address2` string - `city` string, required - `country` string, required — ISO 3166-1 alpha-2 country code. See: GET /utilities/countries/{fiatRailCode} - `state` string, required — State or province. ISO 3166-2 subdivision code (minus the country prefix) for the state. See: GET /utilities/countries/{fiatRailCode} - `zip` string, required - `type` 'business', required - CounterpartyRecipientInfo — This recipient type can only be used for counterparty payouts. The payout details must be a counterparty payout method. - `counterpartyId` string, uuid, required — The ID of the counterparty to use as the recipient - `type` 'counterpartyInfo', required - `supportingDetails` PayoutSupportingDetails - `payoutPurpose` 'VENDOR_PAYMENT' | 'PAYROLL' | 'TAX_PAYMENT' | 'RENT_LEASE_PAYMENT' | 'SUPPLIER_PAYMENT' | 'PERSONAL_GIFT' | 'FAMILY_SUPPORT' | 'CHARITABLE_DONATION' | 'EXPENSE_REIMBURSEMENT' | 'BILL_UTILITY_PAYMENT' | 'TRAVEL_EXPENSES' | 'INVESTMENT_CONTRIBUTION' | 'CASH_WITHDRAWAL' | 'REAL_ESTATE_PURCHASE' | 'OTHER' — The purpose of the payout. See "Supporting Details Requirements" in the Compliance Requirements section on the Guides page for information on when this is required. - `supportingDocument` string — **Supporting Document** A base64 encoded file showing the purpose for the payout. - **Format**: Base64 encoded data URI. File size must be less than 10MB. - **Examples**: Invoice, receipt, contract, etc. - **Note**: See "Supporting Details Requirements" in the Compliance Requirements section on the Guides page for information on when this is required. - `sourceAccountId` string, uuid, required — The ID of the source account to be used for the payout ## Response `201` The successfully created Payout Request - PayoutRequest - `createdAt` string, date-time, required - `id` string, uuid, required - `memo` string - `payouts` PayoutRequestRecipientInfo[], required — Information associated with each recipient's payout included in the original payout request. - `amount` TokenAmount, required - `tokenAmount` number, required — The token amount. - `tokenSymbol` string, required — The token symbol. - `createdAt` string, date-time, required - `details` union, required - FiatPayout — Details pertaining to a specific recipient's payout - `developerFee` DeveloperFee - `developerFeePercentage` number - `exchangeFeePercentage` number, required — The total fee for the transaction (in percentile) applied at transaction execution time. This is applied to the source token amount. For example, a value of 3 means 3%. - `exchangeRate` number, required — The exchange rate for the transaction. The rate at which the token amount will be converted to fiat. The units are destination fiat per token. - `feeTotal` TokenAmount, required - `tokenAmount` number, required — The token amount. - `tokenSymbol` string, required — The token symbol. - `fiatAmount` SimpleFiatAmount, required - `fiatAmount` number, required — The fiat amount. - `fiatCurrencyCode` 'USD' | 'COP' | 'ARS' | 'EUR' | 'MXN' | 'BRL' | 'CLP' | 'PEN' | 'BOB' | 'CRC' | 'ZAR', required — The fiat currency code. - `fiatAndRailCode` 'usd' | 'cop' | 'cop-bre-b' | 'cop-cobre-balance' | 'ars' | 'eur' | 'mxn' | 'brl' | 'clp' | 'pen' | 'bob' | 'crc' | 'zar' | 'usd-peru' | 'usd-china' | 'usd-panama' | 'usd-hong-kong', required — The fiat and rail code, if applicable, for the payout. This corresponds to the type discriminator of the fiatAndRailDetails field in the payout request. - `fiatPayoutStatus` union, required — The status of the fiat payout to the recipient. A successful payout will follow these statuses: created → pending → on-hold (optional) → completed. If a payout fails, it will transition to refundInProgress → refunded. A payout can be canceled before initiation, resulting in the canceled status. The failed status is deprecated and will be replaced by the refund flow. - PayoutCreatedStatus — Status when the transaction hasn't been executed yet and the payout is created. This is the initial status of a fiat payout. - `type` 'created', required - PayoutPendingStatus — Status when the transaction has been initiated and the payout is pending. The funds have been transferred to the provider and payout is being processed. - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `type` 'pending', required - PayoutOnHoldStatus — Status when the transaction has been initiated and the payout is on hold. Review of the transaction is being conducted and the Mural team will reach out if more information is needed. - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `type` 'on-hold', required - PayoutCompletedStatus — Status when the transaction has been executed and the payout is completed. The funds have been received by the recipient. This is a terminal status. - `completedAt` string, date-time, required - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `type` 'completed', required - PayoutFailedStatus — DEPRECATED: Status when the transaction has been initiated but the payout has failed. This is a terminal status. Reach out to Mural support - `errorCode` 'UNKNOWN' | 'ACCOUNT_NUMBER_INCORRECT' | 'REJECTED_BY_BANK' | 'ACCOUNT_TYPE_INCORRECT' | 'ACCOUNT_CLOSED' | 'BENEFICIARY_DOCUMENTATION_INCORRECT', required — Error code categorizing the failure reason - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `reason` string, required - `type` 'failed', required - PayoutCanceledStatus — Status when the transaction wasn't initiated because the sender canceled the transaction. This is a terminal status. - `type` 'canceled', required - PayoutRefundInProgressStatus — Status when a refund has been initiated for a previously failed payout. The refund is currently being processed. - `errorCode` 'UNKNOWN' | 'ACCOUNT_NUMBER_INCORRECT' | 'REJECTED_BY_BANK' | 'ACCOUNT_TYPE_INCORRECT' | 'ACCOUNT_CLOSED' | 'BENEFICIARY_DOCUMENTATION_INCORRECT', required — Error code categorizing the failure reason that led to the refund - `failureReason` string, required — The reason why the payout is being refunded - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `refundInitiatedAt` string, date-time, required — When the refund process was initiated - `type` 'refundInProgress', required - PayoutRefundedStatus — Status when a payout has been successfully refunded. The funds have been returned to the sender. This is a terminal status. - `errorCode` 'UNKNOWN' | 'ACCOUNT_NUMBER_INCORRECT' | 'REJECTED_BY_BANK' | 'ACCOUNT_TYPE_INCORRECT' | 'ACCOUNT_CLOSED' | 'BENEFICIARY_DOCUMENTATION_INCORRECT', required — Error code categorizing the failure reason that led to the refund - `failureReason` string, required — The reason why the payout was refunded - `initiatedAt` string, date-time, required — The time at which thepayout was initiated with the local banking provider - `refundCompletedAt` string, date-time, required — When the refund was completed and funds returned - `refundInitiatedAt` string, date-time, required — When the refund process was initiated - `refundTransactionId` string, uuid, required — The transaction ID of the refund in the Transactions API - `type` 'refunded', required - `transactionFee` TokenAmount, required - `tokenAmount` number, required — The token amount. - `tokenSymbol` string, required — The token symbol. - `type` 'fiat', required - BlockchainPayout - `blockchain` 'ETHEREUM' | 'POLYGON' | 'BASE' | 'CELO' | 'PLASMA' | 'SOLANA', required — The destination blockchain. SOLANA is returned only for USD payouts. - `status` 'AWAITING_EXECUTION' | 'PENDING' | 'EXECUTED' | 'FAILED' | 'CANCELED', required — The status of the blockchain payout. The initial status is AWAITING_EXECUTION, and the status will change to PENDING. EXECUTED, FAILED, and CANCELED are terminal statuses. EXECUTED indicates the blockchain transaction associated with the transfer has been executed. - `transactionHash` string, nullable — On-chain hash for this recipient's settlement. Present for USD payouts to external wallets (populated once settlement completes); absent for USDC payouts — read the top-level `transactionHash` on the payout request in that case. - `type` 'blockchain', required - `walletAddress` string, required — The destination wallet address. EVM (0x-prefixed hex) or Solana (base58-encoded 32-byte pubkey), matching the blockchain value. - `id` string, uuid, required - `recipientInfo` union, required — Information about how this payout recipient was specified - either via counterparty reference or inline details - CounterpartyPayoutRecipientInfo — Recipient information for payouts created using counterparty and payout method references - `counterpartyId` string, uuid, required — The ID of the counterparty used as the recipient - `payoutMethodId` string, uuid, required — The ID of the payout method used as the payout method - `type` 'counterparty', required - InlinePayoutRecipientInfo — Recipient information for payouts created using inline recipient and payout details - `details` union, required — Details about the inline recipient, discriminated by payout type (fiat or blockchain) - InlineFiatPayoutRecipientDetails — Details about an inline fiat payout recipient. This includes recipient information and bank details. - `details` GeneralBankAccountDetails, required — General bank account information for inline fiat payouts - … - `type` 'fiat', required - InlineBlockchainPayoutRecipientDetails — Details about an inline blockchain payout recipient. This includes recipient information and wallet details. - `blockchain` 'ETHEREUM' | 'POLYGON' | 'BASE' | 'CELO' | 'PLASMA' | 'SOLANA', required — The blockchain network for this payout. SOLANA is returned only for USD payouts. - `type` 'blockchain', required - `walletAddress` string, required — The wallet address receiving the payout. EVM (0x-prefixed hex) or Solana (base58-encoded 32-byte pubkey), matching the blockchain value. - `name` string, required — The name of the recipient - `type` 'inline', required - `updatedAt` string, date-time, required - `sourceAccountId` string, uuid, required - `status` 'AWAITING_EXECUTION' | 'CANCELED' | 'PENDING' | 'EXECUTED' | 'FAILED', required — DEPRECATED: use `statusV2` instead. The status of the overall payout request. The initial status is AWAITING_EXECUTION, and the status will change to PENDING. EXECUTED, FAILED, and CANCELED are terminal statuses. EXECUTED indicates the blockchain transaction associated with the entire payout has been executed, but that does not mean your recipients have received funds. Check the individual recipientsPayoutDetails for the status of each recipient. - `statusV2` union, required — The initial status is `awaitingExecution`, and the status will change to `pending`. `executed`, `failed`, and `canceled` are terminal statuses. `executed` indicates the blockchain transaction associated with the entire payout has been executed, but that does not mean your recipients have received funds. Check the individual recipientsPayoutDetails for the status of each recipient. - PayoutRequestAwaitingExecutionStatusV2 - `type` 'awaitingExecution', required - PayoutRequestPendingStatusV2 - `type` 'pending', required - PayoutRequestExecutedStatusV2 - `type` 'executed', required - PayoutRequestFailedStatusV2 — Status metadata for a failed payout request. - `errorDescription` string, required — Human-readable explanation of why the payout request failed. - `type` 'failed', required - PayoutRequestCanceledStatusV2 - `type` 'canceled', required - `transactionHash` string — The transaction hash of the blockchain transaction. Present when the status is EXECUTED. - `updatedAt` string, date-time, required ## Other responses - `400` — Payout Minimum Not Met Error | Additional Recipient Information Required - `401` — Unauthorized - `403` — KycUpgradeRequiredException - `409` — IdempotencyConflictError - `412` — PayoutMethodError - `422` — IdempotencyKeyExpiredError - `428` — PayoutComplianceValidationFailedError --- [API](https://skmtc.net/muralpay/apis/mural-api.md) · [All operations](https://skmtc.net/muralpay/apis/mural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/muralpay/mural-api/versions/437d277f5948/schema)