Get a payment link by ID

GEThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/payment_links/{id}

Language

Credentials

Secret key

Instance keyRemember on this device

Kept in this browser tab unless you tick Remember; don't on a shared computer. Use keys from a sandbox account to test without moving money.

Parameters

Path

idrequired

Query

expand

cURL request

curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID';
const options = {method: 'GET', headers: {Authorization: 'Basic <base64 of SECRET_KEY:>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID"

headers = {"Authorization": "Basic <base64 of SECRET_KEY:>"}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID', [
  'headers' => [
    'Authorization' => 'Basic <base64 of SECRET_KEY:>',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'

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

package main

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

func main() {

  url := "https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links/ID"

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

  req.Header.Add("Authorization", "Basic <base64 of SECRET_KEY:>")

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

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

  fmt.Println(res)
  fmt.Println(string(body))

}

const url = 'https://app.shuttleglobal.com/c/api/payment_links/ID';
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://app.shuttleglobal.com/c/api/payment_links/ID"

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/payment_links/ID', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/payment_links/ID")

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

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

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

package main

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

func main() {

  url := "https://app.shuttleglobal.com/c/api/payment_links/ID"

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

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

  fmt.Println(res)
  fmt.Println(string(body))

}

Response

Payment link details

{
  "payment_link": {
    "id": "string",
    "account": "string",
    "charge": "string",
    "client": "string",
    "contract": "string",
    "expires": "2026-01-01T12:00:00Z",
    "nonce": "string",
    "options": {
      "account": "string",
      "action": "PAYMENT",
      "allow_comment": true,
      "amount": "18.18",
      "comment": "string",
      "currency": "USD",
      "default_amount": "100.00",
      "default_comment": "string",
      "default_reference": "string",
      "name": "string",
      "page_intro": "string",
      "page_pending_message": "string",
      "page_success_message": "string",
      "pending_url": "https://example.com",
      "reference": "string",
      "source": "ECOMMERCE",
      "channel": "string",
      "force_add": true,
      "timezone": "string",
      "success_url": "https://example.com"
    },
    "payment_method": "string",
    "payment": "string",
    "state": {},
    "status": "ACTIVE",
    "transaction": "string",
    "url": "https://app.shuttleglobal.com/cp/link/{id}",
    "v": 1
  }
}

GET

/payment_links/{id}

Authorizations

basicAuth
bearerAuth

Parameters

Path Parameters

required

string

Pattern /^pl_[a-zA-Z0-9]+_[a-zA-Z0-9-]+$/

The payment link’s ID (pl_...).

Query Parameters

expand

string

Comma-separated list of fields to expand (account, contract, charge, transaction, payment_method, payment). Note: These fields will only be populated for payment links with status PAYMENT_PENDING or PAYMENT_SUCCESS.

Responses

200

Payment link details

application/json

object

payment_link

object

string

Unique identifier for the payment link (also used as payment nonce)

Pattern /^pl_[a-zA-Z0-9]+_[a-zA-Z0-9-]+$/

account

string

Associated account ID (populated on PAYMENT_PENDING or PAYMENT_SUCCESS)

charge

string

Associated charge ID (populated on PAYMENT_PENDING or PAYMENT_SUCCESS)

client

string

Client ID (read-only, derived from credentials)

Pattern /^cl_[a-zA-Z0-9]+$/

contract

string

Associated contract ID (populated on PAYMENT_PENDING or PAYMENT_SUCCESS)

expires

string · date-time

Expiry date for the payment link. Must be a future date - cannot set expiry to a past date.

nonce

string

Payment nonce for tokenization actions (same as id)

options

object

Configuration options for the payment link experience

object

account

One of:

string
object

Account ID to skip authentication section

Pattern /^acc_[0-9]+_[0-9a-z]+$/

action

string · enum

default "PAYMENT"

Action type for the payment link.

PAYMENT — take the payment immediately.
AUTH — authorise only, reserving the funds without capturing. Capture later via the Activity view or the Capture API.
TOKENISE — capture the customer’s payment details without taking a payment, producing a reusable token you can charge later.

Note the spelling: the value is TOKENISE, not TOKENIZE.

When using TOKENISE, omit amount and default_amount — the link takes no payment. save_card is redundant, as storing the card is the whole operation. Keep currency: it determines which payment methods are offered. Retrieve the stored token from the payment_method field when you fetch the payment link, or from the PAYMENT_METHOD.ACTIVE webhook.

Only payment methods capable of the requested action are displayed. For example Apple Pay does not support TOKENISE, and ACH does not support AUTH.

Allowed values: PAYMENT AUTH TOKENISE

allow_comment

boolean

Whether to enable the note/comment field

amount

string

e.g. "18.18"

Fixed amount for the payment in major currency units, as a decimal string without commas, using ‘.’ as the decimal separator (e.g. “18.18” for £18.18). If specified, the payer cannot modify it.

comment

string

Fixed note/comment for the payment (if specified, user cannot modify)

currency

string

default "USD"

Fixed currency for the payment (e.g. USD)

default_amount

string

e.g. "100.00"

Default amount in major currency units, as a decimal string without commas, using ‘.’ as the decimal separator (e.g. “100.00”). The payer can modify it.

default_comment

string

Default note/comment to show (user can modify)

default_reference

string

Default reference to show (user can modify)

name

string

Custom name for the payment link (defaults to instance name)

page_intro

string

Custom introduction message for the payment page

page_pending_message

string

Message to display to the user when their payment is pending authorization.

page_success_message

string

Message to display to the user when their payment is successful.

pending_url

string · uri

URL to redirect users when payment requires authorization. Query parameters included in redirect:

payment_link - Payment link ID
status - Will be ‘PENDING’
contract - Contract ID if created
charge - Charge ID if created
transaction - Transaction ID if created
payment_method - Payment method ID if created
account - Account ID if created If skip_receipt is true, redirect happens immediately after authorization is required. If skip_receipt is false, URL is presented after showing the pending message.

reference

string

Fixed reference for the payment (if specified, user cannot modify)

source

string · enum

default "ECOMMERCE"

Source of the payment link

Allowed values: ECOMMERCE

channel

string

Channel identifier to process the payment through

force_add

boolean

Only allow new payment methods, do not show saved payment methods

timezone

string

IANA timezone name for date/time display (e.g., America/New_York)

success_url

string · uri

URL to redirect users after successful payment completion. Query parameters included in redirect:

payment_link - Payment link ID
status - Will be ‘COMPLETED’
contract - Contract ID if created
charge - Charge ID if created
transaction - Transaction ID if created
payment_method - Payment method ID if created
account - Account ID if created If skip_receipt is true, redirect happens immediately after successful authorization. If skip_receipt is false, URL is presented as a button on the receipt page. Query parameters will be appended to this URL - see RedirectUrlParameters schema. Parameters include: payment_link, status, contract, charge, transaction, payment_method, account. Example: https://shop.example.com/success?payment_link=pl_1234_abcdef&status=COMPLETED… Use these parameters to verify payment status and retrieve additional details via API.

payment_method

string

Associated payment method ID (populated on various payment events)

payment

string

Associated payment ID (populated on PAYMENT_PENDING or PAYMENT_SUCCESS)

state

One of:

object

status

string · enum

Current status of the payment link:

ACTIVE - Payment link is available and can be used for payment
PENDING - Payment is in process (either actively processing or in an unresolved state)
COMPLETED - Payment link has been successfully paid
EXPIRED - Payment link has passed its expiration date without being paid or reaching pending state
ARCHIVE - Payment link has been deleted (soft-delete)

Status transitions:

ACTIVE → PENDING: When payment/tokenization starts
PENDING → COMPLETED: On successful payment
PENDING → ACTIVE: On failed payment attempt
Any → EXPIRED: When expiration time is reached
Any → ARCHIVE: When explicitly archived via DELETE

Allowed values: ACTIVE PENDING COMPLETED EXPIRED ARCHIVE

transaction

string

Associated transaction ID (populated on PAYMENT_PENDING or PAYMENT_SUCCESS)

url

string · uri

e.g. "https://app.shuttleglobal.com/cp/link/{id}"

Payment link URL (read-only)

integer

e.g. 1

Object version for optimistic concurrency control

401

Authentication required

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

Example

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}

404

Resource not found

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

500

Internal server error

application/json

object

error

object

type

string

message

string

Was this page helpful?