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:

Transaction Verification: The merchant queries the original transaction to confirm it has a "success" status and retrieves the transactionNo required to initiate the refund.
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.

🚧
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 for details.

API Diagram

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:

Verify the original transaction by calling POST /app-data-search/v3/tran-query with the transactionNo or reference. Confirm the transaction status is "success".
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.
Pockyt processes the refund with the underlying payment network. The customer receives the refund to their original payment method.
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

Process Refund

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

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.
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.
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.
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 for the complete reference.