Create an instance

POSThttps://app.shuttleglobal.com/c/api/instances

Language

Credentials

Secret key

Remember 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 \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{}'

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

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"

payload = {}
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', [
  'body' => '{}',
  '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")

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

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"

  payload := strings.NewReader("{}")

  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))

}

Response

Successful operation

{
  "instance": {
    "id": "string",
    "name": "string",
    "instance_key": "string",
    "status": "ACTIVATING",
    "application": "string",
    "checkout_urls": [
      "string"
    ],
    "client": "string",
    "contact_email": "string",
    "contact_name": "string",
    "contact_phone": "string",
    "country": "string",
    "created": "2026-01-01T12:00:00Z",
    "domain": "string",
    "domains": [
      "string"
    ],
    "environment": "SANDBOX",
    "features": [
      "string"
    ],
    "last_contract": "2026-01-01T12:00:00Z",
    "last_transaction": "2026-01-01T12:00:00Z",
    "merchant_name": "string",
    "metadata": {},
    "parent": "string",
    "private_integrations": [
      "string"
    ],
    "processors": [
      "string"
    ],
    "receipt_format": "string",
    "receipt_users": [
      "string"
    ],
    "report_users": [
      "string"
    ],
    "retry_error_schedule": [
      0
    ],
    "retry_schedule": [
      0
    ],
    "secret_key": "string",
    "tcs_accepted": "2026-01-01T12:00:00Z",
    "tcs_accepted_user": "string",
    "tcs_outstanding": true,
    "terminated": "2026-01-01T12:00:00Z",
    "updated": "2026-01-01T12:00:00Z",
    "v": 0,
    "webhook_target": "string"
  }
}

POST

/instances

Create a new merchant instance

Authorizations

basicAuth

Request Body^required

application/json

object

instance

object

instance_key

required

string

Your ID for the instance (unique to the application)

name

string

The name of the instance, typically company name

checkout_urls

Array<string>

Domains where you embed the Shuttle checkout widget. Required to enable Apple Pay and Google Pay on those domains.

Only list domains where you embed checkout yourself (e.g., your platform pages). Shuttle automatically registers its own hosted pages (payment links, hosted checkout at app.shuttleglobal.com). If you only use Shuttle-hosted payment pages, this field is not needed.

contact_email

string

The contact email for the instance

contact_name

string

The contact name for the instance

contact_phone

string

The contact phone for the instance

country

string

The country for the instance

legal_entities

Array<object>

Enterprise only - an array of legal entities that can receive payment

object

code

required

string

Your ID for the entity (alphanumeric _ -, no spaces)

name

required

string

The name of the entity

country

string

The 2 digit ISO code of the country in which it is incorporated

merchant_name

string

The merchant’s display name, used for Apple Pay and Click to Pay registration. Falls back to name if not set.

receipt_format

string

Template for generating transaction references. Must contain at least one of:

#TRANSACTIONKEY# — a zero-left-padded 8-digit number, incrementing per instance from 10000 (e.g., 00010000, 00010001). Not globally unique.
#TRANSACTIONID# — the same sequence number (unpadded) prefixed with the instance’s client ID (e.g., 1234_10000). Globally unique.

Example: INV-#TRANSACTIONKEY#

Note: Some gateways require transaction references to be unique across all connections. If you are connecting multiple Shuttle instances to the same gateway account, use a unique prefix per instance (e.g., MERCHANT1-#TRANSACTIONKEY#) to avoid collisions. Alternatively, use #TRANSACTIONID# which is globally unique and requires no prefix.

Some gateways also impose a maximum length on transaction references. If the formatted reference exceeds the gateway’s limit, it will be front-trimmed – only the trailing characters are kept. Keep this in mind when designing long prefixes.

secret_key

string

Generates a per-instance API key that allows the merchant to authenticate directly against their instance without requiring the platform’s application credentials. Set to "NEW" to auto-generate a key.

On update: pass "NEW" to rotate the key, false or "" to clear it, or true to leave the existing key unchanged.

tcs_accepted

boolean

True if the user manually accepted the T&Cs - do not populate this unless you have collected proof of this

Responses

200

Successful operation

application/json

object

instance

object

string

Shuttle’s ID for the instance (globally unique)

name

string

The name of the instance, typically company name

instance_key

string

Your ID for the instance (unique to the application)

status

string · enum

The status of the instance, typically ACTIVE or INACTIVE

Allowed values: ACTIVATING ACTIVE INACTIVE

application

string

The application the instance was created in

checkout_urls

Array<string>

Domains where you embed the Shuttle checkout widget, used for Apple Pay and Google Pay domain registration.

client

string

The internal Shuttle ID for this instance

contact_email

string

The contact email provided for the instance, used when providing support

contact_name

string

The contact name provided for the instance, used when providing support

contact_phone

string

The contact phone provided for the instance, used when providing support

country

string

The country provided for the instance

created

string · date-time

The date the instance was created

domain

string

The custom domain for this instance

domains

Array<string>

A list of domains this instance is available under

environment

string · enum

Either SANDBOX or LIVE

Allowed values: SANDBOX LIVE

features

Array<string>

Enterprise only features

last_contract

string · date-time

The date of last contract creation

last_transaction

string · date-time

The date of last transaction creation

merchant_name

string

The merchant’s display name

metadata

object

A map of user defined key value pairs

object

parent

string

The parent instance ID

private_integrations

Array<string>

Any private processors that have been made available to this instance

processors

Array<string>

A list of connected processors

receipt_format

string

Template for generating transaction references. Contains #TRANSACTIONKEY# or #TRANSACTIONID#.

receipt_users

Array<string>

Enterprise only

report_users

Array<string>

Enterprise only

retry_error_schedule

Array<integer>

Custom retry schedule for errored payments (array of delays in milliseconds)

retry_schedule

Array<integer>

Custom retry schedule for declined payments (array of delays in milliseconds)

secret_key

string

Per-instance API key for direct merchant authentication. Only returned when expand=secret_key is requested.

tcs_accepted

string · date-time

If the user manually accepted the T&Cs, the date they were accepted

tcs_accepted_user

string

The user_id of the user that accepted the terms and conditions

tcs_outstanding

boolean

True if the user is required to accept the terms and conditions

terminated

string · date-time

The date the instance was terminated (status INACTIVE only)

updated

string · date-time

The date the instance was last updated

integer

The version of the record

webhook_target

string

The webhook target URL for this instance. Replaces the application-level webhook destination for this instance – events are not sent to both. Supports retry, failover, and fan-out configuration. See Webhook Destinations.

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

Unauthorized

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

Was this page helpful?

Create an instance

Authorizations

Request Bodyrequired

Responses

200

400

401

Request Body^required