Refund

The refund allows you to credit the customer, for example in case of returned goods or cancellation.

---

Request

To make a refund transaction, send a POST request to https://api.mfstream.io/beyag/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

request object parent_uid required string UID of a parent transaction. reason required string A note why a refund was made. amount integer Amount to refund in minimal currency units, for example 1000 for $10.00 tracking_id string The ID of your transaction or order. The ID of your transaction or order. Can be multiple values separated with semicolons. For example, "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f". If multiple values are sent in the request, the transaction search in the back office system can be performed by any of them. additional_data object 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 the payment method provider.

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",
    "reason":"reason",
    "amount": 50,
    "additional_data": {
        "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    }
  }
}

Response

transaction object uid required string Processed transaction UID parent_uid required string UID of a parent transaction. type required string Transaction type. status required string Status of processed transaction. created_at required string Time when transaction was created in ISO 8601 format. updated_at required string Time when transaction was updated in ISO 8601 format. message string Processing result message. amount integer Amount to refund. currency required string A transaction currency in the ISO-4217 alpha-3 code format. For example, USD. tracking_id string The ID of your transaction or order. test boolean true or false. The transaction will be a test one if it is true language string Language of your checkout page or customer. paid_at string Transaction processing date. method_type required string A payment method type or payment brand name supported by the payment method. receipt_url required string Transaction receipt URL refund object status required string Transaction status. ref_id string A transaction ID of the external system of the payment method provider. message string A message from the system of the payment method provider. rrn string A retrieval reference number. auth_code string An authorization code provided by the payment method provider. gateway_id string Gateway ID in the MF STREAM system. smart_routing_verification object A section of parameters of Smart Routing verification results. status string Smart Routing check status for the transaction. additional_data object Section with additional transaction data. referer string URL of the resource from which the transaction request is made.

Example of the response

{
  "transaction": {
    "uid": "2-310b0da80b",
    "parent_uid": "1-310b0da80b",
    "type": "refund",
    "status": "successful",
    "message": "The operation was successfully processed",
    "created_at": "2014-06-11T12:04:59+03:00",
    "updated_at": "2014-06-11T12:04:59+03:00",
    "amount": 50,
    "currency": "USD",
    "test": false,
    "method_type": ":method_name",
    "receipt_url": "https://backoffice.mfstream.io/customer/transactions/2-310b0da80b/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "refund": {
      "message": "The operation was successfully processed",
      "ref_id": "8889999",
      "status": "successful"
    },
    "smart_routing_verification": {
      "status": "successful"
    },
    "additional_data": {
        "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    }
  }
}

Info

If the response contains a pending status, MF STREAM will send a webhook notification with the final transaction status to the merchant once the refund is finalized.