A refund returns money to the customer after a payment has already been captured (settled or pending settlement). Use a refund when the funds have already moved — if the payment has only been authorized but not yet captured, use a void instead, which releases the hold without moving funds.

Refunds are processed by the Payment Proxy service. A transaction can only be refunded while it is in a CAPTURED, PARTIAL_REFUND, or REFUND_FAILED state; attempting to refund a transaction in any other state returns an error. Transactions can be refunded directly from the tenant console by selecing a CAPTURED transaction from the “Transaction History” section, as well as the API.

Full Refund

To refund the entire remaining amount of a transaction, set full_refund to true. You may optionally provide a full_refund_label (max 64 characters) to name the refund line item that is recorded against the transaction. When full_refund is true, do not include refund_items.

POST /v1/payment-proxy/transactions/{transaction_id}/refund

{
    "full_refund": true,
    "full_refund_label": "Full transaction refund",
    "metadata": { "reason": "customer_request" }
}

Partial Refund

To refund specific line items, set full_refund to false (the default) and provide a refund_items array. Each item mirrors the structure of the original transaction items. The total of the refund items must be lesser than or equal to the remaining refundable amount of the item and cannot exceed this amount, or the request is rejected.

POST /v1/payment-proxy/transactions/{transaction_id}/refund

{
    "full_refund": false,
    "refund_items": [
        {
            "name": "Standard Shipping",
            "amount": 9.99,
            "quantity": 1,
            "metadata": {}
        }
    ],
    "metadata": { "reason": "partial_return" }
}

The refund_items[].amount field is a numeric value. The request body is validated against the service’s published schema at the API gateway, so send amount as a JSON number (for example 9.99) and keep line-item name values to 64 characters or fewer.

Response

A successful refund returns the updated transaction status. When the full amount has been returned the status becomes FULL_REFUND; a partial return moves the transaction to PARTIAL_REFUND.

{
    "transaction_id": "a8d664f8-1673-4f58-8e70-ffe278dd28a5",
    "transaction_status": "PARTIAL_REFUND",
    "shorthand_ref_id": "NPB-0001AB",
    "gateway_response": { },
    "message": "Refund processed successfully."
}