Refund a payment

POSThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/payments/{payment_id}/refund

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_idrequired

Body application/json

cURL request

curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payments/PAYMENT_ID/refund \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "refund": {
    "amount": "10.00",
    "reason": "Customer returned item",
    "manual": false
  }
}'

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payments/PAYMENT_ID/refund';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <base64 of SECRET_KEY:>',
    'Content-Type': 'application/json'
  },
  body: '{"refund":{"amount":"10.00","reason":"Customer returned item","manual":false}}'
};

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/payments/PAYMENT_ID/refund"

payload = { "refund": {
        "amount": "10.00",
        "reason": "Customer returned item",
        "manual": False
    } }
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/payments/PAYMENT_ID/refund', [
  'body' => '{
  "refund": {
    "amount": "10.00",
    "reason": "Customer returned item",
    "manual": false
  }
}',
  '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/payments/PAYMENT_ID/refund")

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  \"refund\": {\n    \"amount\": \"10.00\",\n    \"reason\": \"Customer returned item\",\n    \"manual\": false\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/payments/PAYMENT_ID/refund"

  payload := strings.NewReader("{\n  \"refund\": {\n    \"amount\": \"10.00\",\n    \"reason\": \"Customer returned item\",\n    \"manual\": false\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/payments/PAYMENT_ID/refund \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "refund": {
    "amount": "10.00",
    "reason": "Customer returned item",
    "manual": false
  }
}'

const url = 'https://app.shuttleglobal.com/c/api/payments/PAYMENT_ID/refund';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN', 'Content-Type': 'application/json'},
  body: '{"refund":{"amount":"10.00","reason":"Customer returned item","manual":false}}'
};

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/payments/PAYMENT_ID/refund"

payload = { "refund": {
        "amount": "10.00",
        "reason": "Customer returned item",
        "manual": False
    } }
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/payments/PAYMENT_ID/refund', [
  'body' => '{
  "refund": {
    "amount": "10.00",
    "reason": "Customer returned item",
    "manual": false
  }
}',
  '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/payments/PAYMENT_ID/refund")

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  \"refund\": {\n    \"amount\": \"10.00\",\n    \"reason\": \"Customer returned item\",\n    \"manual\": false\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/payments/PAYMENT_ID/refund"

  payload := strings.NewReader("{\n  \"refund\": {\n    \"amount\": \"10.00\",\n    \"reason\": \"Customer returned item\",\n    \"manual\": false\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

Refund processed

{
  "refund": {
    "id": "ref_11842_11073",
    "payment": "pay_11842_11072",
    "amount": "10",
    "created": "2020-11-27T15:17:15.000Z",
    "processed": "2020-11-27T15:17:18.000Z",
    "reason": "Customer requested cancellation",
    "reference": "BOLT-00011073",
    "source_transaction": "tr_11842_11072",
    "status": "SUCCESS",
    "gateway_status": "APPROVED",
    "gateway_message": "string",
    "manual": false,
    "currency": "USD",
    "account": "string",
    "parts": [
      {}
    ],
    "offline": false,
    "updated": "2026-01-01T12:00:00Z",
    "v": 0
  }
}

POST

/payments/{payment_id}/refund

You can refund a payment in part or full, or simply mark a payment as refunded (if refunded offline). You can refund “PAYMENT” and “CAPTURE” type transactions, but not “AUTH” (void an AUTH to release what is still reserved on it).

Note, support for multi-refund (e.g., I pay $100 and refund $20 followed by a second refund of $80) is not available on all gateways.

Authorizations

basicAuth
bearerAuth

Parameters

Path Parameters

payment_id

required

string

e.g. "tr_11842_10000"

The payment’s ID (pay_...), capture ID (ca_...) or transaction ID (tr_...), or the alt_key you gave it (case-insensitive). The record must be a payment or capture, otherwise 404 Payment not found. An alt_key resolves to the newest payment or capture with that key, ignoring failed attempts; if another one with the same alt_key was created in the last six months, the request fails with Duplicate alt_key.

Request Body^required

application/json

object

refund

object

amount

string

e.g. "10.00"

(Optional) The amount of the refund as a string e.g., “10”. The amount should not have commas and use a . as a decimal separator. If omitted, the entire unrefunded amount of the transaction will be refunded.

reason

required

string

e.g. "Customer returned item"

The reason for the refund (free text)

manual

boolean

(Optional) Set to true if you do not want to process the refund via the gateway, but simply record that a refund was performed offline.

Responses

200

Refund processed

application/json

object

refund

object

string

e.g. "ref_11842_11073"

The unique ID of the refund

payment

string

e.g. "pay_11842_11072"

The original payment this refund relates to

amount

string

e.g. "10"

The amount refunded

created

string · date-time

e.g. "2020-11-27T15:17:15.000Z"

When the refund was created/instructed

processed

string · date-time

e.g. "2020-11-27T15:17:18.000Z"

When the refund completed processing

reason

string

e.g. "Customer requested cancellation"

The reason for the refund

reference

string

e.g. "BOLT-00011073"

A unique customer facing reference for the refund

source_transaction

string

e.g. "tr_11842_11072"

The original transaction that is being refunded - may be a payment or a capture

status

string · enum

The status of the refund transaction

Allowed values: SUCCESS PENDING DECLINED INVALID_PAYMENT_METHOD UNRESOLVED UNATTRIBUTED

gateway_status

string · enum

The gateway status of the refund transaction

Allowed values: APPROVED PENDING DECLINED DECLINED_ERROR UNRESOLVED MANUAL

gateway_message

string

The message from the gateway (if pending or declined)

manual

boolean

False if the refund was instructed, or true if it was only recorded (in which case the onus is on the user to perform the refund via an offline method)

currency

string

e.g. "USD"

The currency of the refund (always the same as source transaction)

account

string

The ID of the person this refund is for

parts

Array<object>

An array of parts objects for which charge(s) the refund was applied to

object

offline

boolean

True if this is just a record to indicate a refund was performed offline

updated

string · date-time

The date the record was last updated

integer

The version of the record

400

Bad request - invalid parameters

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 - invalid credentials

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

Payment 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.

Was this page helpful?

Refund a payment

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

400

401

404

Request Body^required