--- title: "Create Payout" method: POST path: "/payout" tags: ["Payout"] --- # Create Payout `POST /payout` ## Request - Base URL: `https://api.finmo.net/v1` - URL: `https://api.finmo.net/v1/payout` - Auth: HTTP basic A **Payout** refers to sending funds to beneficiaries from your Finmo Wallet. Finmo acts as a remitter of funds for both domestic and cross-border fund transfers. Finmo Payouts include domestic fund transfers like NPP in Australia, FAST in Singapore, ACH in the US, SEPA SCT in the EU, or wire transfers using SWIFT. > Beneficiary will be activated after 24 hours of creation. > The platform is accessible through an API integration and allows Payouts via the [dashboard](https://dashboard.finmo.net/preview/dashboards/add-payout). To use Payout via Finmo, you need to load funds into your [Payout wallet](https://dashboard.finmo.net/preview/dashboards/account-detail). You can create a checkout page via the dashboard, and upon completing the transaction, the funds will be available in your Payin wallet. These funds can then be transferred to your Payout wallet through a wallet fund transfer. Alternatively, you can top up your Payout wallet directly using a static Virtual Account associated with it. ### Supported Use-Cases for Disbursing Funds via Finmo * Digital goods and marketplaces * Payroll payments * Payout to suppliers (B2B) * Moving funds between your own entities ### Required APIs for Performing a Payout via Finmo **Step 1:** [List all Payout Methods by Currency & Country](/reference/listpayout-methodbycountrycurrency-1) This API provides all the Payout Methods supported for a specific country and currency combination. **Step 2:** [Get the Required Fields by Payout Method](/reference/getrequiredfieldsbypayoutmethod-1) This API provides the ```SENDER``` and ```BENEFICIARY``` objects required to perform the Payout. **Step 3:** [Validate Beneficiary Details](/reference/validatepayoutbeneficiary-1) (Optional) This API verifies beneficiary details using either the ```beneficiary_id``` or the supplied ```Payout_beneficiary``` information. **Step 4:** Create and Save ```SENDER``` & ```BENEFICIARY``` Tokens The platform offers the option to create and save both ```SENDER``` and ```BENEFICIARY``` tokens so you don't need to fill or store the details. Instead, you provide these tokens in the Create Payout API to complete the transaction. **Step 5:** [Simulate Payout](/reference/simulatepayout-1) in Sandbox To complete your simulation in the sandbox, you must run the [Simulate Payout API](/reference/simulatepayout-1). ### Payout Status & Webhook Notifications Finmo will notify you about the Payout status via webhooks. You can configure a static webhook listener URL via the dashboard or provide a dynamic webhook URL in the Create Payout request. * **Payout_CREATED:** When a Payout is created, Finmo holds (RESERVE) the transferred amount on your Available Balance and triggers a Payout_CREATED webhook. And the Payout status updates to ```PENDING```. * **Payout_COMPLETED:** When a Payout is completed (i.e., the underlying partner/bank confirms the processing of the Payout), Finmo will RELEASE the reserved funds, update the current balance, and create a DEBIT transaction on the Payout Wallet. Finmo will send you a ```Payout_COMPLETED``` webhook, and the Payout status updates to ```COMPLETED```. * **Payout_FAILED:** If a Payout fails, Finmo will send you a ```Payout_FAILED``` webhook. And the Payout status updates to ```FAILED```. > Note: For Payouts such as SWIFT wires or Direct Entry, the ```Payout_COMPLETED``` webhook does not necessarily mean that the beneficiary has received the funds. It indicates that the sender bank has processed the transaction request to the underlying network. If the recipient bank or any correspondent bank fails to process the transaction (for example, due to an invalid or inactive account number), the funds are returned to Finmo, and a ```Payout_FAILED``` webhook is sent. The Payout status updates from ```COMPLETED``` to ```FAILED```, and funds are credited back to your Payout wallet. For real-time transfers such as NPP in Australia or FAST in Singapore, in 99% of cases, a Payout status of ```COMPLETED``` means the beneficiary has successfully received the funds. ## Request body - object - `sender_amount` number, required: Sender transaction amount. The number of decimal place will be different for each currency according to ISO 4217 - `sender_currency` string, required: Sender transaction currency - `sender_country` string: Sender transaction country - `beneficiary_amount` number, required: Beneficiary transaction amount. The number of decimal place will be different for each currency according to ISO 4217 - `beneficiary_currency` string, required: Beneficiary transaction currency - `beneficiary_country` string: Beneficiary transaction country - `payout_method_name` string, required: Payout method name (for e.g. au_bank_npp) - `fx_rate_id` string: FX rate reference - `debit_wallet_id` string, required: **Conditionally required:** Organization Payout Wallet ID (implicit) or customer's Wallet ID. If you dont provide anything in this field, it assumes Payout wallet by default and funds will be debited from this wallet - `fees_wallet_id` string: Fees wallet Id - `organization_reference_id` string: A reference you can later use to identify this payment, such as an order number. Can only be alphanumeric and must be unique for Benefit. - `description` string: Transaction description - `payout_method_param` object: You will receive these params from Get Required fields by Payout method API - `payout_beneficiary_param` object, required: **Conditionally required:** You will receive these params from Get Required fields by Payout method API. Either pass the beneficiary params or provide the beneficiary token created using Create Beneficiary API - `account_number` string, required - `bsb` string, required - `individual` object - `first_name` string, required - `last_name` string, required - `payout_controls` object: Controls specific checks during account validation. - `is_beneficiary_name_match_enabled` boolean - `is_payout_on_name_mismatch_allowed` boolean - `payout_beneficiary_id` string, required: **Conditionally required:** Either pass the beneficiary params or provide the beneficiary token created using Create Beneficiary API - `payout_sender_id` string: **Conditionally required:** Either pass the sender params or provide the sender token created using Create sender API - `payout_sender_param` object: **Conditionally required:** You will receive these params from Get Required fields by Payout method API. Either pass the sender params or provide the sender token created using Create sender API - `type` 'company' | 'individual', required: Type of sender. Must be either 'individual' or 'company' - `company` object, nullable: Company details (required if type is 'company') - `name` string - `incorporation_country` string - `registration_number` string - `address_line1` string - `address_city` string - `purpose_code` string, required: The list of Purpose Codes of the transaction can be found here - `receipt_email` string: Provide an email if you would like to send a receipt to your customer or yourself after the payout is successfully completed - `payout_reference` string: Payout Reference - `webhook_url` string: Custom webhook url for this payout. If not provided we will notify you on whats configured on the Dashboard - `metadata` object: Custom Data - `any-custom-ref` string, required ## Response `201` Created - object - `data` object - `additional_data` string, nullable - `beneficiary_amount` integer - `beneficiary_country` string - `beneficiary_currency` string - `bulk_payout_id` string - `created_at` string, date-time - `customer_id` string - `debit_wallet_id` string - `debit_wallet_transaction_id` string - `description` string, nullable - `fees_currency` string - `fees_including_tax` string, nullable - `fees_wallet_id` string - `fees_wallet_transaction_id` string, nullable - `fees_without_tax` string, nullable - `fx_conversion_id` string, nullable - `fx_rate` integer - `fx_rate_id` string, nullable - `is_chargeable` boolean - `is_fees_charged` boolean - `is_paid` boolean - `is_reconciled` boolean - `is_returnable` boolean - `is_returned` boolean - `metadata` object - `any-custom-ref` string - `org_id` string - `organization_reference_id` string, nullable - `paid_amount` string, nullable - `paid_at` string, date-time, nullable - `paid_currency` string, nullable - `payout_beneficiary_id` string, nullable - `payout_beneficiary_param` object - `account_number` string - `bank_country` string - `bsb` string - `currency` string - `individual` object - `first_name` string - `last_name` string - `type` string - `payout_id` string - `payout_method_name` string - `payout_method_param` object - `payout_reference` string - `payout_returned_transaction_id` string, nullable - `payout_returned_wallet_id` string, nullable - `payout_returned_wallet_transaction_id` string, nullable - `payout_sender_id` string, nullable - `payout_sender_param` object - `type` 'company' | 'individual' - `company` object, nullable - `name` string - `incorporation_country` string - `registration_number` string - `address_line1` string - `address_city` string - `payout_type` string - `purpose_code` string - `reason_for_failure` string - `reason_for_return` string, nullable - `receipt_email` string, nullable - `released_at` string, date-time - `returned_amount` string, nullable - `returned_at` string, date-time, nullable - `returned_currency` string, nullable - `scope` string - `sender_amount` integer - `sender_country` string, nullable - `sender_currency` string - `statement_descriptor` string, nullable - `status` string - `tax_on_fees` string, nullable - `transaction_id` string, nullable - `updated_at` string, date-time - `webhook_url` string, uri, nullable - `request_id` string - `request_time` string, date-time - `status_code` integer - `status_text` string - `success` boolean ## Other responses - `400`: Bad Request - `404`: Not Found - `default` ## Changes - **2026-11-03** `39e5e5ab5c3a`: 1 info - endpoint added [Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/payout/post.md) --- [API](https://skmtc.dev/finmo/apis/finmo-api.md) - [All operations](https://skmtc.dev/finmo/apis/finmo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/finmo/apis/finmo-api/revisions/39e5e5ab5c3a?raw)