Cancel or refund a card transfer
Reverses a card transfer by initiating a cancellation or refund depending on the transaction status. 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.
POST
/accounts/{accountID}/transfers/{transferID}/reversals
curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/reversals" \
-H "Authorization: Bearer {token}" \
-H "X-Idempotency-Key: UUID" \
-H "x-moov-version: v2024.01.00" \
--data-raw '{
"amount": 1000 // $10.00
}'
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)
using Moov.Sdk;
using Moov.Sdk.Models.Components;
using Moov.Sdk.Models.Requests;
var sdk = new MoovClient(xMoovVersion: "<value>");
CreateReversalRequest req = new CreateReversalRequest() {
XIdempotencyKey = "b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8",
AccountID = "f225b49d-911b-440b-baed-6065968b69cb",
TransferID = "a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad",
Body = new CreateReversal() {
Amount = 1000,
},
};
var res = await sdk.Transfers.CreateReversalAsync(req);
// handle responsepackage hello.world;
import io.moov.sdk.Moov;
import io.moov.sdk.models.components.CreateReversal;
import io.moov.sdk.models.components.Security;
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;
public class Application {
public static void main(String[] args) throws GenericError, ReversalValidationError, Exception {
Moov sdk = Moov.builder()
.xMoovVersion("v2024.01.00")
.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()) {
// handle response
}
}
}require 'moov_ruby'
Models = ::Moov::Models
s = ::Moov::Client.new(
x_moov_version: 'v2024.01.00',
)
req = Models::Operations::CreateReversalRequest.new(
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,
),
)
res = s.transfers.create_reversal(request: req)
unless res.reversal.nil?
# handle response
endimport { Moov } from "@moovio/sdk";
const moov = new Moov({
xMoovVersion: "v2024.01.00",
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;
use Moov\MoovPhp\Models\Operations;
$sdk = MoovPhp\Moov::builder()
->setXMoovVersion('v2024.01.00')
->setSecurity(
new Components\Security(
username: '',
password: '',
)
)
->build();
$request = new Operations\CreateReversalRequest(
xIdempotencyKey: 'b91d00b2-4ecb-4eb4-a67f-d6f76c0b7ad8',
accountID: 'f225b49d-911b-440b-baed-6065968b69cb',
transferID: 'a17b29e2-4af6-4c9d-ad3a-dd0ded2966ad',
createReversal: new Components\CreateReversal(
amount: 1000,
),
);
$response = $sdk->transfers->createReversal(
request: $request
);
if ($response->reversal !== null) {
// handle response
}from moovio_sdk import Moov
from moovio_sdk.models import components
with Moov(
x_moov_version="v2024.01.00",
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)Successfully initiated a reversal.
{
"cancellation": {
"cancellationID": "89ca7f54-13ba-4714-b9af-17163eae2057",
"createdOn": "2025-01-19T03:02:43.255309588Z",
"status": "completed"
}
}{
"refund": {
"amount": {
"currency": "USD",
"value": 1938
},
"cardDetails": {
"confirmedOn": "2025-01-19T03:07:26.602114307Z",
"status": "confirmed"
},
"createdOn": "2025-01-19T03:07:26.001024809Z",
"refundID": "89ca7f54-13ba-4714-b9af-17163eae2057",
"status": "pending",
"updatedOn": "2025-01-19T03:07:26.602114307Z"
}
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Successfully initiated a reversal but an error occurred while waiting for a synchronous response.
Contains either a cancellation or refund, depending on the method used to reverse the transfer.
{
"cancellation": {
"cancellationID": "string",
"status": "pending",
"createdOn": "2019-08-24T14:15:22Z"
}
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The server could not understand the request due to invalid syntax.
{
"error": "string"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request contained missing or expired authentication.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The user is not authorized to make the request.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The requested resource was not found.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request conflicted with the current state of the target resource.
{
"error": "string"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.
{
"amount": "string"
}Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Request was refused due to rate limiting.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed due to an unexpected error.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
The request failed because a downstream service failed to respond.
Response headers
x-request-id
string
required
A unique identifier used to trace requests.
Headers
X-Moov-Version
string
Specify an API version.
API versioning follows the format vYYYY.QQ.BB, where
YYYYis the yearQQis the two-digit month for the first month of the quarter (e.g., 01, 04, 07, 10)BBis the build number, starting at.01, for subsequent builds in the same quarter.- For example,
v2024.01.00is the initial release of the first quarter of 2024.
- For example,
The latest version represents the most recent development state. It may include breaking changes and should be treated as a beta release.
When no version is specified, the API defaults to v2024.01.00.
x-idempotency-key
string
required
Prevents duplicate reversals from being created.
Path parameters
accountID
string
required
The Moov account ID.
transferID
string
required
The transfer ID to reverse.
Body
application/json
amount
integer<int64>
required
Amount to reverse in cents. Partial amounts will automatically trigger a refund instead of a cancellation.
Response
cancellation
object
Show child attributes
cancellationID
string
required
createdOn
string<date-time>
required
status
string<enum>
required
Possible values:
pending,
completed,
failed
refund
object
Details of a card refund.
Show child attributes
amount
object
required
Show child attributes
currency
string
required
Pattern
A 3-letter ISO 4217 currency code.
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
Identifier for the refund.
status
string<enum>
required
Possible values:
created,
pending,
completed,
failed
updatedOn
string<date-time>
required
cardDetails
object
Show child attributes
status
string<enum>
required
Possible values:
initiated,
confirmed,
settled,
failed,
completed
completedOn
string<date-time>
confirmedOn
string<date-time>
failedOn
string<date-time>
failureCode
string<enum>
initiatedOn
string<date-time>
settledOn
string<date-time>