Post Payment Acknowledgment

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

Introduction

The Post Payment Acknowledgment endpoint allows merchants to send the processing status of a payment. This is used to mark an order as PAID within a specific timeframe. If the acknowledgment is not received within the required time, the order will automatically be marked for refund.

HTTP Method and URL

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

Path Parameters

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

Request Headers

• X-API-KEY (string, required): The API key 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 payment processing. Possible values are:
  • "Success": Indicates that the payment was successfully processed, and the order will be marked as PAID.
  • "Failure": Indicates that the payment processing failed.
• transactionNo (string, required): The unique transaction number associated with the payment. This corresponds to the linkReferenceNumber generated during the creation of the payment link.

Example Request

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

Request:

POST /api/merchants/12345/payment-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 amount of time after the payment is processed. If the acknowledgment is not received in time, the order will be automatically marked for refund.
• Idempotency: If the acknowledgment is sent multiple times with the same transactionNo, the subsequent calls should be idempotent and not affect the order 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."
  }