Refunds
This guide explains how to process refunds for transactions made with xMoney. Our API provides flexible options for full and partial refunds of successful transactions.
Overview
A refund is the process of returning funds to a customer after a successful transaction. xMoney supports refunding transactions made through various payment methods including credit cards and alternative payment methods like digital wallets.
When to Use Refunds
Common scenarios for issuing refunds:
- Customer returns a product
- Service cancellation
- Duplicate transactions
- Resolving customer disputes
- Testing transactions
Refund Types
xMoney supports two primary types of refunds:
- Full Refund: Returns the entire transaction amount to the customer
- Partial Refund: Returns only a portion of the transaction amount
API Endpoint
Request
DELETE /transaction/{id}
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | integer | Yes | Transaction ID to be refunded |
Form Parameters
Parameter | Type | Required | Description |
---|---|---|---|
reason | string | No | Reason for the refund (see available options below) |
message | string | No | Additional explanation or details about the refund |
amount | number (float) | No | Amount to be refunded. If not provided, the entire transaction amount will be refunded |
Available Refund Reasons
The following reason codes can be provided in the reason
parameter:
Reason Code | Description |
---|---|
fraud-confirm | Transaction identified as fraudulent |
highly-suspicious | Transaction appears suspicious or high-risk |
duplicated-transaction | Customer was charged more than once |
customer-demand | Customer requested a refund |
test-transaction | Transaction was for testing purposes |
card-expired | Transaction made with an expired card |
Response Codes
Code | Description |
---|---|
200 | Refund successfully processed |
400 | Invalid request parameters |
401 | Unauthorized request |
404 | Transaction not found |
500 | Server error |
Refund Eligibility
Not all transactions can be refunded. The API validates refund requests and will reject them in the following cases:
- Transaction is not a deposit (payment) transaction
- Transaction is in one of these statuses:
start
,uncertain
,complete-failed
- Transaction is already refunded, voided, or canceled
- Transaction is pending charge-back
- Amount to refund exceeds the original transaction amount
- Amount to refund exceeds the remaining amount (for partial refunds)
Example Requests
Full Refund
curl -X DELETE \
https://api.xmoney.com/transaction/12345 \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'reason=customer-demand&message=Customer%20returned%20the%20product'
Partial Refund
curl -X DELETE \
https://api.xmoney.com/transaction/12345 \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'reason=customer-demand&message=Partial%20refund%20for%20damaged%20item&amount=25.50'
Example Response
{
"code": 200,
"message": "Transaction successfully refunded",
"data": {
"transactionId": 12345,
"status": "refund-ok",
"refundedAmount": 25.50
}
}
Transaction Status Changes
When a refund is processed successfully, the transaction status changes to refund-ok
. You can check the status of a transaction using the Transaction API endpoints.
Special Considerations
Payment Method Limitations
Different payment methods may have different limitations for refunds. Card payments generally support both full and partial refunds.
Refund Fees
Refunds may incur fees depending on your merchant agreement with xMoney. These fees are configured at the site level and may vary by payment method. Refer to your merchant dashboard or contact support for information about refund fees.
Time Limits
Most payment processors have time limits within which refunds can be processed. Typically, refunds can be processed within 60-180 days of the original transaction, depending on the payment method.
Refund Webhooks
You can configure your system to receive webhook notifications when refunds are processed. This allows your system to automatically update orders or customer records.
To configure webhooks, navigate to the Webhooks section in your merchant dashboard.
Refunding Through the Merchant Interface
In addition to API-based refunds, merchants can also process refunds directly through the xMoney Merchant Dashboard:
- Navigate to the Transaction: Find the transaction you want to refund in your transactions list
- Initiate the Refund: Click the "Refund" button in the transaction details view
- Choose Refund Type: Select between:
- Total Refund: Refunds the entire transaction amount
- Partial Refund: Allows you to specify a custom amount (up to the original transaction amount)
- Provide Required Information:
- Select a reason for the refund from the dropdown menu (required)
- Add an optional comment (up to 255 characters)
- For partial refunds, enter the amount to refund
- Complete the Refund: Click the "Ok" button to process the refund
The refunded transaction will immediately show the updated status and the customer will receive a notification about the processed refund.
Best Practices
- Include detailed reasons: Always provide a clear reason and message for refunds to maintain accurate records
- Process refunds promptly: This improves customer satisfaction and reduces the likelihood of chargebacks
- Partial refunds: When possible, use partial refunds for situations where only part of an order is returned
- Monitor refund activity: Regularly review refunds to identify potential fraud or customer service issues
Troubleshooting
Error Message | Possible Cause | Solution |
---|---|---|
"This transaction can not be refunded" | Transaction is not in a refundable state | Verify transaction status |
"This transaction is already refunded" | Transaction was previously refunded | Check transaction history |
"amount can not exceed remaining amount" | Refund amount exceeds available refundable amount | Reduce refund amount |
For additional assistance with refunds, please contact xMoney support.