Post Refund Acknowledgment

Endpoint: /api/merchants/{merchantId}/refund-acknowledgment

Introduction

The Post Payment Refund Acknowledgment endpoint allows merchants to send the processing status of a payment refund. This is used to mark an order as REFUNDED within a specific timeframe. The refund may not be processed correctly if the acknowledgment is not received within the required time.

HTTP Method and URL

• Method: POST
• URL: /api/merchants/{merchantId}/refund-acknowledgment

Path Parameters

• {merchantId} (string, required): The unique identifier for the merchant.

Request Headers

• X-API-KEY (string, required): The API key is provided to the merchant for authentication.

Request Body

The request body must be in JSON format and include the following fields:

• processingStatus (string, required): The status of the refund processing. Possible values are:
  • "Success": Indicates that the refund was successfully processed, and the order will be marked as REFUNDED.
  • "Failure": Indicates that the refund processing failed.
• transactionNo (string, required): The unique transaction number associated with the refund. This corresponds to the linkReferenceNumber generated while creating the payment link.

Example Request

To send a refund acknowledgment, your request should look like this:

Request:

POST /api/merchants/12345/refund-acknowledgment HTTP/1.1
Host: api.paylink.sa
Content-Type: application/json
X-API-KEY: your-api-key-here

{
    "processingStatus": "Success",
    "transactionNo": "1234567890ABC"
}

Example Response

Upon successfully processing the acknowledgment, the API will return a JSON response with a status indicating success.

Successful Response:

• Status Code: 200 OK
• Content-Type: application/json

{
    "status": "success"
}

Usage Notes

• Time Sensitivity: This endpoint must be called within a specific time after processing the refund. The refund may not be correctly marked if the acknowledgment is not received in time.
• Idempotency: If the acknowledgment is sent multiple times with the same transactionNo, the subsequent calls should be idempotent and not affect the refund status.

Error Responses

In case of errors, the API will return appropriate HTTP status codes and error messages.

• Status Code: 400 Bad Request

  Response:

  JSON

  {
      "error": "Invalid request format or missing required parameters."
  }
  

• Status Code: 401 Unauthorized

  Response:

  JSON

  {
      "error": "Invalid or missing X-API-KEY."
  }
  

• Status Code: 404 Not Found

  Response:

  JSON

  {
      "error": "The specified merchant or transaction was not found."
  }