Update Payment metadata

curl --request POST \
  --url https://api.prod.finverse.net/payments/{paymentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {}
}'

import requests

url = "https://api.prod.finverse.net/payments/{paymentId}"

payload = { "metadata": {} }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {}})
};

fetch('https://api.prod.finverse.net/payments/{paymentId}', 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/payments/{paymentId}",
  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([
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/payments/{paymentId}"

	payload := strings.NewReader("{\n  \"metadata\": {}\n}")

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

	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/payments/{paymentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payments/{paymentId}")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {}\n}"

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

{
  "amount": 500,
  "amount_total_with_surcharge": 500,
  "created_at": "2025-02-10T22:01:27.790Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01H5VH5YCFDVH80YZ8D0TG3HET"
    }
  ],
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "updated_value",
    "new_key": "new_value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1739224888",
    "processor_entity_name": "Finverse Technologies Limited",
    "transaction_reference_id": "1739224888"
  },
  "payment_id": "01JKRY3C9630R169QPKSGZ5SCK",
  "payment_method_id": "01JKRY31TSK2FZ6QPENPKH5CC2",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1",
    "name": "John Doe",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "01JJJADS8A8M9PH8RT3S9AAT3A"
        ]
      }
    ],
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01JKRY36KBKH4N6B9ZDPMSYSBA",
    "account_number": {
      "number": "01JKRY36QWXD22AMWCAX8YX872",
      "type": "LOCAL"
    },
    "account_number_masked": "XXX45",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01JKRY36RA3449AWF353ARZ1CA",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH"
  },
  "status": "EXECUTED",
  "surcharge_amount": 0,
  "type": "MANDATE",
  "updated_at": "2025-02-11T07:24:06.864Z"
}

Payment operations

Update Payment metadata

Update (PATCH) an existing Payment’s metadata, identified by the payment’s payment_id.

Authorization: customer_token

Request parameters

Only the selected fields below can currently be updated. Any omitted fields will remain unchanged.

The following fields are non-editable. Attempting to edit these will return an API error:

amount, amount_total_with_surcharge, currency, created_at, fees, payment_details, payment_id, payment_method_id, recipient, recipient_account, sender, sender_account, , status, surcharge_amount, type, updated_at

Response fields

The response is the updated Payment object.

Refer to Payment object data model in GET /payments/{payment_id}.

Implementation guidance

Be careful when updating the value of a payment’s metadata, as this can impact downstream handling:

Some pre-built Finverse integrations (e.g. Rapidstor/Sitelink and Storeganise payments), rely on payment.metadata to trigger downstream events, such as recording successful/failed payments in the integrated system.
payment.metadata is included in payment webhooks sent by Finverse. If a webhook event is triggered after updating payment.metadata (e.g. due to a payment.status change), any listeners of the webhooks will automatically consume the metadata. Before updating payment.metadata, review how your webhook consumers handle changes to metadata.
1. Note: simply updating payment.metadata will not by itself trigger a webhook event.
Consider how updated metadata can impact all possible downstream consumers of payment.metadata , including:
1. Pre-built Finverse integrations (which rely on metadata to record successful/failed payments)
2. Finverse payment statements (which display metadata)
3. ERP and accounting systems (for example, if they use metadata to allocate payments)
4. Analytics/business intelligence solutions, e.g. Power BI

POST

payments

{paymentId}

Update Payment metadata

curl --request POST \
  --url https://api.prod.finverse.net/payments/{paymentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {}
}'

import requests

url = "https://api.prod.finverse.net/payments/{paymentId}"

payload = { "metadata": {} }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({metadata: {}})
};

