Initiating a Refund Transaction

This documentation explains how to initiate a refund transaction using the Facilero API. By making a POST request, you can process a refund for a previously completed transaction. Once the request is processed, a callback (webhook) containing the refund details will be sent to your specified URL.

API Endpoint

Live

POST https://live.facilero.com/v1/refunds/card

Sandbox

POST https://sandbox.facilero.com/v1/refunds/card

Request Headers:

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>
Replace <AUTH_TOKEN> with the access token obtained from the Authorization Service.

Request Body:

The request should be in JSON format and include the following parameters:

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the refund request.
`mid`	String	Yes	Merchant ID associated with the refund.
`transactionId`	String	Yes	The ID of the transaction to be refunded.
`amount`	String	Yes	The amount to refund, following currency precision rules. Amount in major currency units (not minor units/cents), represented as a string. For example, for USD, "2000" means $2,000.00 and "20" means $20.00. Do not send "2000" to represent $20.00.
`reason`	String	Yes	A description of the reason for the refund.
`callbackUrl`	String	No	URL to receive the status update of the refund.
`metadata`	Map<String, String>	No	Additional key-value metadata for custom use.

Example Request

curl -X POST "https://live.facilero.com/v1/refunds/card" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -d '{
    "requestId": "req12345",
    "mid": "uds939fbskq23pd0vjop1"
    "transactionId": "txn67890",
    "amount": "50.00",
    "reason": "Customer returned the product",
    "callbackUrl": "https://yourserver.com/callback",
    "metadata": {
      "customKey1": "customValue1",
      "customKey2": "customValue2"
    }
  }'

Response Details

The refund endpoint provides a structured response indicating the success or failure of the request.

Response Body

Field	Type	Required	Description
`refundId`	String	Yes	Unique identifier for the refund transaction.
`transactionStatus`	String	Yes	Current status of the transaction (e.g., NEW, PENDING, FAILED, etc.).
`declineCode`	Int	No	Decline code if the transaction fails.

Example Successful Response

HTTP Status: 200 OK
Response Body:

{
  "refundId": "ref12345",
  "transactionStatus": "PENDING",
  "declineCode": null
}

Example Failed Response

HTTP Status: 200 OK
Response Body:

{
  "refundId": "ref12345",
  "transactionStatus": "FAILED",
  "declineCode": 101
}

Callback: Merchant Refund DTO

Once the refund is processed, a webhook will be sent to the callbackUrl specified in the request. The callback provides details about the refund and its status.

Refund Callback DTO

The callback object includes the following fields:

Field	Type	Required	Description
`transactionId`	String	Yes	The ID of the original transaction being refunded.
`refundId`	String	Yes	Unique identifier for the refund.
`requestId`	String	Yes	The original request ID provided when initiating the refund.
`mid`	String	Yes	Merchant ID associated with the refund.
`transactionStatus`	Enum	Yes	The status of the refund transaction (e.g., PENDING, SUCCEED, FAILED).
`declineCode`	Integer	No	Code indicating the reason for failure (if applicable).
`totalAmount`	Double	Yes	The total amount refunded.
`callbackUrl`	String	No	The URL where the callback was sent.
`createdAt`	String	Yes	Timestamp when the refund was processed.

Example Callback Object

{
  "transactionId": "txn67890",
  "refundId": "ref12345",
  "requestId": "req12345",
  "mid": "merchant001",
  "transactionStatus": "SUCCEED",
  "declineCode": null,
  "totalAmount": 50.0,
  "callbackUrl": "https://yourserver.com/callback",
  "createdAt": "2024-01-01T12:00:00Z"
}

ℹ️
Callback (CB) Behavior for FX Refunds
Refund callbacks for FX transactions use the same structure as regular refund callbacks.
The amount reported in the callback always reflects the processed currency amount, not the order currency.
Example:

Original transaction: 20.00 EUR

FX applied at authorization: customer charged 25.00 USD

Refund requested for: 20.00 EUR

The system initiates a refund of 25.00 USD, and the callback payload will contain:
{
  "transactionId": "txn67890",
  "refundId": "ref12345",
  "requestId": "req12345",
  "mid": "merchant001",
  "transactionStatus": "SUCCEED",
  "declineCode": null,
  "totalAmount": 25.0,
  "callbackUrl": "https://yourserver.com/callback",
  "createdAt": "2024-01-01T12:00:00Z"
}
The callback will never return the order currency amount (20.00 EUR) for FX refunds.