Refund Payments

Introduction

The refund process involves several key steps to ensure proper transaction handling:

1. The POS system receives a refund request and verifies the original transaction's status through the Transaction Query API
2. The system confirms the refund request
3. The system initiates the refund by calling the Refund Transaction API with the transaction number or reference ID, which generates a unique refund transaction number
4. Pockyt communicates the refund details to the digital wallet network, which processes the request and credits the refunded amount to the customer's account

🚧

## Prerequisites

Transaction status: You must have a transaction with the status parameter set to "success"

Key Implementation Notes

1. Parameter Flow:

   • transactionNo: Received during the transaction query step and required for refund initiation
   • refundTransactionNo: Generated upon successful refund initiation, used for tracking and auditing
   • reference: The unique ID associated with the original transaction, used in both query and refund steps

2. API Endpoints:

   • Transaction Query: Verifies the status of the original transaction before processing a refund
   • Refund Transaction: Initiates the refund request using transactionNo or reference

3. Webhook Management:

   • IPN URL: Configure an IPN (Instant Payment Notification) URL to receive updates on refund status
   • Ensure validation of transactionNo and refund status in webhook notifications

4. Validation:

   • All API requests require a valid verifySign for authentication
   • A successful operation is indicated by ret_code = 000100

5. Common Error Scenarios:

   • Invalid or missing transactionNo or reference
   • Incorrect or mismatched refund parameters
   • Errors in verifying the verifySign
   • Failure to receive webhook notifications due to IPN misconfiguration

API Workflow

📘

API References for Endpoints in this Workflow:

• Step 2: Query Transaction Status
• Step 3: Process Refund

Step-by-Step Refund Workflow Description

Step 1: Refund Request

• Action: The Merchant Backend processes a refund request submitted by the customer for a previous payment

🚧

You need a transactionNo and a successful status

Step 2: Query Transaction Status

• Action: The Merchant Backend queries the transaction status to monitor refund progress and handle necessary actions. Refunds are only possible for successful transactions. If the transaction was not successful, a refund cannot be processed
• Endpoint: POST /v3/tran-query
• Key Parameters:
  • Request Body: Includes transactionNo to retrieve transaction details
  • Response: Returns transaction details, including status, amount, currency, and refund progress

Step 3: Process Refund

• Action: The Merchant Backend allows the customer to request a refund and initiates the refund process
• Endpoint: POST app-data-search/v3/refund
• Key Parameters:
  • Request Body: Includes transactionNo of the original payment, refundAmount, currency, and optional parameters like the reason for the refund
  • Response: Returns a refundTransactionNo and success status confirming that the refund has been processed

Step 4: Handle Webhook Notification

• Action: After the refund is initiated, Pockyt sends a webhook to the merchant's configured ipnUrl, containing the refund status, transaction number, and other relevant details
• Purpose: To asynchronously confirm the outcome of the refund, enabling the merchant to update internal systems, notify the customer, or trigger any post-refund automation without polling the API
• See Example Webhook Notification Body Here

Step 5: Generate Receipt

• Action: After a successful refund request, the Merchant Backend sends a receipt or notification to the customer
• Process:
  • Uses data from the API response to generate a receipt
  • Sends the receipt via email or another preferred method
• Response: Confirms that the customer has been notified of the refund