fetch('https://api.prod.finverse.net/payments/{paymentId}', 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/payments/{paymentId}",
  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([
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/payments/{paymentId}"

	payload := strings.NewReader("{\n  \"metadata\": {}\n}")

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

	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/payments/{paymentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prod.finverse.net/payments/{paymentId}")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"metadata\": {}\n}"

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

{
  "amount": 500,
  "amount_total_with_surcharge": 500,
  "created_at": "2025-02-10T22:01:27.790Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01H5VH5YCFDVH80YZ8D0TG3HET"
    }
  ],
  "metadata": {
    "employer_name": "Apple Inc",
    "key": "updated_value",
    "new_key": "new_value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1739224888",
    "processor_entity_name": "Finverse Technologies Limited",
    "transaction_reference_id": "1739224888"
  },
  "payment_id": "01JKRY3C9630R169QPKSGZ5SCK",
  "payment_method_id": "01JKRY31TSK2FZ6QPENPKH5CC2",
  "recipient": {
    "name": "Demo App"
  },
  "recipient_account": {
    "account_id": "01H5VH5YCFDVH80YZ8D0TG3HET",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1",
    "name": "John Doe",
    "user_details": [
      {
        "details_type": "HK_ID",
        "values": [
          "01JJJADS8A8M9PH8RT3S9AAT3A"
        ]
      }
    ],
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01JKRY36KBKH4N6B9ZDPMSYSBA",
    "account_number": {
      "number": "01JKRY36QWXD22AMWCAX8YX872",
      "type": "LOCAL"
    },
    "account_number_masked": "XXX45",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01JKRY36RA3449AWF353ARZ1CA",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01GWKTK0380NBRCV1B8D6N0SEH"
  },
  "status": "EXECUTED",
  "surcharge_amount": 0,
  "type": "MANDATE",
  "updated_at": "2025-02-11T07:24:06.864Z"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

paymentId

string

required

payment id

Body

application/json

request body for updating payment

metadata

object

Customer-supplied attributes in key:value format. E.g. employer_name: Apple Inc. Any keys provided will be inserted as new keys into the existing metadata object, without removing any existing key:value pairs. If a key already exists in the metadata object, its value will be overwritten with the updated value provided.

Show child attributes

Response

Successful

amount

integer

required

Amount of the payment (in minor currency unit)

Example:

100

amount_total_with_surcharge

integer

required

Total amount of the payment including any transaction fee surcharge_amount paid by the sender (in minor currency unit). See surcharge_amount on transaction fee surcharges.

Example:

100

surcharge_amount

integer

required

Transaction fee surcharge_amount paid by the sender, if any surcharge has been configured (in minor currency unit). Transaction fee surcharges are off by default, but can be set for specific payment methods, or for custom scenarios (e.g. based on transaction amount, payment flow, etc). Contact [email protected] to configure surcharges.

Example:

100

created_at

string<date-time>

Timestamp when the payment was first created

currency

string

Currency of the payment (e.g. HKD)

Example:

"HKD"

error

object

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

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 payment

Show child attributes

payment_id

string

Finverse Payment ID for this payment. Always unique. Creating a payment with different idempotency keys will result in two payments with different IDs.

payment_method

object

Details on the payment method

Show child attributes

payment_method_id

string

(TO BE DEPRECATED) Finverse unique ID for the payment method

recipient

object

Details on the recipient of the payment

Show child attributes

recipient_account

object

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

Show child attributes

sender

object

Details on the sender of the payment

Show child attributes

sender_account

object

(IN DEVELOPMENT) Details on the Sender's source institution and account, which is funding the payment

Show child attributes

status

enum<string>

Current status of the payment. Possible values: CREATED, AUTHORIZATION_REQUIRED, PROCESSING, SUBMITTED, EXECUTED, CANCELLED, FAILED

Available options:

AUTHORIZATION_REQUIRED,

AUTHORIZING,

PROCESSING,

SUBMITTED,

EXECUTED,

FAILED,

REVOKED,

CANCELLED,

CREATED

type

enum<string>

Specified payment type. Possible values: - CARD: payment via card gateway (e.g. Stripe) - MANDATE: direct debit bank payment - MANUAL: manual bank transfer (e.g. FPS, PayNow) - SINGLE: not used (reserved for future use)

Available options:

MANDATE,

SINGLE,

CARD,

MANUAL,

WALLET

updated_at

string<date-time>

Timestamp of the last update to the payment's record