---
updatedAt: 2026-06-23T13:54:17.000Z
agentTools:
  projectIndex: https://docs.pockyt.io/llms.txt
---

# Refund

Process full or partial refunds for completed checkout transactions.

# Introduction

Process full or partial refunds for completed checkout transactions. The refund endpoint works across all online and in-store payment types, returning funds to the customer's original payment method.

The refund workflow involves two key functions:

1. **Transaction Verification:** The merchant queries the original transaction to confirm it has a `"success"` status and retrieves the `transactionNo` required to initiate the refund.
2. **Refund Processing:** The merchant calls the refund endpoint with the original transaction details and the desired refund amount. Pockyt communicates with the payment network to credit the customer's account.

<Callout icon="🚧" theme="warn">
  ## Pre-requisites

  **API Credentials**: Obtain `merchantNo`, `storeNo`, and API token values from Pockyt.

  **Successful Original Transaction**: Refunds can only be processed against transactions with a `status` of `"success"`. If the original transaction was not successful, the refund request will be rejected.

  **Authentication**: All API requests must include a valid `verifySign`. See [Signing API Calls](https://docs.pockyt.io/docs/signing-api-calls) for details.
</Callout>

***

## API Diagram

```mermaid
sequenceDiagram
    participant MB as Merchant Backend
    participant PA as Pockyt API
    participant PN as Payment Network

    Note over MB: Step 1: Verify Original Transaction
    MB->>PA: POST /app-data-search/v3/tran-query
    PA-->>MB: Transaction details (status: success)

    Note over MB: Step 2: Initiate Refund
    MB->>PA: POST /app-data-search/v3/refund
    PA-->>MB: refundTransactionNo

    Note over PA: Step 3: Refund Processing
    PA->>PN: Refund request
    PN-->>PA: Refund confirmed

    Note over PA: Step 4: Webhook Notification
    PA-->>MB: Refund result (status, refundTransactionNo)
```

***

## How Refunds Work

The refund flow is straightforward:

1. **Verify the original transaction** by calling `POST /app-data-search/v3/tran-query` with the `transactionNo` or `reference`. Confirm the transaction status is `"success"`.
2. **Call the refund endpoint** at `POST /app-data-search/v3/refund` with the original `transactionNo`, the `refundAmount`, and your `currency`. The API returns a `refundTransactionNo` for tracking.
3. **Pockyt processes the refund** with the underlying payment network. The customer receives the refund to their original payment method.
4. **Receive the webhook notification** on the `ipnUrl` configured in the original transaction. The webhook confirms the final refund status.

If the webhook is delayed or not received, you can query the refund status using the `tran-query` endpoint with the `refundTransactionNo`.

> 📘 **API References:**
>
> * [Query Transaction Status](https://docs.pockyt.io/reference/query-api)
> * [Process Refund](https://docs.pockyt.io/v1.1/reference/refund-api)

***

## Full vs. Partial Refunds

The refund endpoint supports both full and partial refunds:

* **Full refund:** Set `refundAmount` equal to the original transaction amount. The entire payment is returned to the customer.
* **Partial refund:** Set `refundAmount` to any value less than the original transaction amount. Only the specified portion is refunded. Multiple partial refunds can be issued against a single transaction, as long as the total refunded amount does not exceed the original transaction amount.

***

## Key Considerations

1. **Status Requirement:** Only transactions with a `"success"` status can be refunded. Attempting to refund a pending, failed, or already fully refunded transaction will return an error.

2. **Refund Tracking:** Each refund generates its own `refundTransactionNo`, separate from the original `transactionNo`. Use this identifier for tracking refund status, webhook matching, and audit purposes.

3. **Webhook Handling:** Refund webhooks are delivered to the same `ipnUrl` configured in the original payment request. Ensure your webhook handler can distinguish between payment and refund notifications by checking the transaction type in the webhook payload.

4. **Error Handling:** A `ret_code` of `000100` indicates success on all Pockyt API responses. Common refund errors include invalid `transactionNo`, attempting to refund a non-successful transaction, or exceeding the original transaction amount. See [Status & Error Codes](https://docs.pockyt.io/reference/status-error-codes) for the complete reference.