Cancel or refund a card transfer
Reverses a card transfer by initiating a cancellation or refund depending on the transaction status.
In v2026.10 and later, reversing an auth-capture card-payment transfer with no captures cancels the entire capturableAmount.
In those API versions, an auth-capture card-payment transfer with one final capture is canceled or refunded depending on its processing state.
Auth-capture card-payment transfers with a non-final capture or multiple captures are not supported in those API versions.
Read our reversals guide
to learn more.
To access this endpoint using a token you'll need
to specify the /accounts/{accountID}/transfers.write scope.
curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/reversals" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.01.00" \
-d '{
"amount": 0
}'mc, _ := moov.NewClient()
var accountID string // Partner account
var transferID string
// Idempotency Key is a unique identifier for this Transfer request
// Using the github.com/google/uuid library:
idempotencyKey := moov.WithReversalsIdempotencyKey(uuid.New())
mc.ReverseTransfer(ctx, accountID, transferID, moov.CreateReversal{
Amount: 1000,
}, idempotencyKey)
import { Moov } from "@moovio/sdk";
const moov = new Moov({
security: {
username: "",
password: "",
},
});
async function run() {
const result = await moov.transfers.createReversal({
xIdempotencyKey: "b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8",
accountID: "f225b49d-911b-440b-baed-6065968b69cb",
transferID: "a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad",
createReversal: {
amount: 1000,
},
});
console.log(result);
}
run();declare(strict_types=1);
require 'vendor/autoload.php';
use Moov\MoovPhp;
use Moov\MoovPhp\Models\Components;
$sdk = MoovPhp\Moov::builder()
->setSecurity(
new Components\Security(
username: '',
password: '',
)
)
->build();
$createReversal = new Components\CreateReversal(
amount: 1000,
);
$response = $sdk->transfers->createReversal(
xIdempotencyKey: 'b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8',
accountID: 'f225b49d-911b-440b-baed-6065968b69cb',
transferID: 'a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad',
createReversal: $createReversal
);
if ($response->reversal !== null) {
// handle response
}package hello.world;
import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.errors.ReversalValidationError;
import io.moov.sdk.models.operations.CreateReversalResponse;
import java.lang.Exception;
import java.lang.Object;
public class Application {
public static void main(String[] args) throws GenericError, ReversalValidationError, Exception {
Moov sdk = Moov.builder()
.security(Security.builder()
.username("")
.password("")
.build())
.build();
CreateReversalResponse res = sdk.transfers().createReversal()
.xIdempotencyKey("b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8")
.accountID("f225b49d-911b-440b-baed-6065968b69cb")
.transferID("a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad")
.createReversal(CreateReversal.builder()
.amount(1000L)
.build())
.call();
if (res.reversal().isPresent()) {
Reversal unionValue = res.reversal().get();
Object raw = unionValue.value();
if (raw instanceof ReversedWithCancellation) {
ReversedWithCancellation reversedWithCancellationValue = (ReversedWithCancellation) raw;
// Handle reversedWithCancellation variant
} else if (raw instanceof ReversedWithRefund) {
ReversedWithRefund reversedWithRefundValue = (ReversedWithRefund) raw;
// Handle reversedWithRefund variant
} else {
// Unknown or unsupported variant
}
}
}
}from moovio_sdk import Moov
from moovio_sdk.models import components
with Moov(
security=components.Security(
username="",
password="",
),
) as moov:
res = moov.transfers.create_reversal(x_idempotency_key="b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8", account_id="f225b49d-911b-440b-baed-6065968b69cb", transfer_id="a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad", amount=1000)
# Handle response
print(res)require 'moov_ruby'
Models = ::Moov::Models
s = ::Moov::Client.new(
security: Models::Components::Security.new(
username: '',
password: ''
)
)
res = s.transfers.create_reversal(x_idempotency_key: 'b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8', account_id: 'f225b49d-911b-440b-baed-6065968b69cb', transfer_id: 'a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad', create_reversal: Models::Components::CreateReversal.new(
amount: 1000
))
unless res.reversal.nil?
# handle response
endusing Moov.Sdk;
using Moov.Sdk.Models.Components;
var sdk = new MoovClient(security: new Security() {
Username = "",
Password = "",
});
var res = await sdk.Transfers.CreateReversalAsync(
xIdempotencyKey: "b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8",
accountID: "f225b49d-911b-440b-baed-6065968b69cb",
transferID: "a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad",
body: new CreateReversal() {
Amount = 1000,
}
);
// handle response{
"cancellation": {
"cancellationID": "89ca7f54-13ba-4714-b9af-17163eae2057",
"createdOn": "2025-01-19T03:02:43.255309588Z",
"status": "completed"
}
}Response headers
x-request-id
string
required
{
"cancellation": {
"cancellationID": "string",
"status": "pending",
"createdOn": "2019-08-24T14:15:22Z"
}
}Response headers
x-request-id
string
required
{
"error": "string"
}Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
{
"error": "string"
}Response headers
x-request-id
string
required
{
"amount": "string"
}Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Response headers
x-request-id
string
required
Headers
X-Moov-Version
string
v2026.08.00 uses v2026.07.00.
A malformed value, such as 2022, returns a 404 response.
v2026.01.00
x-idempotency-key
string
required
Path parameters
accountID
string
required
transferID
string
required
Body
amount
integer<int64>
required
card-payment reversals in v2026.10 and later, a transfer with no captures uses the full capturableAmount.
For those transfers with one final capture, a cancellation uses the full capture amount, while a refund may be partial.
Response
cancellation
object
Show child attributes
cancellationID
string
required
createdOn
string<date-time>
required
status
string<enum>
required
pending,
completed,
failed
refund
object
Show child attributes
amount
object
required
Show child attributes
currency
string
required
Pattern
value
integer<int64>
required
Quantity in the smallest unit of the specified currency.
In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.
createdOn
string<date-time>
required
refundID
string
required
status
string<enum>
required
created,
pending,
completed,
failed
updatedOn
string<date-time>
required
cardDetails
object
Show child attributes
status
string<enum>
required
initiated,
confirmed,
settled,
failed,
completed
completedOn
string<date-time>
confirmedOn
string<date-time>
failedOn
string<date-time>
failureCode
string<enum>
call-issuer,
do-not-honor,
processing-error,
invalid-transaction,
invalid-amount,
no-such-issuer,
reenter-transaction,
cvv-mismatch,
lost-or-stolen,
insufficient-funds,
invalid-card-number,
invalid-merchant,
expired-card,
incorrect-pin,
transaction-not-allowed,
suspected-fraud,
amount-limit-exceeded,
velocity-limit-exceeded,
revocation-of-authorization,
card-not-activated,
issuer-not-available,
could-not-route,
cardholder-account-closed,
unknown-issue,
duplicate-transaction
initiatedOn
string<date-time>
settledOn
string<date-time>