Refund a Cash Payment

Localpayment enables you to process refunds for cash payments through both API integration and the Dashboard interface. This guide covers the complete refund workflow for cash transactions, which requires the data-required refunds flow to provide beneficiary and bank account details for processing.

Before You Begin

Ensure you have:

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

Country Requirements

Understanding of country-specific requirements and local regulations.

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.
Complete beneficiary information for data-required refunds.

Implementation Guide

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

API Refund Processing

Programmatically process refunds through REST API for automated workflows and integration with your systems.

Dashboard Refund Processing

Manually process refunds through the Localpayment Dashboard with a user-friendly interface. Note: All Dashboard refunds require approval.

Data-Required Refunds for Cash Payments

Cash refunds are processed as Data-Required Refunds, meaning you need both the original transaction's externalId and complete beneficiary information. Unlike card payments where funds can be returned to the original payment method, cash payments require explicit bank account details since there's no digital payment method to reverse.

⚠️
Important: Only full refunds are permitted for cash transactions. Partial refunds are not supported. The beneficiary and destination account information must be the same as the data from which the payment originates.

Step 1: Process Refund via API

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

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
`externalId`	The original transaction's externalId	✅
`comment`	Optional note about the refund reason	❌
`beneficiary`	Recipient details including bank information	✅
`beneficiary.type`	Beneficiary type (`INDIVIDUAL` or `COMPANY`)	✅
`beneficiary.name`	First name of the beneficiary	✅
`beneficiary.lastName`	Last name of the beneficiary	✅
`beneficiary.document.type`	Document type of the beneficiary	✅
`beneficiary.document.id`	Document ID of the beneficiary	✅
`beneficiary.bank.name`	Name of the beneficiary's bank	✅
`beneficiary.bank.code`	Bank code	✅
`beneficiary.bank.account.type`	Account type	✅
`beneficiary.bank.account.number`	Account number of the beneficiary	✅

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 cash",
    "beneficiary": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "RFC",
        "id": "EXTF900101NI1"
      },
      "bank": {
        "name": "BBVA MEXICO",
        "code": "012",
        "account": {
          "type": "S",
          "number": "322000180511735471"
        }
      }
    }
  }'

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

Parameter	Description	Use Case
`externalId`	Your reference for the original transaction.	Reconciliation and tracking.
`internalId`	Localpayment's unique refund identifier.	Support and audit purposes.
`status.code`	Refund status code (`902` for successful refund).	Status monitoring.

Error Response

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

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

Common Error Scenarios

Error	Description	Solution
Insufficient Funds	Your Localpayment account balance is insufficient to cover the refund amount	Add funds to your Localpayment account or wait for pending settlements to clear
Transaction Not Found	The provided `externalId` does not exist or is invalid	Verify the externalId is correct and the transaction exists in your transaction history
Invalid Status	The original transaction is not in a refundable state (must be `Completed`)	Check the transaction status and ensure it has been successfully processed before attempting refund
Permission Denied	Your user role lacks necessary refund permissions	Contact your account administrator to grant appropriate refund permissions for your role
Duplicate Refund	Attempting to refund an already refunded transaction	Verify the transaction hasn't been refunded previously by checking the refund status
Invalid Amount	Attempting a partial refund when only full refunds are allowed	Process refund for the full transaction amount only

Dashboard Refunds

Cash 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:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Refund Status Codes

Code	Status	Description
`400`	`ERROR`	Refund request failed due to validation errors or invalid parameters.
`902`	`REFUNDED`	The payin was successfully refunded.

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

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

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

Next Steps

View transaction status

Check the current status of transactions and refunds using the Transaction Status API.

Configure webhooks

Set up webhooks to receive real-time notifications for refund status changes.

Review user roles

Manage user permissions and roles for refund processing capabilities.