Refund an Order

API Endpoint: Process a Refund for an Order

Description

This API endpoint allows processing a refund for a specific order associated with a merchant. The refund is triggered by providing the order number and a reason for the refund. It is secured and can only be accessed by users with the PARTNER role.

HTTP Request

Testing Environment:

POST https://restpilot.paylink.sa/rest/partner/v2/merchant/{key}/{value}/refund

Production Environment:

POST https://restapi.paylink.sa/rest/partner/v2/merchant/{key}/{value}/refund

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer `<your_token_here>`

Note: To obtain the Bearer token required for authentication, refer to the Partner Authentication Guide.

Path Parameters

key: The key used to identify the merchant attribute. Possible values:
- cr or freelancer: Search by the merchant's license number.
- mobile: Search by the merchant's phone number.
- email: Search by the merchant's email address.
- accountNo: Search by the merchant's account number.
value: The value associated with the key (e.g., specific license number, phone number, email, or account number).

Request Body

The request body should be in application/json format, containing the order number and the reason for the refund.

Example Request Body

{
    "orderNumber": "1722731077436",
    "refundReason": "Client canceled the order."
}

Example `curl` Request

curl --location 'https://paylinkapi.eu.ngrok.io/rest/partner/v2/merchant/email/[email protected]/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJoYXNzYW4uYXlvdWIuMTk4MEBnbWFpbC5jb20iLCJhdXRoIjoiUk9MRV9NRVJDSEFOVCxST0xFX01FUkNIQU5UX0FDQ09VTlQsUk9MRV9QQVJUTkVSIiwiaXNzIjoiQVBJIiwiZXhwIjoxNzI1MzIzMDYzfQ.dcxeRtoGcfmbNo4H4ons8FBy5onqRoqMxTvnFX5-Ezeup36oH1uh8_MgNKCuoekJw3ut-iKPucp1cC63ufcohw' \
--data '{
    "orderNumber": "1722731077436",
    "refundReason": "Client canceled the order."
}'

Response

Content-Type	Value
JSON	`application/json`

Response Example

The response will confirm the refund details, including the order number, refund amount, currency, and reason.

{
    "id": 237,
    "orderNumber": "1722731077436",
    "amount": 125.0,
    "currency": "SAR",
    "refundReason": "Client canceled the order.",
    "createDatetime": 1722731201000
}

Response Details

Field	Type	Description
`id`	Integer	The unique identifier for the refund transaction.
`orderNumber`	String	The order number for which the refund was processed.
`amount`	Number	The amount was refunded to the client.
`currency`	String	The currency in which the refund was processed, e.g., "SAR".
`refundReason`	String	The reason provided for the refund.
`createDatetime`	Long	The timestamp when the refund was created, represented in milliseconds since epoch.

Security

Code	Meaning
401	Unauthorized: If the provided token is invalid or expired.
403	Forbidden: If the user does not have the required `PARTNER` role.
404	Not Found: If no merchant or order is found for the specified key and value.
400	Bad Request: If the request body is malformed or required fields are missing.