Refunds

This page describes the complete lifecycle of a Refund: its status flow, what each status means, the notifications you receive, the structure of the callback payload, and how to query updates.

Status Map

The following diagram covers the possible status flow for Refunds. For every status change a webhook notification is sent to the merchant's API.

Status Description

Refund Status	Trigger	Changes in linked transaction
REQUESTED	Merchant requests a refund successfully	none
PROCESSING	We request a refund successfully to the PSP	none
COMPLETED	We get a response from the PSP that the refund was completed	Status Change: REFUNDED, PARTIALLY_REFUNDEDUpdate Refunded Amount
FAILED	We tried to process the refund but an error occurred and it will not proceed	none

Notification

A webhook notification is sent to your notification_url for every Refund status change. The notification is a lightweight signal — after receiving it, query the Update Endpoint for the current refund status and details.

Scenario	When it happens	Effect on the linked payment
Refund requested	You successfully request a refund (REQUESTED).	None yet.
Refund processing	We forward the refund request to the PSP (PROCESSING).	None yet.
Refund completed	The PSP confirms the refund (COMPLETED).	The linked payment moves to REFUNDED or PARTIALLY_REFUNDED and its refunded amount is updated.
Refund failed	The refund could not be processed (FAILED).	None.

The callback for a refund references the refund record and the original payment so you can reconcile it:

Callback body

{
  "refund_id": 123,
  "payment_token": "PAYMENT_ID"
}

Update Endpoint

Retrieve the current status and details of a refund on demand. Identify the refund by its refund_id.

GET https://api-sandbox.letpay.io/refund/REFUND_ID

Possible statuses: REQUESTED, PROCESSING, COMPLETED, FAILED.

AUTHORIZATION	API Key
Key	X-Auth-Token
Value	MY_ACCESS_TOKEN

200 - Success

Example Request

200 - Success

    curl --location 'https://api-sandbox.letpay.io/refund/REFUND_ID' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

    {
      "refund_id": 1,
      "payment_token": "fa5ec5cc-d4d5-439e-8fb5-0368d409dc9b",
      "created_at": "2019-06-25",
      "refund_status": "PROCESSING",
      "refresh_token": "MY_ACCESS_TOKEN"
    }

404 - Not Found

Example Request

404 - Not Found

    curl --location 'https://api-sandbox.letpay.io/refund/INVALID_REFUND_ID' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

    {
      "timestamp": "2024-05-14T18:17:01.793+00:00",
      "status": 404,
      "error": "Not Found",
      "path": "/refund/INVALID_REFUND_ID",
      "errors": [
        {
          "code": "00.01.0068",
          "description": "We couldn't find this refund ID, please check again."
        }
      ],
      "refresh_token": "MY_ACCESS_TOKEN"
    }

401 - Unauthorized

Example Request

401 - Unauthorized

    curl --location 'https://api-sandbox.letpay.io/refund/REFUND_ID' \
    --header 'X-Auth-Token: INVALID_ACCESS_TOKEN'

Example Response

Header

  Content-Type: application/json

Body

    {
      "timestamp": "2024-05-14T18:21:23.021+00:00",
      "status": 401,
      "error": "Unauthorized",
      "message": "Access Denied",
      "path": "/refund/REFUND_ID"
    }

You can also list all refunds for a payment via Get Refund Requests for a Payment.