List payment methods

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

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

Query

criteriaorderexpandlimitoffset

cURL request

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

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_methods';
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_methods"

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_methods', [
  '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_methods")

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_methods"

  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_methods';
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_methods"

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_methods', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

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

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_methods"

  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

List of payment methods

{
  "payment_methods": [
    {
      "id": "string",
      "account": "string",
      "address": {},
      "advanced_notice_hours": 180,
      "archived": "2026-01-01T12:00:00Z",
      "authorisation_url": "string",
      "code": "string",
      "created": "2026-01-01T12:00:00Z",
      "created_session": "string",
      "expiry": "string",
      "failing_reason": "string",
      "failing_since": "2026-01-01T12:00:00Z",
      "gateway": "string",
      "gateway_group": "string",
      "gateway_status": "string",
      "last4": "string",
      "last_used": "2026-01-01T12:00:00Z",
      "mandate_id": "string",
      "mandate_link": "string",
      "mandate_reference": "string",
      "mandate_text": "string",
      "name": "string",
      "requires_cvc": true,
      "source": "MOTO",
      "status": "ACTIVE",
      "sub_status": "string",
      "sub_status_reason": "string",
      "tags": "string",
      "metadata": {},
      "bin": "string",
      "card_holder_name": "string",
      "eci": "string",
      "network_token": true,
      "source_type": "string",
      "token": "string",
      "type": "string",
      "updated_session": "string",
      "v": 0
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

GET

/payment_methods

Search and list payment method objects with various filtering criteria.

Authorizations

basicAuth
bearerAuth

Parameters

Query Parameters

criteria

string

Search criteria for filtering payment methods. Available fields: id, account, bin, code, created, expiry, failing_since, gateway, last4, last_used, mandate_reference, source, status, sub_status, token, type, updated

Examples:

account=acc_12345_67890
status=ACTIVE
type=VISA
expiry<>2024-01;2024-12

order

string

Sort order for results. Supports any field that criteria supports. Defaults to created:desc if not specified. Append :desc for descending order. Separate multiple order fields with commas.

Examples:

order=last_used:desc
order=type,created:desc

expand

string

Fields to expand into full objects. Separate multiple fields with commas.

Available fields:

account (account object)
bin (card BIN object)
gateway (gateway object)
created_session (session object)
updated_session (session object)

Example: expand=account,gateway

limit

integer

Number of records to return: 20 if not set, at most 1000.

offset

integer

Number of records to skip before the first one returned. offset + limit can’t exceed 5000; to read further, page by a field such as created instead. See Paging through results.

Responses

200

List of payment methods

application/json

object

payment_methods

Array<object>

object

string

Unique identifier for the payment method

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

account

string

Account ID this payment method belongs to

address

object

Address fields. All fields are optional and any values are accepted to prevent interrupting payments due to address validation issues. Field behavior:

When updating an address, the entire address object is replaced with the new values
To clear/null out all address fields, set each field to an empty string Client applications can implement their own validation if needed.

object

country

string

Country code (any format accepted). Set to empty string to clear.

line1

string

First line of the address. Set to empty string to clear.

line2

string

Second line of the address. Set to empty string to clear.

line3

string

Third line of the address. Set to empty string to clear.

line4

string

City/Town. Set to empty string to clear.

line5

string

Postcode/ZIP. Set to empty string to clear.

line6

string

State/Region. Set to empty string to clear.

advanced_notice_hours

integer

e.g. 180

Number of hours this payment method requires between a payment being instructed and the funds settling at the bank. Returned by gateways for schemes that need lead time (e.g., BACS, SEPA, ACH, PAD, BECS). Absent / null for card and wallet methods.

When set, Shuttle schedules each charge and its payment attempt this many hours before the charge’s due date — the due date itself is unchanged, but the charge is generated and sent to the gateway earlier so the customer is debited on time. See the Scheduler guide for details.

archived

string · date-time

When the payment method was archived (deleted)

authorisation_url

string

Link for 3DS or equivalent process during creation

code

string

Your ID for this payment method

created

string · date-time

When the payment method was created

created_session

string

Session that created this payment method

expiry

string

Expiry date in MM/YYYY format

failing_reason

string

Reason this payment method is not working

failing_since

string · date-time

When this payment method stopped working

gateway

string

Gateway this payment method is linked to

gateway_group

string

Group identifier for gateways that support payment method sharing. When present, this payment method can be used across any gateway that shares the same gateway_group. This feature is only supported on specific gateway implementations.

gateway_status

string

Gateway’s status of the payment method

last4

string

Last 4+ digits of the payment method identifier

last_used

string · date-time

When this payment method was last used

mandate_id

string

ID of the legal mandate where applicable

mandate_link

string

Link to the legal mandate where applicable

mandate_reference

string

Customer-facing mandate reference number

mandate_text

string

Legal text of the mandate

name

string

Display name of the payment method

requires_cvc

boolean

Whether CVC is required for ecommerce/MOTO payments

source

string · enum

Where the payment method was captured

Allowed values: MOTO ECOMMERCE POS

status

string · enum

Current status of the payment method

Allowed values: ACTIVE FAILING FAILED ARCHIVE EXPIRED INACTIVE SINGLEUSE REQAUTH

sub_status

string

Free text substatus (e.g., mandate status for GOCARDLESS)

sub_status_reason

string

Description of the substatus

tags

string

CSV of tags/references

metadata

object

Custom key-value pairs

object

key

additional properties

any

bin

string

Card BIN number

card_holder_name

string

Name on the card

eci

string

Electronic Commerce Indicator value

network_token

boolean

Whether this payment method uses a network token

source_type

string

Source card type

token

string

Gateway token (only for ACTIVE and FAILING methods)

type

string

Payment method type (e.g., VISA, MASTERCARD, SEPA, ACH)

updated_session

string

Session that last updated this payment method

integer

Version of the record

meta

object

limit

integer

offset

integer

total

integer

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

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?