Create a payout

curl --request POST \
  --url https://api.prod.finverse.net/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 123,
  "confirm": true,
  "currency": "<string>",
  "payment_details": {
    "description": "<string>",
    "external_transaction_reference": "<string>"
  },
  "recipient_account": {
    "account_id": "<string>"
  },
  "sender_account": {
    "account_id": "<string>"
  },
  "metadata": {}
}
'

import requests

url = "https://api.prod.finverse.net/payouts"

payload = {
    "amount": 123,
    "confirm": True,
    "currency": "<string>",
    "payment_details": {
        "description": "<string>",
        "external_transaction_reference": "<string>"
    },
    "recipient_account": { "account_id": "<string>" },
    "sender_account": { "account_id": "<string>" },
    "metadata": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 123,
    confirm: true,
    currency: '<string>',
    payment_details: {description: '<string>', external_transaction_reference: '<string>'},
    recipient_account: {account_id: '<string>'},
    sender_account: {account_id: '<string>'},
    metadata: {}
  })
};

fetch('https://api.prod.finverse.net/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.finverse.net/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 123,
    'confirm' => true,
    'currency' => '<string>',
    'payment_details' => [
        'description' => '<string>',
        'external_transaction_reference' => '<string>'
    ],
    'recipient_account' => [
        'account_id' => '<string>'
    ],
    'sender_account' => [
        'account_id' => '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.finverse.net/payouts"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.finverse.net/payouts")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "live": true,
  "amount": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "currency": "<string>",
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "type": "LINKING_ERROR"
  },
  "fees": [
    {
      "amount": 100,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "The payment account ID"
    }
  ],
  "metadata": {},
  "payment_details": {
    "description": "<string>",
    "estimated_arrival_time": "2025-08-22T12:00:00Z",
    "mandate_id": "<string>",
    "processor_details": {
      "processor_id": "<string>",
      "processor_reference": "<string>"
    },
    "references": {
      "recipient_reference": "<string>"
    },
    "scheduled_date": "2023-11-07T05:31:56Z",
    "transaction_reference_id": "<string>"
  },
  "payout_id": "<string>",
  "recipient": {
    "external_user_id": "<string>",
    "user_id": "<string>",
    "user_type": "INDIVIDUAL",
    "name": "<string>",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "recipient_account": {
    "account_id": "sender_account_id",
    "account_number": {
      "number": "<string>",
      "type": "LOCAL",
      "number_plaintext": "<string>"
    },
    "account_number_masked": "<string>",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01EP4A1MZDHKETZFRPF0K62S6S",
    "accountholder_name_plaintext": "Chan Li Pak",
    "bank_code": "<string>",
    "institution_id": "hsbc-hk",
    "institution_name": "HSBC",
    "metadata": {},
    "user_id": "01GY6H0JA7BS8EVGY56NSHFX2E"
  },
  "sender": {
    "name": "<string>"
  },
  "sender_account": {
    "account_id": "<string>",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "status": "EXECUTED",
  "transaction_date": "<string>",
  "transaction_time": "2025-08-22T12:00:00Z",
  "type": "MANUAL",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR"
  }
}

POST

payouts

Create a payout

curl --request POST \
  --url https://api.prod.finverse.net/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 123,
  "confirm": true,
  "currency": "<string>",
  "payment_details": {
    "description": "<string>",
    "external_transaction_reference": "<string>"
  },
  "recipient_account": {
    "account_id": "<string>"
  },
  "sender_account": {
    "account_id": "<string>"
  },
  "metadata": {}
}
'

import requests

url = "https://api.prod.finverse.net/payouts"

payload = {
    "amount": 123,
    "confirm": True,
    "currency": "<string>",
    "payment_details": {
        "description": "<string>",
        "external_transaction_reference": "<string>"
    },
    "recipient_account": { "account_id": "<string>" },
    "sender_account": { "account_id": "<string>" },
    "metadata": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 123,
    confirm: true,
    currency: '<string>',
    payment_details: {description: '<string>', external_transaction_reference: '<string>'},
    recipient_account: {account_id: '<string>'},
    sender_account: {account_id: '<string>'},
    metadata: {}
  })
};

