Create Payout

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. To use Payout via Finmo, you need to load funds into your Payout wallet. 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

This API provides all the Payout Methods supported for a specific country and currency combination.

Step 2: Get the Required Fields by Payout Method

This API provides the SENDER and BENEFICIARY objects required to perform the Payout.

Step 3: Validate Beneficiary Details (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 in Sandbox

To complete your simulation in the sandbox, you must run the Simulate Payout API.

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.

Body Params
number
required

Sender transaction amount. The number of decimal place will be different for each currency according to ISO 4217

string
required

Sender transaction currency

string

Sender transaction country

number
required

Beneficiary transaction amount. The number of decimal place will be different for each currency according to ISO 4217

string
required

Beneficiary transaction currency

string

Beneficiary transaction country

string
required

Payout method name (for e.g. au_bank_npp)

string

FX rate reference

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

string

Fees wallet 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.

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

payout_controls
object

Controls specific checks during account validation.

string
required

Conditionally required: Either pass the beneficiary params or provide the beneficiary token created using Create Beneficiary API

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

string
required

The list of Purpose Codes of the transaction can be found here

string

Provide an email if you would like to send a receipt to your customer or yourself after the payout is successfully completed

string

Payout Reference

string

Custom webhook url for this payout. If not provided we will notify you on whats configured on the Dashboard

metadata
object

Custom Data

Headers
string
enum
Defaults to application/json; charset=utf-8

Generated from available response content types

Allowed:
Responses

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json; charset=utf-8
application/json