Create a payment method

POSThttps://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

Body application/json

cURL request

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

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

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"

payload = { "payment_method": { "account": "string" } }
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_methods', [
  'body' => '{
  "payment_method": {
    "account": "string"
  }
}',
  '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")

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_method\": {\n    \"account\": \"string\"\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_methods"

  payload := strings.NewReader("{\n  \"payment_method\": {\n    \"account\": \"string\"\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_methods \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_method": {
    "account": "string"
  }
}'

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

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"

payload = { "payment_method": { "account": "string" } }
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_methods', [
  'body' => '{
  "payment_method": {
    "account": "string"
  }
}',
  '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")

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_method\": {\n    \"account\": \"string\"\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_methods"

  payload := strings.NewReader("{\n  \"payment_method\": {\n    \"account\": \"string\"\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 method created

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

POST

/payment_methods

Create a new payment method. This API supports two main use cases:

Data import/copy (token import)
Third-party UI integration (payment details capture and gateway tokenization)

For third-party UI integration or custom tokenization flows, please contact support as additional gateway-specific requirements may apply.

Authorizations

basicAuth
bearerAuth

Request Body^required

application/json

object

payment_method

required

object

account

required

One of:

string
object

Account ID or CRM key

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

gateway

string

Gateway this payment method is linked to

last4

string

Last 4+ digits of the payment method identifier

manual

boolean

Must be true for token import, false for third-party UI integration

name

string

Display name of the payment method

requires_cvc

boolean

Whether CVC is required for ecommerce/MOTO payments

status

string · enum

Initial status of the payment method

Allowed values: ACTIVE FAILING

token

string

Gateway token (format varies by gateway)

type

string

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

source

string · enum

Source of the payment method

Allowed values: ECOMMERCE MOTO POS

tags

string

CSV of tags/references

metadata

object

Custom key-value pairs

object

key

additional properties

any

bin

string

Card BIN number

card_number

string

Card number. Non-digits are stripped. Required unless a bank detail set, a wallet detail set or a token is sent.

card_expiry

string

Card expiry. Alias of expiry. Accepts MMYY, MM/YY, M/YY or MYY and is stored as a month.

card_cvc

string

Card security code. Passed to the gateway and never stored.

iban

string

IBAN. Alias sepa_iban. Makes the method SEPA.

account_holder_name

string

Name on the bank account. Aliases cardholder_name, sepa_account_holder_name, ach_account_holder_name.

account_type

string

Bank account type: checking, savings or businessChecking. Alias ach_account_type. Makes the method ACH.

routing_number

string

Bank routing number. Alias ach_routing_number.

account_number

string

Bank account number. Alias ach_account_number. Makes the method BACS when no other type applies.

contracts

Array<string>

Ids of the contracts this payment method is attached to once it is active.

Responses

200

Payment method created

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

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 payment method

Authorizations

Request Bodyrequired

Responses

200

400

401

404

500

Request Body^required