Cancel payout

curl --request POST \
  --url https://api.prod.finverse.net/payouts/{payoutId}/cancel \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prod.finverse.net/payouts/{payoutId}/cancel', 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/{payoutId}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.prod.finverse.net/payouts/{payoutId}/cancel"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payouts/{payoutId}/cancel")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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

{payoutId}

cancel

Cancel payout

curl --request POST \
  --url https://api.prod.finverse.net/payouts/{payoutId}/cancel \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.prod.finverse.net/payouts/{payoutId}/cancel', 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/{payoutId}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.prod.finverse.net/payouts/{payoutId}/cancel"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payouts/{payoutId}/cancel")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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.

Path Parameters

payoutId

string

required

payout id

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