Cancel Payment Link

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

import requests

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

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

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

print(response.text)

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

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

{
  "amount": 10000,
  "created_at": "2024-08-16T15:32:09.814Z",
  "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": "01J5DX2KYPS8E35HRTPVM545B1",
  "payment_metadata": {
    "contract_id": "1234",
    "key": "value"
  },
  "sender": {
    "email": "[email protected]",
    "external_user_id": "user_id_1||1723822330",
    "name": "John Doe",
    "user_id": "01J5DX2KZ39YTKMDHGFTAVT2XR"
  },
  "session_status": "OPEN",
  "status": "CANCELLED",
  "unique_reference_id": "Inv12345|1723822330",
  "updated_at": "2024-08-16T15:32:12.980Z",
  "url": "https://pay.prod.finverse.net/link/01J5DX2KYPS8E35HRTPVM545B1"
}

Payment links

Cancel Payment Link

Cancel a Payment Link (using a specific payment_link_id). This sets the Payment Link status to CANCELLED and Finverse will no longer process any user inputs or payments for the Payment Link.

Cancellation is optional.

Authorization: customer_token

Response fields

The response is a Payment Link object, or an error object if the Payment Llink is not cancellable (e.g. payment is already processing).

Refer to Payment Link object data model in GET /payments_links/{payment_link_id}.

POST

payment_links

{paymentLinkId}

cancel

Cancel Payment Link

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

import requests

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

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

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

print(response.text)

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

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

{
  "amount": 10000,
  "created_at": "2024-08-16T15:32:09.814Z",
  "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": "01J5DX2KYPS8E35HRTPVM545B1",
  "payment_metadata": {
    "contract_id": "1234",
    "key": "value"
  },
  "sender": {
    "email": "[email protected]",
    "external_user_id": "user_id_1||1723822330",
    "name": "John Doe",
    "user_id": "01J5DX2KZ39YTKMDHGFTAVT2XR"
  },
  "session_status": "OPEN",
  "status": "CANCELLED",
  "unique_reference_id": "Inv12345|1723822330",
  "updated_at": "2024-08-16T15:32:12.980Z",
  "url": "https://pay.prod.finverse.net/link/01J5DX2KYPS8E35HRTPVM545B1"
}

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 cancelled)

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.