curl --request POST \
--url https://api.cope.com/v1/commerce/payments/{id}/refunds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount_cents": 2
}
'import requests
url = "https://api.cope.com/v1/commerce/payments/{id}/refunds"
payload = { "amount_cents": 2 }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({amount_cents: 2})
};
fetch('https://api.cope.com/v1/commerce/payments/{id}/refunds', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cope.com/v1/commerce/payments/{id}/refunds",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount_cents' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cope.com/v1/commerce/payments/{id}/refunds"
payload := strings.NewReader("{\n \"amount_cents\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cope.com/v1/commerce/payments/{id}/refunds")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount_cents\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cope.com/v1/commerce/payments/{id}/refunds")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount_cents\": 2\n}"
response = http.request(request)
puts response.read_bodyRefund a payment
Refunds a settled sale and returns the refund it created. Only a sale can be refunded —
passing a refund’s own id answers 404, exactly as reading it through
GET /v1/commerce/payments/{id} does.
amount_cents is the amount to return in minor units and must be a positive integer.
Omit it to refund everything still refundable on the payment: send no body, or a JSON object
without amount_cents. An explicit null is refused. It is also the only field the body
accepts: any other key is refused with 422 rather than ignored, so a misspelled field name
cannot quietly become a full refund. Query parameters are refused the same way.
Send the body as application/json; a charset parameter, a +json media type, and the
JSON synonyms text/x-json and application/jsonrequest are accepted too. A non-empty body of
a type the endpoint does not read, such as text/plain or application/octet-stream, or a
Content-Type that is not a media type, is refused with 415 unsupported_media_type; a body
that does not parse, with 400 invalid_request. Nothing is refunded in either case.
A refused refund answers 422 with one of these codes:
validation_failed— the body is not the one described above;errorsnames each member.refund_not_available— the payment cannot be refunded at all: it is already charged back, already fully refunded, past its refund window, split across tenders, or has nothing left to refund, or it was taken through PayPal while PayPal refunds are not enabled for it.detailsays which.refund_exceeds_limit—amount_centsis more than is still refundable on the payment.insufficient_seller_balance— the seller’s balance is below zero (see below).paypal_merchant_not_found— a PayPal sale whose seller no longer has an active PayPal account connected to COPE.payment_fully_refundedorrefund_window_expired— the payment’s state changed while the request was being processed, for example because a concurrent refund took what was left.
Each of these codes comes with a detail that says in words what happened, such as
“The seller’s balance cannot fund a refund right now.” for insufficient_seller_balance. Branch on
code; detail is for people and its wording may change.
Seller balance. A refund is paid out of the seller’s balance in the payment’s currency and
payment provider. Sale proceeds count towards the available balance only once their release
date has passed, while a refund is debited on the day it is made, so refunds can take the
available balance below zero while proceeds are still waiting to be released. The refund is
refused with insufficient_seller_balance while that available balance is below zero, and the
same request succeeds once enough proceeds have been released. On a PayPal sale the same code is
also returned when PayPal refuses the refund because the seller’s PayPal account cannot fund it;
that clears once the PayPal balance covers the refund.
A refund that could not be attempted answers 503 instead, with nothing refunded:
sale_not_yet_booked (the sale is not yet recorded in COPE’s ledger, which follows the payment
within moments), refund_in_progress (another refund of the same payment is being processed) or
seller_balance_unavailable (the seller’s balance could not be read).
Idempotency-Key is required. A retry carrying the same key and the same body returns the
original refund; the same key with a different body is refused with 409. Two deliberate
refunds of the same size need two different keys — that is the only thing distinguishing
them from a retry. A refusal this operation answers with one of the codes listed here — a 422,
the 415, a 400 for a body that does not parse, the 502 and 503 answers below, or a 404 — is not
stored against its key, so the same request may be sent again later under the same key, and it
runs again against the payment’s state at that moment.
Requires the payments permission at write. An API key holds a permission at the lower of its own level (read for a read-only key) and its holder’s role; a key without it is refused with 403.
curl --request POST \
--url https://api.cope.com/v1/commerce/payments/{id}/refunds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount_cents": 2
}
'import requests
url = "https://api.cope.com/v1/commerce/payments/{id}/refunds"
payload = { "amount_cents": 2 }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({amount_cents: 2})
};
fetch('https://api.cope.com/v1/commerce/payments/{id}/refunds', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cope.com/v1/commerce/payments/{id}/refunds",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount_cents' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cope.com/v1/commerce/payments/{id}/refunds"
payload := strings.NewReader("{\n \"amount_cents\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cope.com/v1/commerce/payments/{id}/refunds")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount_cents\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cope.com/v1/commerce/payments/{id}/refunds")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount_cents\": 2\n}"
response = http.request(request)
puts response.read_bodyAuthorizations
Headers
Required. At most 255 characters of valid UTF-8 with no NUL byte. A retry that carries the same key and the same body returns the original response instead of performing the write a second time. The same key with a different body is refused with 409 idempotency_conflict. Keys are remembered for 24 hours. A returned original response carries the header Idempotent-Replayed: true.
255Path Parameters
Body
Was this page helpful?