Refund a payment transaction

Refunds part or all of a transaction through its payment gateway. This moves real money and is not idempotent: do not retry a call that succeeded.

Only transactions with status paid, authorized or refunded (partly refunded) can be refunded, and only up to the amount not refunded yet, excluding gateway fees, and no more than the item allows. On success the transaction status becomes refunded, or released when an authorization is released without charging. On a reservation, HQ records the refund only when metadata names the payment. When the account adds gateway fees to payments, HQ adjusts the amount sent to the gateway so that the matching part of the fee is returned too.

On an authorized transaction, the part of the hold that is not refunded is captured, so refunding 0 captures the whole hold.

Responses

🟢200OK

application/json

The refunded transaction in data.transaction. HTTP 200 is also used for failures: always check success. When it is false, the body is an ErrorBusinessRule (status_code 410) or an ErrorUnauthorized (status_code 401 or 403). An ErrorBusinessRule means the refund was not made, for example because the gateway rejected it, does not support refunds, or nothing is left to refund. Its reason, when the gateway gives one, is in errors.error.

Bodyapplication/json

Example

{
    "success": true,
    "status_code": 200,
    "errors": [],
    "data": {
        "transaction": {
            "id": 5512,
            "uuid": "8c1f7c1e-2b9a-4a51-9d1e-6f2a0b0f3c11",
            "item_type": "car_rental.reservations",
            "item_id": 1052,
            "contact_type": "contacts",
            "contact_id": 30,
            "gateway_id": 2,
            "method_id": 3,
            "label": "Reservation #1052",
            "description": "Rental deposit",
            "amount": "150.00",
            "refunded_amount": "50.00",
            "currency": "usd",
            "status": "refunded",
            "status_description": "Approved",
            "reference": "pi_3PZ0example",
            "authorization": false,
            "external_redirect": "https://www.example.com/booking/1052/paid",
            "external_url": "https://yourcompany.example.com/public/payment-gateways/payment-transactions/8c1f7c1e-2b9a-4a51-9d1e-6f2a0b0f3c11/external"
        }
    }
}

🟠404Record Not Found

🟠422Parameter Error

Request

Responses