Create a new payment link

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

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

Body application/json

cURL request

curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_link": {
    "options": {
      "amount": "18.18",
      "default_amount": "100.00",
      "skip_receipt": false,
      "source": "ECOMMERCE"
    }
  }
}'

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <base64 of SECRET_KEY:>',
    'Content-Type': 'application/json'
  },
  body: '{"payment_link":{"options":{"amount":"18.18","default_amount":"100.00","skip_receipt":false,"source":"ECOMMERCE"}}}'
};

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"

payload = { "payment_link": { "options": {
            "amount": "18.18",
            "default_amount": "100.00",
            "skip_receipt": False,
            "source": "ECOMMERCE"
        } } }
headers = {
    "Authorization": "Basic <base64 of SECRET_KEY:>",
    "Content-Type": "application/json"
}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links', [
  'body' => '{
  "payment_link": {
    "options": {
      "amount": "18.18",
      "default_amount": "100.00",
      "skip_receipt": false,
      "source": "ECOMMERCE"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Basic <base64 of SECRET_KEY:>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_link\": {\n    \"options\": {\n      \"amount\": \"18.18\",\n      \"default_amount\": \"100.00\",\n      \"skip_receipt\": false,\n      \"source\": \"ECOMMERCE\"\n    }\n  }\n}"

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

package main

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

func main() {

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

  payload := strings.NewReader("{\n  \"payment_link\": {\n    \"options\": {\n      \"amount\": \"18.18\",\n      \"default_amount\": \"100.00\",\n      \"skip_receipt\": false,\n      \"source\": \"ECOMMERCE\"\n    }\n  }\n}")

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

  req.Header.Add("Authorization", "Basic <base64 of SECRET_KEY:>")
  req.Header.Add("Content-Type", "application/json")

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

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

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

}

curl --request POST \
  --url https://app.shuttleglobal.com/c/api/payment_links \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_link": {
    "options": {
      "amount": "18.18",
      "default_amount": "100.00",
      "skip_receipt": false,
      "source": "ECOMMERCE"
    }
  }
}'

const url = 'https://app.shuttleglobal.com/c/api/payment_links';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json'},
  body: '{"payment_link":{"options":{"amount":"18.18","default_amount":"100.00","skip_receipt":false,"source":"ECOMMERCE"}}}'
};

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"

payload = { "payment_link": { "options": {
            "amount": "18.18",
            "default_amount": "100.00",
            "skip_receipt": False,
            "source": "ECOMMERCE"
        } } }
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.shuttleglobal.com/c/api/payment_links', [
  'body' => '{
  "payment_link": {
    "options": {
      "amount": "18.18",
      "default_amount": "100.00",
      "skip_receipt": false,
      "source": "ECOMMERCE"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_link\": {\n    \"options\": {\n      \"amount\": \"18.18\",\n      \"default_amount\": \"100.00\",\n      \"skip_receipt\": false,\n      \"source\": \"ECOMMERCE\"\n    }\n  }\n}"

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

package main

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

func main() {

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

  payload := strings.NewReader("{\n  \"payment_link\": {\n    \"options\": {\n      \"amount\": \"18.18\",\n      \"default_amount\": \"100.00\",\n      \"skip_receipt\": false,\n      \"source\": \"ECOMMERCE\"\n    }\n  }\n}")

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

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
  req.Header.Add("Content-Type", "application/json")

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

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

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

}

Response

Payment link created successfully

{
  "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
  }
}

POST

/payment_links

Authorizations

basicAuth
bearerAuth

Request Body^required

application/json

object

payment_link

required

object

expires

string · date-time

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

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]+$/

allow_description

boolean

Whether to allow the payer to add a comment

alt_key

string

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

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.

description

string

Fixed comment to show with payment

currency

string

Three-letter ISO currency code

Pattern /^[A-Z]{3}$/

default_alt_key

string

Default reference that user can modify

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_description

string

Default comment to show (can be changed by payer if allow_description is true)

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. Only shown on the receipt page when skip_receipt is false and no pending_url is provided.

page_success_message

string

Message to display to the user when their payment is successful. Only shown on the receipt page when skip_receipt is false and no success_url is provided.

pending_url

string · uri

URL to redirect to when a payment requires authorization (pending state). If skip_receipt is true, redirect happens immediately after payment submission. 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/pending?payment_link=pl_1234_abcdef&status=PENDING… Use these parameters to verify payment status and retrieve additional details via API.

save_card

boolean

Controls whether the payment method will be saved:

If true: Payment method will be saved with the payment
If false: Payment method won’t be saved and user won’t be given the option
If not set: User will be given the option to save their payment method

Note that save_card: false also withdraws any payment method that can only be used by storing a token first - GoCardless Direct Debit and Instant Bank Pay, for example - since those cannot be offered under a hard “never save” instruction. To take a payment that saves nothing while still offering them, leave save_card unset and use default_save_card with hide_save_card_toggle instead.

default_save_card

boolean

Initial state of the “save payment method” checkbox. The payer can still change it, and it is ignored when save_card is set. Unlike save_card, it does not restrict which payment methods are offered.

hide_save_card_toggle

boolean

Hides the “save payment method” checkbox from the payer, leaving whatever default_save_card set in force. Pair the two to express a preference rather than an instruction: do not save, but stay available to methods that need a token.

skip_receipt

boolean

Controls redirect behavior after payment submission:

true - Immediately redirect to success_url/pending_url
false - Show receipt page with messages before redirect

If true: Immediately redirect to success_url (successful payment) or pending_url (pending authorization)
If false: Show receipt page with a button to proceed to the appropriate URL

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.

state

One of:

object

Responses

200

Payment link created successfully

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"

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

400

Bad request

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.

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

Instance not found (only checked after successful authentication)

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?

Create a new payment link

Authorizations

Request Bodyrequired

Responses

200

400

401

404

500

Request Body^required