fetch('https://api.prod.finverse.net/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.finverse.net/payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 123,
    'confirm' => true,
    'currency' => '<string>',
    'payment_details' => [
        'description' => '<string>',
        'external_transaction_reference' => '<string>'
    ],
    'recipient_account' => [
        'account_id' => '<string>'
    ],
    'sender_account' => [
        'account_id' => '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.finverse.net/payouts"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.prod.finverse.net/payouts")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 123,\n  \"confirm\": true,\n  \"currency\": \"<string>\",\n  \"payment_details\": {\n    \"description\": \"<string>\",\n    \"external_transaction_reference\": \"<string>\"\n  },\n  \"recipient_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"sender_account\": {\n    \"account_id\": \"<string>\"\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "live": true,
  "amount": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "currency": "<string>",
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "type": "LINKING_ERROR"
  },
  "fees": [
    {
      "amount": 100,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "The payment account ID"
    }
  ],
  "metadata": {},
  "payment_details": {
    "description": "<string>",
    "estimated_arrival_time": "2025-08-22T12:00:00Z",
    "mandate_id": "<string>",
    "processor_details": {
      "processor_id": "<string>",
      "processor_reference": "<string>"
    },
    "references": {
      "recipient_reference": "<string>"
    },
    "scheduled_date": "2023-11-07T05:31:56Z",
    "transaction_reference_id": "<string>"
  },
  "payout_id": "<string>",
  "recipient": {
    "external_user_id": "<string>",
    "user_id": "<string>",
    "user_type": "INDIVIDUAL",
    "name": "<string>",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "recipient_account": {
    "account_id": "sender_account_id",
    "account_number": {
      "number": "<string>",
      "type": "LOCAL",
      "number_plaintext": "<string>"
    },
    "account_number_masked": "<string>",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01EP4A1MZDHKETZFRPF0K62S6S",
    "accountholder_name_plaintext": "Chan Li Pak",
    "bank_code": "<string>",
    "institution_id": "hsbc-hk",
    "institution_name": "HSBC",
    "metadata": {},
    "user_id": "01GY6H0JA7BS8EVGY56NSHFX2E"
  },
  "sender": {
    "name": "<string>"
  },
  "sender_account": {
    "account_id": "<string>",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "status": "EXECUTED",
  "transaction_date": "<string>",
  "transaction_time": "2025-08-22T12:00:00Z",
  "type": "MANUAL",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "details": "<string>",
    "error_code": "CREDENTIALS_INVALID",
    "message": "<string>",
    "request_id": "<string>",
    "type": "LINKING_ERROR"
  }
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

Idempotency-Key

string

required

A random key provided by the customer, per unique payout. The purpose for the Idempotency key is to allow safe retrying without the operation being performed multiple times.

Body

application/json

Request body containing information to create a payout

amount

integer

required

The payout amount, in the minor unit of the currency

confirm

boolean

required

If true, the payout is immediately submitted for processing. If false, the payout is created in CREATED status and must be confirmed via POST /payouts/{payoutId}/confirm before it is processed.

currency

string

required

ISO 4217 currency code of the payout

payment_details

object

required

Show child attributes

recipient_account

object

required

Show child attributes

sender_account

object

required

Show child attributes

metadata

object

Up to 20 metadata key-value pairs

Show child attributes

Response

live

boolean

required

Flag to indicate whether the payment is a test transaction (i.e. from/to a test bank, live=false) or a live transaction (i.e. from/to a real bank, live=true).

amount

integer

Amount of the payout (in minor currency unit)

created_at

string<date-time>

Timestamp when the payout was first created

currency

string

Currency of the payout (e.g. HKD)

error

object

Details on why the payout failed (returned when status = FAILED). Note: this is used to detail any asynchronous e errors occuring after payout creation; any synchronous errors (e.g. API validation errors, real-time payout errors) will instead be returned directly during POST /payouts.

Show child attributes

fees

object[]

Details on the fee(s) to be charged

Show child attributes

metadata

object

Customer-supplied attributes in key:value format. E.g. employer_name: Apple Inc

Show child attributes

payment_details

object

Details on the payout

Show child attributes

payout_id

string

Finverse Payout ID for this payout. Always unique. Creating a payout with different idempotency keys will result in two payouts with different IDs.

recipient

object

Details on the recipient of the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient may not be known.

Show child attributes

recipient_account

object

Details on the account receiving the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient account may not be known.

Show child attributes

sender

object

Details on the sender of the payout

Show child attributes

sender_account

object

Details on the Sender's account at Finverse (i.e. the Customer App's settlement account at Finverse)

Show child attributes

status

enum<string>

Current status of the payout. Possible values: CREATED, FUNDED, PROCESSING, SUBMITTED, EXECUTED, CANCELLED, FAILED

Available options:

EXECUTED,

CREATED,

PROCESSING,

PROCESSING_FUNDS,

CANCELLED,

FAILED,

FUNDED,

SUBMITTED

transaction_date

string

[DEPRECATED] Transaction date

transaction_time

string<date-time> | null

Date/time at which the payout was confirmed as executed. The actual settlement date/time of the payout may be different. In addition, a payout may be recorded at different times on the bank accounts of the sender vs. the recipient. Note: in some cases, the transaction date will be known, but the specific transaction time may not be known. In these cases, the transaction time will be listed as YYYY-MM-DDT00:00:00Z (or another fixed time value).

Example:

"2025-08-22T12:00:00Z"

type

enum<string>

Specified payout type. Possible values: MANUAL, SCHEDULED, SETTLEMENT

Available options:

MANUAL,

SCHEDULED,

SETTLEMENT

updated_at

string<date-time>

Timestamp of the last update to the payout's record