Refund a Virtual Account Payment

Localpayment enables you to process refunds for virtual account payments, allowing you to return funds to customers through both API integration and the Dashboard interface. This guide covers the complete refund workflow for virtual account transactions using the direct refund method.

Before You Begin

Ensure you have:

Additional Refund Requirements:

• Sufficient balance in your Localpayment account to cover the refund amount.
• User role with refund permissions (see User Roles documentation).
• The original transaction must be in Completed status.
• The externalId of the original payment transaction.

Implementation Guide

Localpayment provides two methods for processing virtual account refunds: API integration for automated processing and Dashboard for manual operations.

Direct Refunds for Virtual Accounts

All virtual account refunds are processed as Direct Refunds, meaning you only need the original transaction's externalId. The system automatically routes funds back to the original payer's account without requiring additional beneficiary information.

⚠️

Important: Only full refunds are permitted for virtual account transactions. Partial refunds are not supported.

Country-Specific Requirements

Virtual account refunds have specific requirements and limitations depending on the country and banking method. Below are the key country-specific considerations:

Step 1: Process Refund via API

To refund a virtual account payment through API, send a PATCH request to the Refund endpoint.

Key Request Parameters

The request requires several key parameters:

Example Request

Below is an example using curl:

curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/payin/{{externalId}}/refund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "comment": "Refund API Virtual Account"
  }'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successfully processed refund returns confirmation details:

{
  "externalId": "1c364061-1f3d-4b94-c270-bf915c22e8f5",
  "internalId": "8a9abd31-31e0-429a-32a6-cca8b9e1e536",
  "status": {
    "code": "902",
    "description": "REFUNDED",
    "detail": "The payin was refunded"
  }
}

Key Response Fields

Error Response

When a refund request fails, you'll receive error information:

{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Invalid operation"
  }
}

Common Error Scenarios

Dashboard Refunds

Virtual account refunds can also be processed through the Localpayment Dashboard interface. This method provides a visual workflow for managing refunds and is particularly useful for:

• Occasional refunds that don't require API automation.
• Administrative oversight where approval workflows are needed.
• Quick refund processing without development resources.

For detailed instructions on processing refunds through the Dashboard, including step-by-step guidance and interface walkthroughs, please refer to the Dashboard Refunds Guide .

⚠️

Approval Required: All refunds initiated through the Localpayment Dashboard require approval through the designated authorization workflow. Ensure you have the necessary user permissions before attempting Dashboard refunds.

Step 3: Track Refund Status

After initiating a refund, monitor its progress through these methods:

Common Refund Status Codes

📝

Note: For complete status code reference, see the Transaction Status documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

1. Successful Refund: Process refund with valid externalId and sufficient funds.
2. Insufficient Funds: Attempt refund with inadequate account balance.
3. Invalid Transaction: Try to refund non-existent externalId.
4. Duplicate Refund: Attempt to refund already refunded transaction.
5. Permission Validation: Test with users having different permission levels.

Next Steps