Refunds

A refund is the process of returning funds to a customer after a transaction has been completed. Refunds are typically issued when an order is canceled, a product is returned, or a service is not rendered as expected. In Localpayment, refunds are initiated using the externalId of the original transaction and must always be for the full amount. Partial refunds are not supported.

ℹ️
Processing time
The processing time for a refund varies depending on the payment method and the issuer involved.

How Refunds Work

When a refund is initiated, Localpayment retrieves the original transaction based on the provided externalId. Once the transaction is validated, the following process takes place based on the payment method:

Card Payments: A reversal is performed. The refunded amount is withdrawn from the merchant’s Localpayment account and returned to the cardholder via the card issuer.
Alternative Payment Methods (Cash, Bank Transfer, APMs): The customer will receive a bank transfer. In this case, the merchant is responsible for initiating the payout to the customer’s account.

ℹ️
For alternative payment methods, review the Payouts documentation for details on how to transfer funds and the applicable fees.

Refunds are essential for improving customer experience and maintaining trust. You should only issue a refund when the transaction was successfully completed and the customer is eligible based on your refund policy.

How to Process a Refund

Once a payment has been completed and your customer requests a refund, you can initiate the process directly from your system. Here's how it works:

Your Customer Requests a Refund: A customer contacts your business to request a refund for a previous payment.
You Send the API Request: Your system sends a refund request to the Localpayment API, including the required details such as the externalId of the original transaction.
Localpayment Processes the Request: Once received, Localpayment will process the refund request. If eligible, the refund will be created and initiated.
Your Customer Receives the Funds: The refunded amount is returned to the customer's bank account or original payment method. Processing time varies depending on the issuer or payment method.

Availability

Refunds are available for the following payment methods:

Card: Refunds are processed as reversals to the original card. The funds are returned directly to the cardholder's account. Processing times depend on the issuing bank.
Cash: Refunds for cash payments are issued via bank transfer to the customer. Make sure to collect the customer's bank account details before initiating the refund.
Bank Transfer: Refunds for bank transfer payments are also processed via bank transfer to the original payer. Bank account information is required.

Requirements and Limitations

Before initiating a refund, ensure the following conditions are met for Localpayment to process the request successfully:

The original transaction must have been successfully authorized.
The original transaction must not be under dispute.
The refund must be requested within the valid time frame allowed for the specific payment method.
The refund must be for the full transaction amount. Partial refunds are not supported.
The recipient’s name must match the name used in the original transaction.

Failure to meet any of these conditions may result in a failed refund request.

Before Requesting a Refund

Before submitting a refund request, make sure you've completed the following step:

Generate an Access Token (Required): You'll need a valid access token to authenticate your API requests. Refer to the Generate an Access Token documentation for instructions.

Refund a Payment

You can issue a refund for a previously completed payment using the transaction identifier externalId as a path parameter in your request. To initiate a refund, send a PATCH request to the Refund a Payin endpoint.

Request Example

Below is an example using curl:

curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/{externalId}/refund' \
--header 'x-client-code: 0000' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '{
}'

Parameters

externalId: A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. de14bcf2-15ee-22e3-ab59-99c3fcba31e8).

See all available parameters in the request.

Successful response example

If the refund request is successfully submitted, the API will return a status code of 902, indicating that the refund is in progress.

{
    "externalId": "e36ef929-c2d4-fcf0-b30c-99dc51798f4b",
    "internalId": "c09095fb-6a0e-47af-9f43-3d9452b0f290",
    "status": {
        "code": "902",
        "description": "REFUNDED",
        "detail": "The payin was refunded"
    }
}

Key Fields in the Response

externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining refund status.
internalId: A unique identifier for the transaction in Localpayment’s system.
status: Object with information about the status of the refund.
status.code: The status code (e.g., 902 for REFUNDED).

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.

Localpayment also sends webhooks to your application to notify you about changes in the refund status. For more information, refer to the Webhooks documentation.

Refund a Cash Payment

To refund a cash payment, you must provide the customer's bank account details along with the original externalId. Localpayment will use this information to process a bank transfer to the customer's account.

Request Example

Below is an example using curl:

curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/{externalId}/refund' \
--header 'x-client-code: 0000' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '{
    "externalId": "e36ef929-c2d4-fcf0-b30c-99dc51798f4b",
    "comment": "Refund Cash",
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RUC",
            "id": "1791234561009
        },
        "bank": {
            "name": "Bank name",
            "code": "191",
            "account": {
                "type": "S",
                "number": "1910119655111901676653"
            }
        }
    }
}'

Parameters

externalId: A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. de14bcf2-15ee-22e3-ab59-99c3fcba31e8).
beneficiary: Object containing recipient information for the refund.
beneficiary.type: Type of beneficiary (e.g., INDIVIDUAL).
beneficiary.name: First name of the beneficiary.
beneficiary.lastname: Last name of the beneficiary.
beneficiary.document: Object with document type and ID.
beneficiary.bank: Object with bank details.
bank.name: Name of the bank.
bank.code: Bank code.
bank.account: Object with bank account type and number.

See all available parameters in the request.

Successful response example

{
    "externalId": "e36ef929-c2d4-fcf0-b30c-99dc51798f4b",
    "internalId": "c09095fb-6a0e-47af-9f43-3d9452b0f290",
    "status": {
        "code": "902",
        "description": "REFUNDED",
        "detail": "The payin was refunded"
    }
}

Key Fields in the Response

externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining refund status.
internalId: A unique identifier for the transaction in Localpayment’s system.
status: Object with information about the status of the refund.
status.code: The status code (e.g., 903 for REFUNDED).

For more details about possible status codes, refer to the Transaction Status documentation.

Localpayment will also send a webhook to your application once the refund status is updated. For implementation details, see the Webhooks guide.

ℹ️Processing time

How Refunds Work

ℹ️

How to Process a Refund

Availability

Requirements and Limitations

Before Requesting a Refund

Refund a Payment

Refund a Cash Payment

ℹ️
Processing time