Update a payment method

PUThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/payment_methods/{payment_method_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

payment_method_idrequired

Body application/json

cURL request

curl --request PUT \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_methods/PAYMENT_METHOD_ID \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_method": {}
}'

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_methods/PAYMENT_METHOD_ID';
const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Basic <base64 of SECRET_KEY:>',
    'Content-Type': 'application/json'
  },
  body: '{"payment_method":{}}'
};

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/PAYMENT_METHOD_ID"

payload = { "payment_method": {} }
headers = {
    "Authorization": "Basic <base64 of SECRET_KEY:>",
    "Content-Type": "application/json"
}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_methods/PAYMENT_METHOD_ID', [
  'body' => '{
  "payment_method": {}
}',
  '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_methods/PAYMENT_METHOD_ID")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_method\": {}\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_methods/PAYMENT_METHOD_ID"

  payload := strings.NewReader("{\n  \"payment_method\": {}\n}")

  req, _ := http.NewRequest("PUT", 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 PUT \
  --url https://app.shuttleglobal.com/c/api/payment_methods/PAYMENT_METHOD_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_method": {}
}'

const url = 'https://app.shuttleglobal.com/c/api/payment_methods/PAYMENT_METHOD_ID';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json'},
  body: '{"payment_method":{}}'
};

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/PAYMENT_METHOD_ID"

payload = { "payment_method": {} }
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

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

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://app.shuttleglobal.com/c/api/payment_methods/PAYMENT_METHOD_ID', [
  'body' => '{
  "payment_method": {}
}',
  '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_methods/PAYMENT_METHOD_ID")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_method\": {}\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_methods/PAYMENT_METHOD_ID"

  payload := strings.NewReader("{\n  \"payment_method\": {}\n}")

  req, _ := http.NewRequest("PUT", 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

Updated payment method

{
  "payment_method": {
    "id": "string",
    "account": "string",
    "address": {
      "country": "string",
      "line1": "string",
      "line2": "string",
      "line3": "string",
      "line4": "string",
      "line5": "string",
      "line6": "string"
    },
    "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
  }
}

PUT

/payment_methods/{payment_method_id}

Update an existing payment method’s details.

Authorizations

basicAuth
bearerAuth

Parameters

Path Parameters

payment_method_id

required

string

The payment method’s ID (pm_...), or its code.

Request Body^required

application/json

object

payment_method

required

object

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.

code

string

Your ID for this payment method

expiry

string

Expiry date in MM/YYYY format

last4

string

Last 4+ digits of the payment method identifier

manual

boolean

Must be true as only manual updates are currently supported

name

string

Display name of the payment method

requires_cvc

boolean

Whether CVC is required for ecommerce/MOTO payments

token

string

Gateway token (format varies by gateway)

tags

string

CSV of tags/references

metadata

object

Custom key-value pairs

object

key

additional properties

any

Responses

200

Updated payment method

application/json

object

payment_method

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

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?

Update a payment method

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

400

401

404

500

Request Body^required