Get payment

curl --request GET \
  --url https://api.prod.finverse.net/payments/{paymentId} \
  --header 'Authorization: Bearer <token>'

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

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 => "GET",
  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/payments/{paymentId}"

	req, _ := http.NewRequest("GET", 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/payments/{paymentId}")

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

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

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

{
  "amount": 500,
  "amount_total_with_surcharge": 500,
  "created_at": "2025-06-21T06:30:26.839Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01JY8AKPBC32AZ5TPD99R27JZP"
    }
  ],
  "metadata": {
    "branch": "branch1",
    "key": "updated_value",
    "new_key": "new_value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1750487427",
    "mandate_id": "01JY8JWDY51SYHP006XZBAMVGN",
    "processor_entity_name": "Finverse Technologies Limited",
    "references": {
      "bank_transaction_reference": "DBS_BANK_REF_01JY8JWTJ92E3RX2TF5F1RA2KK",
      "finverse_transaction_reference": "FV250101AABB",
      "dda_reference": "FINVERSE T-62F2-FINV"
    },
    "transaction_reference_id": "1750487427"
  },
  "payment_id": "01JY8JWSHVR9SNZWYFYX2C9CTV",
  "payment_method_id": "01JY8JWE50618D9RGH44AR884F",
  "recipient": {
    "name": "Finverse Test"
  },
  "recipient_account": {
    "account_id": "01JY8AKPBC32AZ5TPD99R27JZP",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1_1750487415",
    "name": "John Doe",
    "user_details": [],
    "user_id": "01JY8JWE3NG8CJ7DVJZJC3HMJT",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01JY8JWKX2HSZJ500DNEJ3JGHQ",
    "account_number": {
      "number": "01JY8JWM06NV1VNCPM6D5JJ9Y9",
      "type": "LOCAL"
    },
    "account_number_masked": "XXX45",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01JY8JWKZRZ32FFE4G0FPM19H1",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01JY8JWE3NG8CJ7DVJZJC3HMJT"
  },
  "status": "EXECUTED",
  "surcharge_amount": 0,
  "type": "MANDATE",
  "updated_at": "2025-06-21T06:30:28.482Z"
}

Payment operations

Get payment

Retrieve a Payment object (using a specific payment_id).

Authorization: customer_token

Response fields

Single Payment object, containing information on the Payment.

fees (array)

Details on the fee(s) to be charged. Returns an empty array if no fees will be charged.

payment_details (object)

Details describing the Payment.

processor_details (object, optional)

Additional details on how the payment was processed.

result (object, optional)

Additional details on the payment processing result.

references (object, optional)

Additional references for the Payment (e.g. transaction IDs generated by Finverse or the payment gateway).

payment_method (object, optional)

Details on the payment method authorized by the end-user. Refer to the Payment Method data model in GET /payment_users/{user_id}/payment_methods for details on the Payment Method object.

Limitations:

Payment Method object is not returned for one-time manual bank transfers (payment.type = MANUAL, e.g. FPS/PayNow bank transfers).
- These are payments initiated by Payment Links where end-users “push” funds to the recipient bank account. No payment method is created or stored in Finverse systems.
Payment Method object is returned, but without a payment_method_id****, for some card payments with Future Payments disabled.
- These are one-time card payments initiated by Payment Links. In some cases (depending on the external payment gateway through which the payment is processed), no payment method is created or stored in Finverse systems, so no payment_method_id is available.
- However, some card details may still be returned in the payment_method.card.card_details object, for informational purposes (if available from the external payment gateway).

recipient (object), sender (object)

The recipient and sender objects include a Payment User object for each of the counterparties of a payment. Refer to the Payment User data model in GET /payment_users/{payment_user_id} for details on the Payment User object.

Note: Some Payment User metadata fields are omitted for clarity (e.g. created_at, metadata, updated_at).

recipient_account (object), sender_account (object)

The recipient_account and sender_account objects include a Payment Account object for each of the counterparties of a payment. Refer to the Payment Account object data model in GET /payment_users/{user_id}/payment_accounts for details on the Payment Account object.

Note: Some Payment Account metadata fields are omitted for clarity (e.g. created_at, metadata, updated_at).

GET

payments

{paymentId}

Get payment

curl --request GET \
  --url https://api.prod.finverse.net/payments/{paymentId} \
  --header 'Authorization: Bearer <token>'

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

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 => "GET",
  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/payments/{paymentId}"

	req, _ := http.NewRequest("GET", 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/payments/{paymentId}")

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

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

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

{
  "amount": 500,
  "amount_total_with_surcharge": 500,
  "created_at": "2025-06-21T06:30:26.839Z",
  "currency": "HKD",
  "fees": [
    {
      "amount": 500,
      "currency": "HKD",
      "paid_by": "RECIPIENT",
      "paid_by_account_id": "01JY8AKPBC32AZ5TPD99R27JZP"
    }
  ],
  "metadata": {
    "branch": "branch1",
    "key": "updated_value",
    "new_key": "new_value"
  },
  "payment_details": {
    "collection_entity_name": "Finverse Technologies Limited",
    "description": "Test payment",
    "external_transaction_reference": "1750487427",
    "mandate_id": "01JY8JWDY51SYHP006XZBAMVGN",
    "processor_entity_name": "Finverse Technologies Limited",
    "references": {
      "bank_transaction_reference": "DBS_BANK_REF_01JY8JWTJ92E3RX2TF5F1RA2KK",
      "finverse_transaction_reference": "FV250101AABB",
      "dda_reference": "FINVERSE T-62F2-FINV"
    },
    "transaction_reference_id": "1750487427"
  },
  "payment_id": "01JY8JWSHVR9SNZWYFYX2C9CTV",
  "payment_method_id": "01JY8JWE50618D9RGH44AR884F",
  "recipient": {
    "name": "Finverse Test"
  },
  "recipient_account": {
    "account_id": "01JY8AKPBC32AZ5TPD99R27JZP",
    "account_type": "SETTLEMENT_ACCOUNT"
  },
  "sender": {
    "external_user_id": "user_id_1_1750487415",
    "name": "John Doe",
    "user_details": [],
    "user_id": "01JY8JWE3NG8CJ7DVJZJC3HMJT",
    "user_type": "INDIVIDUAL"
  },
  "sender_account": {
    "account_id": "01JY8JWKX2HSZJ500DNEJ3JGHQ",
    "account_number": {
      "number": "01JY8JWM06NV1VNCPM6D5JJ9Y9",
      "type": "LOCAL"
    },
    "account_number_masked": "XXX45",
    "account_type": "EXTERNAL_ACCOUNT",
    "accountholder_name": "01JY8JWKZRZ32FFE4G0FPM19H1",
    "bank_code": "420",
    "institution_id": "testbank-dbs-hk",
    "institution_name": "Testbank (HK) Payments - Personal",
    "user_id": "01JY8JWE3NG8CJ7DVJZJC3HMJT"
  },
  "status": "EXECUTED",
  "surcharge_amount": 0,
  "type": "MANDATE",
  "updated_at": "2025-06-21T06:30:28.482Z"
}

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

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