changes

fusion_clover/utils.py

@@ -155,23 +155,45 @@ def build_charge_payload(amount, currency, source_token, capture=True,
 
 
 def build_refund_payload(charge_id, amount=None, currency=None, reason=''):
-    """Build a Clover refund payload.
+    """Build a Clover ``/v1/refunds`` payload.
+
+    The Clover Ecommerce ``/v1/refunds`` endpoint accepts ONLY the
+    ``charge`` field — including any other field triggers a 400
+    "Invalid JSON format" response. ``amount`` and ``reason`` arguments
+    are accepted for backwards-compat but ignored by this endpoint.
+
+    For partial refunds, callers should use the
+    ``/v1/payments/{paymentId}/refunds`` endpoint instead, which takes
+    ``{"amount": <cents>}`` or ``{"fullRefund": true}``.
+
+    https://docs.clover.com/dev/docs/ecommerce-refunding-payments
 
     :param str charge_id: The Clover charge ID to refund.
-    :param float amount: Optional partial refund amount in major currency units.
-    :param recordset currency: Optional currency record (needed for partial refunds).
-    :param str reason: Optional reason for the refund.
+    :param float amount: IGNORED on this endpoint (full refund only).
+        Use a /payments/{id}/refunds call for partial.
+    :param recordset currency: IGNORED.
+    :param str reason: IGNORED on this endpoint.
     :return: The Clover-formatted refund payload.
     :rtype: dict
     """
-    payload = {
-        'charge': charge_id,
-    }
+    return {'charge': charge_id}
 
+
+def build_payment_refund_payload(amount=None, currency=None, full_refund=False):
+    """Build a Clover ``/v1/payments/{paymentId}/refunds`` payload.
+
+    Used for partial refunds (the ``/v1/refunds`` endpoint is full-refund
+    only). Either pass ``full_refund=True`` to refund the entire payment,
+    or ``amount`` (with ``currency``) for a partial.
+
+    :param float amount: Partial refund amount in major currency units.
+    :param recordset currency: Currency record for the partial refund.
+    :param bool full_refund: If True, refund the entire payment.
+    :return: The Clover-formatted payment-refund payload.
+    :rtype: dict
+    """
+    if full_refund:
+        return {'fullRefund': True}
     if amount is not None and currency:
-        payload['amount'] = format_clover_amount(amount, currency)
-
-    if reason:
-        payload['reason'] = reason
-
-    return payload
+        return {'amount': format_clover_amount(amount, currency)}
+    return {'fullRefund': True}