Create a refund
curl --request POST \
--url https://merchant-api-prod.anyway.sh/v1/refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"orderId": "<string>",
"amountCents": 123
}
'import requests
url = "https://merchant-api-prod.anyway.sh/v1/refunds"
payload = {
"orderId": "<string>",
"amountCents": 123
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({orderId: '<string>', amountCents: 123})
};
fetch('https://merchant-api-prod.anyway.sh/v1/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://merchant-api-prod.anyway.sh/v1/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([
'orderId' => '<string>',
'amountCents' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-API-Key: <api-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://merchant-api-prod.anyway.sh/v1/refunds"
payload := strings.NewReader("{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
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://merchant-api-prod.anyway.sh/v1/refunds")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://merchant-api-prod.anyway.sh/v1/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["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}"
response = http.request(request)
puts response.read_body{
"data": {
"amountCents": 123,
"createdAt": "<string>",
"currency": "<string>",
"failedAt": "<string>",
"failureReason": "<string>",
"fullyRefunded": true,
"orderId": "<string>",
"orgId": "<string>",
"reason": "<string>",
"refundId": "<string>",
"refundedAt": "<string>",
"status": "<string>",
"totalRefundedCents": 123
},
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": {
"amountCents": 123,
"createdAt": "<string>",
"currency": "<string>",
"failedAt": "<string>",
"failureReason": "<string>",
"fullyRefunded": true,
"orderId": "<string>",
"orgId": "<string>",
"reason": "<string>",
"refundId": "<string>",
"refundedAt": "<string>",
"status": "<string>",
"totalRefundedCents": 123
},
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}Merchant API endpoints
Create a refund
Refund a card order, in full or in part.
POST
/
v1
/
refunds
Create a refund
curl --request POST \
--url https://merchant-api-prod.anyway.sh/v1/refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"orderId": "<string>",
"amountCents": 123
}
'import requests
url = "https://merchant-api-prod.anyway.sh/v1/refunds"
payload = {
"orderId": "<string>",
"amountCents": 123
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({orderId: '<string>', amountCents: 123})
};
fetch('https://merchant-api-prod.anyway.sh/v1/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://merchant-api-prod.anyway.sh/v1/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([
'orderId' => '<string>',
'amountCents' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-API-Key: <api-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://merchant-api-prod.anyway.sh/v1/refunds"
payload := strings.NewReader("{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
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://merchant-api-prod.anyway.sh/v1/refunds")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://merchant-api-prod.anyway.sh/v1/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["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"orderId\": \"<string>\",\n \"amountCents\": 123\n}"
response = http.request(request)
puts response.read_body{
"data": {
"amountCents": 123,
"createdAt": "<string>",
"currency": "<string>",
"failedAt": "<string>",
"failureReason": "<string>",
"fullyRefunded": true,
"orderId": "<string>",
"orgId": "<string>",
"reason": "<string>",
"refundId": "<string>",
"refundedAt": "<string>",
"status": "<string>",
"totalRefundedCents": 123
},
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": {
"amountCents": 123,
"createdAt": "<string>",
"currency": "<string>",
"failedAt": "<string>",
"failureReason": "<string>",
"fullyRefunded": true,
"orderId": "<string>",
"orgId": "<string>",
"reason": "<string>",
"refundId": "<string>",
"refundedAt": "<string>",
"status": "<string>",
"totalRefundedCents": 123
},
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}{
"data": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
},
"message": "<string>",
"success": true
}Authenticate with an API key that belongs to the target organization and has Full access or the
sales:refunds:execute permission. Only the Owner, Admin and Finance roles can grant it.
- Refunds through the API work only after Anyway has enabled them for your organization; contact Anyway support to turn it on. Until then a refund on one of your orders returns
403REFUND_API_NOT_ENABLED, whatever the key. Order errors, such as404for an unknown order, come first. - Takes the same inputs as the Refund button on an order in the dashboard. Omit
amountCentsto refund everything still refundable.reasonis optional:duplicate,fraudulentorrequested_by_customer. The currency is always the order’s. - Send a unique
Idempotency-Keyheader (required; 1–200 ASCII characters from0x21to0x7E, no spaces). The same key with the same body returns the same refund and never refunds twice. The same key with a different order, amount or reason returns409. - Card orders up to 90 days old only. Contact Anyway support for older orders.
200withstatussucceededmeans the refund is done.202withstatuspendingmeans it waits for Anyway’s review or for the card network. Review applies when the refund brings the order’s total refunded to the approval threshold or above, or takes your organization past its daily refund limit (shared with dashboard refunds); only one refund per order can wait for review at a time. Retry with the sameIdempotency-Keyto get its current state, or wait for therefund.succeededorrefund.failedWebhook.- The response is the same refund object as Get a refund. API refunds also show on the order in the dashboard.
| Status | Code | Meaning |
|---|---|---|
400 | BAD_REQUEST | A missing or invalid Idempotency-Key, an unknown field, an amount of 0 or less, or an invalid reason. |
400 | REFUND_AMOUNT_TOO_LARGE | amountCents is more than is left to refund on the order. |
400 | REFUND_NOT_REFUNDABLE | amountCents was omitted and nothing is left to refund on the order. |
400 | REFUND_UNSUPPORTED_METHOD | The order wasn’t paid by card. |
400 | REFUND_WINDOW_EXPIRED | The order is older than 90 days. |
400 | amount_too_large, charge_already_refunded or charge_disputed | The card network refuses it: more than is left to refund, already fully refunded, or disputed. |
401 | The API key is missing or invalid. | |
403 | INSUFFICIENT_SCOPE | The key lacks sales:refunds:execute. |
403 | REFUND_API_NOT_ENABLED | Refunds through the API aren’t enabled for your organization. Contact Anyway support. |
404 | Unknown order ID, or it belongs to another organization. | |
409 | REFUND_PENDING_EXISTS | Another refund on this order is waiting for review. |
409 | REFUND_IDEMPOTENCY_MISMATCH | The Idempotency-Key was already used with a different order, amount or reason. |
409 | REFUND_FAILED or REFUND_REJECTED | The refund for this Idempotency-Key already failed or was rejected. Send a new key to try again. |
503 | REFUND_UNAVAILABLE | The payment provider is busy or down, or this refund is still in progress. Retry with the same Idempotency-Key. |
Headers
Body
application/json
Order and amount