---
title: "Simulate Payout"
method: PATCH
path: "/payout/simulate"
tags: ["Payout"]
---

# Simulate Payout

`PATCH /payout/simulate`

## Request

- Base URL: `https://api.finmo.net/v1`
- URL: `https://api.finmo.net/v1/payout/simulate`
- Auth: HTTP basic

Use this Method in the sandbox to simulate the completion of a Payout i.e. transfer of funds to the beneficiary. 

The Payout must be in a ```PENDING``` status to complete or cancel it. Upon successful execution, the Payin status updates to ```COMPLETED```, ```FAILED``` or ```RETURNED```.

## Request body

- object
  - `beneficiary_amount` string: Beneficiary transaction amount
  - `beneficiary_currency` string: Beneficiary transaction currency
  - `payout_id` string, required: Payout reference (payout_*)
  - `status` string, required: Final status of the payout. Possible values: COMPLETED, FAILED, RETURNED

## Response `200`

OK

- 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
    - `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

- `404`: Not Found
- `406`: Not Acceptable

## Changes

- **2026-11-03** `39e5e5ab5c3a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/payout/simulate/patch.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)