Process OpenPix refund transaction

Author: rennerocha

thebook/webhooks/openpix/services.py

@@ -16,6 +16,8 @@ def calculate_openpix_fee(amount, transaction_type):
     on the amount received, the active account plan and the type of the transaction
     """
     fee = 0.0
+    if transaction_type == "REFUND":
+        return fee
 
     if transaction_type == "WITHDRAW":
         fee = -1
@@ -68,12 +70,25 @@ def fetch_transactions(start_date: datetime.date, end_date: datetime.date):
 
         transaction_type = jmespath.search("type", transaction)
         is_bank_account_transfer = transaction_type == "WITHDRAW"
+        is_refund = transaction_type == "REFUND"
         if is_bank_account_transfer:
             transaction_category = bank_account_transfer_category
             transaction_description = (
                 f"Transferência entre contas bancárias - {transaction_id}"
             )
             transaction_amount = -1 * transaction_amount
+        elif is_refund:
+            transaction_category = None
+            credit_party_name = (
+                jmespath.search("creditParty.holder.name", transaction) or ""
+            )
+            credit_party_tax_id = jmespath.search(
+                "creditParty.holder.taxID.taxID", transaction
+            )
+            transaction_description = (
+                f"Reembolso - {credit_party_name} - {credit_party_tax_id}"
+            )
+            transaction_amount = -1 * transaction_amount
         else:
             transaction_category = None
             payer_name = jmespath.search("payer.name", transaction) or ""
@@ -97,17 +112,18 @@ def fetch_transactions(start_date: datetime.date, end_date: datetime.date):
             transaction_amount, transaction_type
         )
 
-        results.append(
-            Transaction(
-                reference=f"{transaction_id}-T",
-                date=transaction_date,
-                description=f"Taxa OpenPix - {transaction_description}",
-                amount=transaction_fee_amount,
-                bank_account=bank_account,
-                category=bank_fee_category,
-                source="openpix-fetch-transactions",
-                created_by=user,
+        if transaction_fee_amount != 0.0:
+            results.append(
+                Transaction(
+                    reference=f"{transaction_id}-T",
+                    date=transaction_date,
+                    description=f"Taxa OpenPix - {transaction_description}",
+                    amount=transaction_fee_amount,
+                    bank_account=bank_account,
+                    category=bank_fee_category,
+                    source="openpix-fetch-transactions",
+                    created_by=user,
+                )
             )
-        )
 
     return results

thebook/webhooks/tests/openpix/sample_payloads/openpix__refund_transaction.json

@@ -0,0 +1,69 @@
+{
+  "pageInfo": {
+    "skip": 0,
+    "limit": 100,
+    "hasPreviousPage": false,
+    "hasNextPage": false
+  },
+  "status": "OK",
+  "transactions": [
+    {
+      "value": 10200,
+      "time": "2026-03-24T23:36:42.136Z",
+      "endToEndId": "D54811417202603242336EmE2DpJUiYc",
+      "status": "CONFIRMED",
+      "type": "REFUND",
+      "pixQrCode": {
+        "name": "MSVG9",
+        "value": 10200,
+        "comment": "good",
+        "identifier": "MSVG9",
+        "correlationID": "ABCD9",
+        "paymentLinkID": "4da5a308-cf3b-430b-8f71-66a565857703",
+        "createdAt": "2026-03-16T23:53:19.385Z",
+        "updatedAt": "2026-03-16T23:53:19.385Z"
+      },
+      "subType": "REFUND_SENT",
+      "debitParty": {
+        "pixKey": {
+          "pixKey": "e77996eb-d15e-46ea-99a7-3190af4e293e",
+          "type": "RANDOM"
+        },
+        "account": {
+          "branch": "0001",
+          "account": "987654",
+          "accountType": "TRAN"
+        },
+        "psp": {
+          "id": "11111111",
+          "name": "WOOVI IP LTDA."
+        },
+        "holder": {
+          "taxID": {
+            "taxID": "12345678000110",
+            "type": "BR:CNPJ"
+          }
+        }
+      },
+      "creditParty": {
+        "account": {
+          "branch": "0001",
+          "account": "12345678",
+          "accountType": "TRAN"
+        },
+        "psp": {
+          "id": "12345678",
+          "name": "NU PAGAMENTOS - IP"
+        },
+        "holder": {
+          "name": "John Doe",
+          "taxID": {
+            "taxID": "12345678910",
+            "type": "BR:CPF"
+          }
+        }
+      },
+      "createdAt": "2026-03-24T23:36:42.225Z"
+    }
+  ]
+}

thebook/webhooks/tests/openpix/test_calculate_openpix_fee.py

@@ -22,6 +22,8 @@
         ("FIXO", "PAYMENT", 630, -0.85),
         ("PERCENTUAL", "WITHDRAW", 630, -1),
         ("FIXO", "WITHDRAW", 630, -1),
+        ("FIXO", "REFUND", 630, 0.0),
+        ("PERCENTUAL", "REFUND", 630, 0.0),
     ],
 )
 def test_calculate_openpix_fee_based_on_selected_plan(

thebook/webhooks/tests/openpix/test_services__fetch_transactions.py

@@ -77,6 +77,14 @@ def openpix_fetch_transactions__withdraw_transaction():
         return payload.read()
 
 
+@pytest.fixture
+def openpix__refund_transaction():
+    with open(
+        Path(SAMPLE_PAYLOADS_DIR / "openpix__refund_transaction.json"), "r"
+    ) as payload:
+        return payload.read()
+
+
 @responses.activate
 def test_fetch_multiple_transactions(
     db,
@@ -267,3 +275,32 @@ def test_fetch_withdraw_transaction(
     assert transactions[1].bank_account == openpix_bank_account
     assert transactions[1].category == bank_fee_category
     assert transactions[1].created_by == user
+
+
+@responses.activate
+def test_fetch_refund_transaction(
+    db,
+    openpix__refund_transaction,
+    openpix_bank_account,
+    user,
+):
+    responses.add(
+        responses.GET,
+        f"{settings.OPENPIX_API_BASE_URL}/api/v1/transaction",
+        body=openpix__refund_transaction,
+        content_type="application/json",
+    )
+
+    transactions = fetch_transactions(
+        start_date=datetime.date(2026, 3, 24), end_date=datetime.date(2026, 3, 26)
+    )
+
+    assert len(transactions) == 1
+
+    assert transactions[0].reference == "D54811417202603242336EmE2DpJUiYc"
+    assert transactions[0].date == datetime.date(2026, 3, 24)
+    assert transactions[0].description == "Reembolso - John Doe - 12345678910"
+    assert transactions[0].amount == Decimal("-102")
+    assert transactions[0].bank_account == openpix_bank_account
+    assert transactions[0].source == "openpix-fetch-transactions"
+    assert transactions[0].created_by == user