Refund

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

POST https://<PayEngine-host>/api/payment/refund

Request Body

Name	Type	Description
amount*	string	Amount to be refunded. Should be less or equal to available transaction amount
id*	string	Transaction ID
reason*	string	Reason for the refund
metadata	object	Add any additional metadata by passing a json object
internal_transaction_id	string	An internal ID from integrating system. Will be returned in the response and associated refunds if provided.

200

Refund Response Field Definitions

Field Name	Type	Description	Required?
id	string	PayEngine payment ID for the sale request	Required
transaction_id	string	Unique transaction ID	Required
merchant_id	string	Merchant ID	Required
gateway_id	string	ID of the gateway through which the transaction is processed	Optional
reason	string	Reason provided in the request	Required
token	string	Card token used in the original transaction	Required
internal_transaction_id	string	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	Optional
order_number	string	Order number provided in the original transaction	Optional
return_response	object	Refer to Credit Card Sale (SaleResponse) or ACH Sale (AchResponse) object definitions	Required
metadata	object	Return all the metadata sent in the request	Optional

Sample Request / Response

Request Body

Example Request

{
    "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" : "[email protected]"
    }
}

Response Body

Webhook event: PAYMENT_REFUNDED

Webhook Payload Example

{
    "event_uid": "d774ae2550b7288a135dfa025b8b4605",
    "event": "PAYMENT_REFUNDED",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "reason": "Discount issued",
        "metadata": {
            "email": "[email protected]",
            "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"
    }
}