Refund

The refund allows you to credit the customer, for example in case of returned goods or cancellation. To post a refund request, a valid transaction UID from a former Capture or Payment transaction is required. It is only possible to credit an amount less than or equal to the initial transaction using the same currency as with the original transaction. This feature also allows you to issue multiple partial refunds against an original transaction.

Request

To make a refund transaction, send a POST to https://gateway.mfstream.io/transactions/refunds with the parameters from the tables below.

Header parameters


Content-Type required	`application/json`
Accept required	`application/json`
X-API-Version	Possible values: `2`, `3`. By default, `3`. More details here
RequestID	Idempotency key. More details here.

Body parameters

object

parent_uid

required

string
A UID of the payment or capture transaction.

amount

required

integer
An amount to refund in minimal currency units, for example 1000 for $10.00.

reason

required

string (255)
A note why a refund was made.

tracking_id

string (255)
Transaction ID in the merchant's system. Please, use a unique value. If tracking_id is not provided, the response returns the tracking_id of the corresponding payment/capture transaction, provided that it was included in the payment/capture request.

object
A section with additional transaction data.

referer

string
URL of the resource from which the transaction request is made. Contact the Tech Support Team to check if this parameter is required by your acquirer.

Warning

If the integration supports multiple partial refunds, each refund request is treated as a separate transaction.

If a 5xx response is received or a network error occurs after sending the request, it is recommended to check the transaction status by tracking_id. If no transaction is found, resend the original request using the same idempotency key.

Resending the request without an idempotency key or with a new idempotency key may result in an additional partial refund.

Example of the request

{
  "request":{
    "parent_uid":"1-310b0da80b",
    "amount":50,
    "reason":"Client request",
    "tracking_id": "123a",
    "additional_data": {
      "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    }
  }
}

Response

object

uid

required

string
A UID of the processed transaction.

status

required

string
A status of the processed transaction.

message

required

string
A processing result message corresponding to the code. For certain integration options, this parameter contains the processing result message provided by the acquirer.

amount

bigInteger

currency

string
A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.

parent_uid

string
UID of a parent transaction.

type

required

string
A transaction type.

receipt_url

required

string
A transaction receipt URL.

created_at

string
A time when the transaction was created at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ.

updated_at

string
A time when the transaction was last updated at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ.

paid_at

string
A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the transaction is incomplete.

settled_at

string
A time when the acquiring bank settled the transaction amount to the merchant's current account in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the parameter is not applicable to the transaction.

psp_settled_at

string
Date and time of the transaction settlement between MF STREAM and the merchant in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the parameter is not applicable to the transaction.

object
A section of parameters of Smart Routing verification results.

status

string
Smart Routing check status for the transaction.

object
A section of detailed information about the transaction.

referer

string
URL of the resource from which the transaction request is made.

code

required

string
Transaction processing code .

friendly_message

required

string
A customer-friendly message corresponding to the code. For certain integration options, this parameter contains the processing result message provided by the acquirer.

object

message	string A processing result message provided by the acquirer.
ref_id	string A transaction reference ID provided by the acquirer.
rrn	string A retrieval reference number. A transaction ID issued by the card processing service.
auth_code	string An authorization code provided by the acquirer.
gateway_id	string Gateway ID in the MF STREAM system.
status	string A status of the processed transaction in the acquiring bank.

Example of the response

{
  "transaction": {
    "uid": "1cbf77cb-ed58-40f2-8bb4-0be10f12fda8",
    "status": "successful",
    "amount": 492,
    "currency": "EUR",
    "reason": "Client request",
    "type": "refund",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-04-02T14:01:09.302Z",
    "updated_at": "2024-04-02T14:01:12.460Z",
    "paid_at": "2024-04-02T14:01:12.397Z",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "parent_uid": "5e14b86f-1bb9-40ad-b42a-b925176aec63",
    "receipt_url": "https://backoffice.mfstream.io/customer/transactions/1cbf77cb-ed58-40f2-8bb4-0be10f12fda8/30c0d33fdd4ad02356c73067aedcaddc228bcaca8be500ecf84edbd44ffb6b39?language=en",
    "status_code": null,
    "mute_notifications": null,
    "id": "1cbf77cb-ed58-40f2-8bb4-0be10f12fda8",
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
      "status": "successful"
    },
    "refund": {
      "message": "Refund was approved",
      "ref_id": "8889999",
      "rrn": null,
      "auth_code": null,
      "bank_code": "05",
      "gateway_id": 3483,
      "status": "successful"
    },
    "additional_data": {
        "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    }
  }
}