Get Payment Link

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

import requests

url = "https://api.prod.finverse.net/payment_links/{paymentLinkId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.prod.finverse.net/payment_links/{paymentLinkId}', 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/payment_links/{paymentLinkId}",
  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/payment_links/{paymentLinkId}"

	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/payment_links/{paymentLinkId}")

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": 10000,
  "created_at": "2024-04-22T02:48:22.688Z",
  "currency": "HKD",
  "link_customizations": {
    "language": "en"
  },
  "metadata": {
    "key": "value",
    "tracking_flow": "webapp-checkout"
  },
  "mode": "PAYMENT",
  "payment_details": {
    "description": "TEST Payment",
    "external_transaction_reference": "INV12345"
  },
  "payment_link_id": "01HW1V8PX04GHM6Q8ZAR7DPRAT",
  "payment_metadata": {
    "contract_id": "1234",
    "key": "value"
  },
  "sender": {
    "email": "[email protected]",
    "external_user_id": "user_id_1||1713754102",
    "name": "John Doe",
    "user_id": "01HW1V8PXBYHY2T0N121R50Q5V"
  },
  "session_status": "OPEN",
  "status": "CREATED",
  "unique_reference_id": "Inv12345|1713754102",
  "updated_at": "2024-04-22T02:48:22.688Z",
  "url": "https://pay.prod.finverse.net/link/01HW1V8PX04GHM6Q8ZAR7DPRAT"
}

Payment links

Get Payment Link

Retrieve a Payment Link object (using a specific payment_link_id).

Authorization: customer_token

Response fields

Single Payment Link object, containing information on the Payment Link.

payment (object)

Latest Payment object (if any) associated with the payment link.

Refer to the Payment data model in GET /payments/{payment_id} for details on the Payment object.

Only returned if mode = PAYMENT, once a Payment has started processing or is executed/failed.

payment_details (object, optional)

Details describing the requested payment.

Only returned if mode = PAYMENT.

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.

Currently, only returned for payment methods that are stored. The following payment methods are not stored:

(i) one-time payment methods (e.g. FPS);

(ii) recurring payment methods authorized for only one-time use (e.g. cards/mandates where Future Payments are not enabled).

For one-time card payments (i.e. where cards are not stored), some card details are included in the Payments object, when available from the card processing gateway (see payment_links.payments.payment_methods or payments.payment_methods).

payment_setup_options (object)

Additional parameters recording how payment methods and future payments have been configured.

sender (object)

The sender object includes a Payment User object for the sender of the 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).

GET

payment_links

{paymentLinkId}

Get Payment Link

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

import requests

url = "https://api.prod.finverse.net/payment_links/{paymentLinkId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.prod.finverse.net/payment_links/{paymentLinkId}', 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/payment_links/{paymentLinkId}",
  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/payment_links/{paymentLinkId}"

	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/payment_links/{paymentLinkId}")

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": 10000,
  "created_at": "2024-04-22T02:48:22.688Z",
  "currency": "HKD",
  "link_customizations": {
    "language": "en"
  },
  "metadata": {
    "key": "value",
    "tracking_flow": "webapp-checkout"
  },
  "mode": "PAYMENT",
  "payment_details": {
    "description": "TEST Payment",
    "external_transaction_reference": "INV12345"
  },
  "payment_link_id": "01HW1V8PX04GHM6Q8ZAR7DPRAT",
  "payment_metadata": {
    "contract_id": "1234",
    "key": "value"
  },
  "sender": {
    "email": "[email protected]",
    "external_user_id": "user_id_1||1713754102",
    "name": "John Doe",
    "user_id": "01HW1V8PXBYHY2T0N121R50Q5V"
  },
  "session_status": "OPEN",
  "status": "CREATED",
  "unique_reference_id": "Inv12345|1713754102",
  "updated_at": "2024-04-22T02:48:22.688Z",
  "url": "https://pay.prod.finverse.net/link/01HW1V8PX04GHM6Q8ZAR7DPRAT"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

paymentLinkId

string

required

The payment link id

Minimum string length: 1

Response

Success (Link created)

amount

integer

Amount of the payment (in minor currency unit). Only returned if mode = PAYMENT.

Example:

100

created_at

string<date-time>

Timestamp when the payment link was first created

currency

string

Currency of the payment (e.g. HKD)

Example:

"HKD"

integration_metadata

object

Show child attributes

link_customizations

object

Optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements. See POST /payment_links.

Show child attributes

metadata

object

Customer-supplied attributes in key:value format. E.g. contract_id: 1234.

Show child attributes

mode

enum<string>

Specified payment link mode. Possible values: - PAYMENT: payment link is used to collect the specified payment amount now; - SETUP: payment link is used to register a payment method to be charged later (using POST /payments).

Available options:

PAYMENT

Example:

"PAYMENT"

payment

object

Latest Payment object (if any) associated with the payment link Only returned if mode = PAYMENT.

Show child attributes

payment_details

object

Details on the payment Only returned if mode = PAYMENT.

Show child attributes

payment_link_id

string

Finverse Payment Link ID for this payment link. Always unique. Creating a payment link with different unique_reference_id values will result in two payment links with different IDs.

payment_metadata

object

Customer-supplied attributes in key:value format, to facilitate payment reconciliation. E.g. contract_id: 1234. These will be added as metadata on any Payment object directly created by the Payment Link, and will be included in Finverse's reporting (e.g. statements issued to customer apps). Only used if mode = PAYMENT. Will be ignored if mode = SETUP.

Show child attributes

payment_method

object

Details on the payment method authorized by the end-user

Show child attributes

payment_setup_options

object

Additional parameters recording how payment methods and future payments have been configured

Show child attributes

sender

object

Details on the sender of the payment

Show child attributes

session_status

enum<string>

Current session status of the payment link. Possible values: OPEN, PROCESSING, COMPLETE, FAILED. Session status returns interim status details on a payment link in status = CREATED: - Session status starts as OPEN, then may progress to PROCESSING (indicating an async payment method or payment is currently processing), COMPLETE (for successful payment links), or FAILED (for failed payment method setup or payments). - Session status is computed at read-time based on the status of any payment method setup or payment initiated by the payment link, until the payment link is successful. - Session status may reset if a user retries a payment method setup or payment using the same payment link until it is successful (e.g. session_status may go from FAILED > PROCESSING, FAILED > COMPLETE, etc). - The final session_status is COMPLETE, which corresponds to payment link status = PAID or SETUP_SUCCEEDED. We recommend using the payment link status as the primary indicator of payment link success (e.g. status = PAID or SETUP_CREATED). However, if your user flow or UI needs interim session details while the payment link status is still CREATED, then you should use session_status (for example to display to the user a "Your payment is processing" or "Your payment failed" message).

Available options:

OPEN,

PROCESSING,

COMPLETE,

FAILED

status

enum<string>

Status of the payment link. Possible values: CREATED, PAID, SETUP_SUCCEEDED, CANCELLED. The status for a successful payment link varies based on the payment link mode: - mode = PAYMENT => success status = PAID - mode = SETUP => success status = SETUP_SUCCEEDED.

Available options:

CREATED,

PAID,

EXPIRED

unique_reference_id

string

Customer-supplied string, uniquely identifying the payment to be collected. See “Handling retries and avoiding duplicate payments” under POST /payment_links.

Minimum string length: 1

updated_at

string<date-time>

Timestamp of the last update to the payment link's record

url

string

URL to launch the Finverse Link UI flow, for the end-user to select a payment method & authorize the payment.