Create a refund
Initiate a refund for a card transfer.
Use the Cancel or refund a card transfer endpoint for more comprehensive cancel and refund options.
See the reversals guide for more information.
To access this endpoint using an access token
you'll need to specify the /accounts/{accountID}/transfers.write scope.
curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/refunds" \
-H "Authorization: Bearer {token}" \
-H "X-Moov-Version: v2026.07.00"mc, _ := moov.NewClient()
var accountID string
var transferID string
mc.RefundTransfer(ctx, accountID, transferID, moov.CreateRefund{
Amount: 1700,
})
import { Moov } from "@moovio/sdk";
const moov = new Moov({
security: {
username: "",
password: "",
},
});
async function run() {
const result = await moov.transfers.initiateRefund({
xIdempotencyKey: "8d9af6b8-67e1-4efa-8188-68039f34097d",
accountID: "cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2",
transferID: "04022119-95be-4ef4-9dd4-b3782f6aa7b9",
createRefund: {
amountDetails: {
surcharge: {
currency: "USD",
valueDecimal: "12.987654321",
},
},
},
});
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()
->setSecurity(
new Components\Security(
username: '',
password: '',
)
)
->build();
$request = new Operations\InitiateRefundRequest(
xIdempotencyKey: '8d9af6b8-67e1-4efa-8188-68039f34097d',
accountID: 'cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2',
transferID: '04022119-95be-4ef4-9dd4-b3782f6aa7b9',
createRefund: new Components\CreateRefund(
amountDetails: new Components\RefundAmountDetails(
surcharge: new Components\AmountDecimal(
currency: 'USD',
valueDecimal: '12.987654321',
),
),
),
);
$response = $sdk->transfers->initiateRefund(
request: $request
);
if ($response->createRefundResponse !== null) {
// handle response
}package hello.world;
import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.*;
import io.moov.sdk.models.operations.InitiateRefundRequest;
import io.moov.sdk.models.operations.InitiateRefundResponse;
import java.lang.Exception;
import java.lang.Object;
public class Application {
public static void main(String[] args) throws GenericError, CardAcquiringRefund, RefundValidationError, Exception {
Moov sdk = Moov.builder()
.security(Security.builder()
.username("")
.password("")
.build())
.build();
InitiateRefundRequest req = InitiateRefundRequest.builder()
.xIdempotencyKey("8d9af6b8-67e1-4efa-8188-68039f34097d")
.accountID("cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2")
.transferID("04022119-95be-4ef4-9dd4-b3782f6aa7b9")
.createRefund(CreateRefund.builder()
.amountDetails(RefundAmountDetails.builder()
.surcharge(AmountDecimal.builder()
.currency("USD")
.valueDecimal("12.987654321")
.build())
.build())
.build())
.build();
InitiateRefundResponse res = sdk.transfers().initiateRefund()
.request(req)
.call();
if (res.createRefundResponse().isPresent()) {
CreateRefundResponse unionValue = res.createRefundResponse().get();
Object raw = unionValue.value();
if (raw instanceof io.moov.sdk.models.components.CardAcquiringRefund) {
io.moov.sdk.models.components.CardAcquiringRefund cardAcquiringRefundValue = (io.moov.sdk.models.components.CardAcquiringRefund) raw;
// Handle cardAcquiringRefund variant
} else if (raw instanceof AsyncCreatedRefund) {
AsyncCreatedRefund yncCreatedRefundValue = (AsyncCreatedRefund) raw;
// Handle asyncCreatedRefund 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.initiate_refund(x_idempotency_key="8d9af6b8-67e1-4efa-8188-68039f34097d", account_id="cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2", transfer_id="04022119-95be-4ef4-9dd4-b3782f6aa7b9", amount_details={
"surcharge": {
"currency": "USD",
"value_decimal": "12.987654321",
},
})
# Handle response
print(res)require 'moov_ruby'
Models = ::Moov::Models
s = ::Moov::Client.new(
security: Models::Components::Security.new(
username: '',
password: ''
)
)
req = Models::Operations::InitiateRefundRequest.new(
x_idempotency_key: '8d9af6b8-67e1-4efa-8188-68039f34097d',
account_id: 'cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2',
transfer_id: '04022119-95be-4ef4-9dd4-b3782f6aa7b9',
create_refund: Models::Components::CreateRefund.new(
amount_details: Models::Components::RefundAmountDetails.new(
surcharge: Models::Components::AmountDecimal.new(
currency: 'USD',
value_decimal: '12.987654321'
)
)
)
)
res = s.transfers.initiate_refund(request: req)
unless res.create_refund_response.nil?
# handle response
endusing Moov.Sdk;
using Moov.Sdk.Models.Components;
using Moov.Sdk.Models.Requests;
var sdk = new MoovClient(security: new Security() {
Username = "",
Password = "",
});
InitiateRefundRequest req = new InitiateRefundRequest() {
XIdempotencyKey = "8d9af6b8-67e1-4efa-8188-68039f34097d",
AccountID = "cb6ae9f9-afab-4f06-9eb0-8abf54a3ada2",
TransferID = "04022119-95be-4ef4-9dd4-b3782f6aa7b9",
Body = new CreateRefund() {
AmountDetails = new RefundAmountDetails() {
Surcharge = new AmountDecimal() {
Currency = "USD",
ValueDecimal = "12.987654321",
},
},
},
};
var res = await sdk.Transfers.InitiateRefundAsync(req);
// handle response{
"amount": {
"currency": "USD"
},
"createdOn": "2023-09-09T14:15:22Z",
"refundID": "d4963079-5b35-4d17-981e-8f851753f786"
}{
"amount": {
"currency": "USD"
},
"cardDetails": {
"confirmedOn": "2023-09-09T14:17:41Z",
"initiatedOn": "2023-09-09T14:16:22Z",
"status": "confirmed"
},
"createdOn": "2023-09-09T14:15:22Z",
"refundID": "d4963079-5b35-4d17-981e-8f851753f786",
"status": "pending",
"updatedOn": "2023-09-09T14:17:41Z"
}Response headers
x-request-id
string
required
{
"refundID": "string",
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z",
"status": "created",
"amount": {
"currency": "USD",
"value": 1204
},
"amountDetails": {
"surcharge": {
"currency": "USD",
"valueDecimal": "12.987654321"
}
},
"cardDetails": {
"status": "initiated",
"failureCode": "call-issuer",
"initiatedOn": "2019-08-24T14:15:22Z",
"confirmedOn": "2019-08-24T14:15:22Z",
"settledOn": "2019-08-24T14:15:22Z",
"failedOn": "2019-08-24T14:15:22Z",
"completedOn": "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
{
"refundID": "string",
"createdOn": "2019-08-24T14:15:22Z",
"updatedOn": "2019-08-24T14:15:22Z",
"status": "created",
"amount": {
"currency": "USD",
"value": 1204
},
"amountDetails": {
"surcharge": {
"currency": "USD",
"valueDecimal": "12.987654321"
}
},
"cardDetails": {
"status": "initiated",
"failureCode": "call-issuer",
"initiatedOn": "2019-08-24T14:15:22Z",
"confirmedOn": "2019-08-24T14:15:22Z",
"settledOn": "2019-08-24T14:15:22Z",
"failedOn": "2019-08-24T14:15:22Z",
"completedOn": "2019-08-24T14:15:22Z"
}
}Response headers
x-request-id
string
required
{
"amount": "string",
"amountDetails": {
"surcharge": "string"
},
"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
Headers
X-Moov-Version
string
v2026.07.00
x-idempotency-key
string
required
x-wait-for
string
rail-response
Path parameters
accountID
string
required
transferID
string
required
Body
Specifies a partial amount to refund.
Before v2026.10, this request body may be omitted. In v2026.10 and later, send an empty object to refund the full amount of the original transfer.
amount
integer<int64>
amountDetails
object
Show child attributes
surcharge
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
Response
amount
object
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.
amountDetails
object
Show child attributes
surcharge
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
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>
createdOn
string<date-time>
refundID
string
status
string<enum>
created,
pending,
completed,
failed
updatedOn
string<date-time>
amount
object
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.
amountDetails
object
Show child attributes
surcharge
object
Show child attributes
currency
string
required
Pattern
valueDecimal
string
required
Pattern
A decimal-formatted numerical string that represents up to 9 decimal place precision.
For example, $12.987654321 is '12.987654321'.
createdOn
string<date-time>
refundID
string