Skip to main content

Refund Transaction

Overview​

The Refund API allows you to return full ammount or pratial amount of funds to a customer. This functionality supports the full settlement lifecycle by enabling refunds for transactions that have been successfully settled (status CAPTURED) or processed immediately (status SALE).

Prerequisites​

To initiate a refund, you need the transactionId of a transaction that has already been settled.

  • Allowed Statuses: CAPTURED or SALE.

Initiate Refund​

To create a refund, send a POST request to the transactionRefunds endpoint.

Parameters​

  • amount (number, optional): The amount to be refunded.
  • Validation: Must be less than or equal to the remaining captured amount of the transaction.
  • Default: If omitted, the system attempts to refund the full remaining balance.

Example Request:

curl --location --request POST 'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/transactions/{{transactionId}}/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <keyValue>' \
--data '{
    "amount": 10.50
}'

Response Handling​

After submitting the request, the API will return the updated transaction object or an error code based on validation rules.

Success​

If successful (200 OK), the transaction status will update to REFUNDED or PARTIALLY_REFUNDED.

Errors​

  • 422 Unprocessable Content: Returned if the requested amount exceeds the captured amount.
  • 400 Bad Request: Returned if you attempt to refund a transaction that is not in a settled state (e.g., AUTHORIZED or VOIDED).

Transaction Lifecycle​

The following state diagram illustrates where the Refund action fits within the payment lifecycle, specifically after the Capture phase.