> For the complete documentation index, see [llms.txt](https://docs.payengine.co/payengine-api-v2.5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payengine.co/payengine-api-v2.5/transactions/refund.md).

# Refund

Refund API is designed to issue refunds on an existing transaction. This API can't be used to issue standalone refunds or credits.

<mark style="color:green;">`POST`</mark> `https://<Platform-host>/api/payment/refund`

#### Request Body

<table><thead><tr><th width="282">Name</th><th width="85">Type</th><th>Description</th></tr></thead><tbody><tr><td>amount<mark style="color:red;">*</mark></td><td>string</td><td>Amount to be refunded. Should be less or equal to available transaction amount</td></tr><tr><td>id<mark style="color:red;">*</mark></td><td>string</td><td>Transaction ID</td></tr><tr><td>reason<mark style="color:red;">*</mark></td><td>string</td><td>Reason for the refund</td></tr><tr><td>metadata</td><td>object</td><td>Add any additional metadata by passing a json object</td></tr><tr><td>internal_transaction_id</td><td>string</td><td>An internal ID from integrating system. Will be returned in the response and associated refunds if provided.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Refund Response Field Definitions" %}

<table><thead><tr><th width="211">Field Name</th><th width="103">Type</th><th width="307.3583984375">Description</th><th>Required?</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Platform payment ID for the sale request</td><td>Required</td></tr><tr><td>transaction_id</td><td>string</td><td>Unique transaction ID</td><td>Required</td></tr><tr><td>merchant_id</td><td>string</td><td>Merchant ID</td><td>Required</td></tr><tr><td>gateway_id</td><td>string</td><td>ID of the gateway through which the transaction is processed</td><td>Optional</td></tr><tr><td>reason</td><td>string</td><td>Reason provided in the request</td><td>Required</td></tr><tr><td>token</td><td>string</td><td>Card token used in the original transaction</td><td>Required</td></tr><tr><td>internal_transaction_id</td><td>string</td><td>An internal ID from integrating system. Will be returned in the response and associated refunds if provided. If not provided in the request, the internal_transaction_id from the original sale transaction will be returned</td><td>Optional</td></tr><tr><td>order_number</td><td>string</td><td>Order number provided in the original transaction</td><td>Optional</td></tr><tr><td>return_response</td><td>object</td><td>Refer to <a href="/pages/K8BP4U8UG9RUhkIFpjn6">Credit Card Sale</a> (SaleResponse) or <a href="/pages/uGaxCbbNUcutaUhW5aVS">ACH Sale</a> (AchResponse) object definitions</td><td>Required</td></tr><tr><td>metadata</td><td>object</td><td>Return all the metadata sent in the request</td><td>Optional</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### Sample Request / Response

{% tabs %}
{% tab title="Request Body" %}
**Example Request**

```json
{
    "id": "9a0df7ef-b77f-4525-97e1-f41a98ad7f75",
    "amount": 10,
    "reason": "Discount issued",
    "internal_transaction_id": "121212",
    "description": "Refund for the services",
    "metadata": {
        "customer_id": "123",
        "email" : "test@test.com"
    }
}

```

{% endtab %}

{% tab title="Response Body" %}
**Example Response**

```json
{
    "data": {
        "id": "336cb9f7-3733-4e5a-9ab7-c42a05ebff22",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "transaction_id": "0ceec557-418c-476d-a9b2-def89048dc4d",
        "reason": "Discount issued",
        "internal_transaction_id": "121212",
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "return_response": {
            "status": "PASS",
            "response_code": "A0000",
            "response_message": "Success",
            "auth_code": "255385",
            "host_response_code": "00",
            "host_reference_number": "497915451651",
            "task_id": "20501784",
            "transaction_id": "76968598",
            "transaction_timestamp": "2025-04-02T18:58:21",
            "order_number": "59753509",
            "processed_amount": "16.40",
            "external_reference_id": "59753509",
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:58 PM         \\n               REFUND               \\n            Card # 1111             \\n          Card Type: VISA           \\n         Entry Mode : KEYED         \\n      Transaction ID: 76968598      \\n        SUBTOTAL: USD $16.40        \\n         TOTAL: USD $16.40          \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:58 PM         \\n               REFUND               \\n            Card # 1111             \\n          Card Type: VISA           \\n         Entry Mode : KEYED         \\n      Transaction ID: 76968598      \\n        SUBTOTAL: USD $16.40        \\n         TOTAL: USD $16.40          \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "masked_card_number": "1111",
            "card_type": "visa",
            "returned_amount": "16.40"
        },
        "metadata": {
            "customer_id": "123",
            "email": "test@test.com"
        },
        "order_number": "150t65898"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Webhook event: **PAYMENT\_REFUNDED**
{% endhint %}

#### Webhook Payload Example

```json
{
    "event_uid": "d774ae2550b7288a135dfa025b8b4605",
    "event": "PAYMENT_REFUNDED",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "reason": "Discount issued",
        "metadata": {
            "email": "test@test.com",
            "customer_id": "123"
        },
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "order_number": "150t65898",
        "transaction_id": "829856bf-e04b-4c57-a092-2a46798859c4",
        "return_response": {
            "status": "PASS",
            "task_id": "54543964",
            "auth_code": "941825",
            "card_type": "visa",
            "order_number": "79928879",
            "response_code": "A0000",
            "transaction_id": "40808945",
            "returned_amount": "16.40",
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:59 PM         \\n               REFUND               \\n            Card # 1111             \\n          Card Type: VISA           \\n         Entry Mode : KEYED         \\n      Transaction ID: 40808945      \\n        SUBTOTAL: USD $16.40        \\n         TOTAL: USD $16.40          \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 06:59 PM         \\n               REFUND               \\n            Card # 1111             \\n          Card Type: VISA           \\n         Entry Mode : KEYED         \\n      Transaction ID: 40808945      \\n        SUBTOTAL: USD $16.40        \\n         TOTAL: USD $16.40          \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "processed_amount": "16.40",
            "response_message": "Success",
            "host_response_code": "00",
            "masked_card_number": "1111",
            "external_reference_id": "79928879",
            "host_reference_number": "817267004532",
            "transaction_timestamp": "2025-04-02T18:59:34"
        },
        "internal_transaction_id": "987654321",
        "original_transaction_id": "fb49209e-c0d6-45dd-9045-014e0cfeb356"
    }
}
```