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:

  1. Full Refund: Returns the entire transaction amount to the customer
  2. Partial Refund: Returns only a portion of the transaction amount

API Endpoint

Request

DELETE /transaction/{id}

Path Parameters

ParameterTypeRequiredDescription
idintegerYesTransaction ID to be refunded

Form Parameters

ParameterTypeRequiredDescription
reasonstringNoReason for the refund (see available options below)
messagestringNoAdditional explanation or details about the refund
amountnumber (float)NoAmount 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 CodeDescription
fraud-confirmTransaction identified as fraudulent
highly-suspiciousTransaction appears suspicious or high-risk
duplicated-transactionCustomer was charged more than once
customer-demandCustomer requested a refund
test-transactionTransaction was for testing purposes
card-expiredTransaction made with an expired card

Response Codes

CodeDescription
200Refund successfully processed
400Invalid request parameters
401Unauthorized request
404Transaction not found
500Server 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:

  1. Navigate to the Transaction: Find the transaction you want to refund in your transactions list
  2. Initiate the Refund: Click the "Refund" button in the transaction details view
  3. 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)
  4. 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
  5. 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

  1. Include detailed reasons: Always provide a clear reason and message for refunds to maintain accurate records
  2. Process refunds promptly: This improves customer satisfaction and reduces the likelihood of chargebacks
  3. Partial refunds: When possible, use partial refunds for situations where only part of an order is returned
  4. Monitor refund activity: Regularly review refunds to identify potential fraud or customer service issues

Troubleshooting

Error MessagePossible CauseSolution
"This transaction can not be refunded"Transaction is not in a refundable stateVerify transaction status
"This transaction is already refunded"Transaction was previously refundedCheck transaction history
"amount can not exceed remaining amount"Refund amount exceeds available refundable amountReduce refund amount

For additional assistance with refunds, please contact xMoney support.