dime-python-sdk 1.2.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

dime_payments/config.py

@@ -8,7 +8,7 @@ if TYPE_CHECKING:
 
 class Config:
     DEFAULT_BASE_URL = 'https://app.dimepayments.com'
-    VERSION = '1.2.0'
+    VERSION = '1.3.1'
 
     def __init__(
         self,

dime_payments/data_objects/cover_fee_quote.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from typing import Any
+
+from ..support.arr import arr_object, arr_string
+
+
+@dataclass
+class CoverFeeQuote:
+    """
+    The processing fee a cover-fee invoice adds on top of what the customer pays,
+    quoted for both payment methods.
+
+    Present on an :class:`Invoice` only when ``cover_fee_required`` is true. The fee
+    is NOT a line item and is NOT part of the invoice's ``total``: the merchant is
+    owed ``total``, and the customer is charged ``total`` plus this fee. Card and
+    ACH rates differ, so the amount depends on how the customer chooses to pay —
+    ``cc_total`` is the higher of the two and what the invoice and its emails lead
+    with.
+
+    ``basis`` names what the quote was computed against — currently always
+    ``balance``, the amount still outstanding. Paying a partial amount re-quotes the
+    fee against that amount, so treat these as a quote for settling in full today
+    rather than a fixed charge.
+
+    Money is kept as strings, consistent with the rest of the SDK, to avoid float
+    rounding.
+    """
+
+    basis: str | None = None
+    base: str | None = None
+    cc_fee: str | None = None
+    cc_total: str | None = None
+    ach_fee: str | None = None
+    ach_total: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> 'CoverFeeQuote':
+        cc = arr_object(data, 'cc')
+        ach = arr_object(data, 'ach')
+
+        return cls(
+            basis=arr_string(data, 'basis'),
+            base=arr_string(data, 'base'),
+            cc_fee=arr_string(cc, 'fee'),
+            cc_total=arr_string(cc, 'total'),
+            ach_fee=arr_string(ach, 'fee'),
+            ach_total=arr_string(ach, 'total'),
+        )

dime_payments/data_objects/invoice.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass, field
 from typing import Any
 
 from ..support.arr import arr_array, arr_bool, arr_int, arr_object, arr_string
+from .cover_fee_quote import CoverFeeQuote
 from .invoice_customer import InvoiceCustomer
 from .invoice_event import InvoiceEvent
 from .invoice_payment import InvoicePayment
@@ -15,6 +16,10 @@ class Invoice:
 
     Money fields arrive as dollar amounts and are kept as strings, consistent
     with the rest of the SDK, to avoid float rounding.
+
+    When ``cover_fee_required`` is set the customer must also pay the processing
+    fee, which is reported on :attr:`cover_fee_quote` rather than included in
+    ``total`` — so what settles is more than what the invoice says.
     """
 
     id: int | None = None
@@ -30,6 +35,8 @@ class Invoice:
     amount_paid: str | None = None
     balance: str | None = None
     allow_partial_payment: bool = False
+    cover_fee_required: bool = False
+    cover_fee_quote: CoverFeeQuote | None = None
     thank_you_note: str | None = None
     public_url: str | None = None
     customer: InvoiceCustomer = field(default_factory=InvoiceCustomer)
@@ -53,6 +60,12 @@ class Invoice:
             amount_paid=arr_string(data, 'amount_paid'),
             balance=arr_string(data, 'balance'),
             allow_partial_payment=arr_bool(data, 'allow_partial_payment'),
+            cover_fee_required=arr_bool(data, 'cover_fee_required'),
+            cover_fee_quote=(
+                CoverFeeQuote.from_dict(data['cover_fee_quote'])
+                if isinstance(data.get('cover_fee_quote'), dict)
+                else None
+            ),
             thank_you_note=arr_string(data, 'thank_you_note'),
             public_url=arr_string(data, 'public_url'),
             customer=InvoiceCustomer.from_dict(arr_object(data, 'customer')),

dime_payments/data_objects/invoice_payment.py

@@ -6,9 +6,17 @@ from ..support.arr import arr_int, arr_string
 
 @dataclass
 class InvoicePayment:
-    """A payment recorded against an invoice."""
+    """
+    A payment recorded against an invoice.
+
+    ``amount`` is what was credited to the invoice; ``cover_fee`` is the processing
+    fee charged on top of it, so ``amount + cover_fee`` is what the customer
+    actually paid. It is zero unless the invoice required the customer to cover
+    fees.
+    """
 
     amount: str | None = None
+    cover_fee: str | None = None
     paid_at: str | None = None
     method: str | None = None
     transaction_id: int | None = None
@@ -17,6 +25,7 @@ class InvoicePayment:
     def from_dict(cls, data: dict[str, Any]) -> 'InvoicePayment':
         return cls(
             amount=arr_string(data, 'amount'),
+            cover_fee=arr_string(data, 'cover_fee'),
             paid_at=arr_string(data, 'paid_at'),
             method=arr_string(data, 'method'),
             transaction_id=arr_int(data, 'transaction_id'),

dime_payments/data_objects/recurring_invoice.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Any
 
-from ..support.arr import arr_array, arr_int, arr_object, arr_string
+from ..support.arr import arr_array, arr_bool, arr_int, arr_object, arr_string
 from .invoice_customer import InvoiceCustomer
 from .line_item import LineItem
 
@@ -38,6 +38,8 @@ class RecurringInvoice:
     status: str | None = None
     recurrence_schedule: str | None = None
     payment_terms: str | None = None
+    # Copied onto every invoice this template generates.
+    cover_fee_required: bool = False
     start_date: str | None = None
     end_date: str | None = None
     next_run_date: str | None = None
@@ -55,6 +57,7 @@ class RecurringInvoice:
             status=arr_string(data, 'status'),
             recurrence_schedule=arr_string(data, 'recurrence_schedule'),
             payment_terms=arr_string(data, 'payment_terms'),
+            cover_fee_required=arr_bool(data, 'cover_fee_required'),
             start_date=arr_string(data, 'start_date'),
             end_date=arr_string(data, 'end_date'),
             next_run_date=arr_string(data, 'next_run_date'),

dime_payments/http/transport.py

@@ -11,7 +11,7 @@ from .error_handler import ErrorHandler
 if TYPE_CHECKING:
     from ..config import Config
 
-SDK_VERSION = '1.2.0'
+SDK_VERSION = '1.3.1'
 
 
 class Transport:

dime_payments/resources/invoices.py

@@ -25,6 +25,12 @@ class Invoices(AbstractResource):
     """
 
     def list(self, sid: str, filters: dict[str, Any] | None = None) -> CursorPage[Invoice]:
+        """
+        List invoices for a merchant.
+
+        ``filters['status']`` is one of draft, sent, viewed, partially_paid, paid, void,
+        refunded, overdue or all.
+        """
         body = self._envelope({'sid': sid}, filters or {})
         return self._paginate('GET', 'invoices', body, Invoice.from_dict)
 
@@ -39,6 +45,12 @@ class Invoices(AbstractResource):
         ``customer_name``, ``customer_email``, ``payment_terms``
         (``due_on_receipt`` | ``net_15`` | ``net_30`` | ``net_60``) and at least
         one entry in ``lines``, each referencing a Merchant ``item_id``.
+
+        Pass ``cover_fee_required`` to make the customer pay the processing fee. The
+        fee is added on top of the invoice at payment time rather than becoming a
+        line item, so ``total`` stays the amount owed to the merchant — read
+        :attr:`Invoice.cover_fee_quote` for what the customer will actually be
+        charged. Omit it to inherit the Merchant's invoice setting.
         """
         body = self._envelope({'sid': sid} | attributes)
         raw = self._transport.request('POST', 'invoice/create', body)
@@ -86,6 +98,12 @@ class Invoices(AbstractResource):
         ``expiration_date``; for ACH, pass ``routing_number`` /
         ``account_number`` / ``account_type`` / ``account_name``. Omit ``amount``
         to pay the full balance.
+
+        On a cover-fee invoice the processing fee for ``payment_type`` is charged on
+        top of ``amount``, so the card or bank account is debited more than the
+        invoice is credited. The fee lands as ``cover_fee`` on the matching entry in
+        :attr:`Invoice.payments`. Card and ACH rates differ, so the same ``amount``
+        settles differently per ``payment_type``.
         """
         body = self._envelope({'sid': sid, 'invoice_id': invoice_id} | attributes)
         raw = self._transport.request('POST', 'invoice/pay', body)

dime_payments/resources/recurring_invoices.py

@@ -18,6 +18,13 @@ class RecurringInvoices(AbstractResource):
         return RecurringInvoice.from_dict(raw.get('data') or {})
 
     def create(self, sid: str, attributes: dict[str, Any]) -> RecurringInvoice:
+        """
+        Create a recurring-invoice template. When ``recurring_start_date`` is today
+        the first invoice is generated and sent immediately.
+
+        ``cover_fee_required`` makes the customer cover the processing fee on every
+        invoice this template generates.
+        """
         body = self._envelope({'sid': sid} | attributes)
         raw = self._transport.request('POST', 'recurring-invoice/create', body)
         return RecurringInvoice.from_dict(raw.get('data') or {})

{dime_python_sdk-1.2.0.dist-info → dime_python_sdk-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dime-python-sdk
-Version: 1.2.0
+Version: 1.3.1
 Summary: Python client for the Dime Payments API
 Author: Dime Technology
 License: MIT License
@@ -218,6 +218,11 @@ item (a fund or designation). Draft invoices can be edited; once sent they are l
 Identify the customer with `customer_uuid` — the same uuid every other resource uses, and the only
 identifier the customer endpoints return. `customer_id` is still accepted for older integrations.
 
+**Statuses.** `invoice.status` is one of `draft`, `sent`, `viewed`, `partially_paid`, `paid`, `void` or
+`refunded`. `paid` is not always final: if the customer's bank returns an ACH payment, the invoice is
+reopened (back to `partially_paid`, `viewed` or `sent`, with `amount_paid` and `balance` updated) and an
+`invoice_payment_returned` webhook fires. Re-read the invoice rather than caching a `paid` status forever.
+
 ```python
 # Look up (or create) the merchant items a line can reference
 items = dime.invoices.list_items('000010')
@@ -267,9 +272,52 @@ dime.invoices.void('000010', invoice.id)
 dime.invoices.duplicate('000010', invoice.id)
 ```
 
+#### Making the customer cover processing fees
+
+Set `cover_fee_required` and the customer must pay the processing fee — it is not an optional
+checkbox at checkout. The fee is **not** a line item and is **not** part of `total`: the merchant is
+still owed `total`, and the fee is added on top of whatever the customer pays.
+
+Card and ACH rates differ, so the charge depends on how the customer pays. `cover_fee_quote` gives
+you both, quoted against the outstanding balance:
+
+```python
+invoice = dime.invoices.create('000010', {
+    'customer_uuid': customer.uuid,
+    'customer_name': 'Jane Doe',
+    'customer_email': 'jane@example.com',
+    'payment_terms': 'net_15',
+    'cover_fee_required': True,  # omit to inherit the merchant's invoice setting
+    'lines': [
+        {'item_id': item.id, 'name': 'Consulting', 'quantity': 1, 'unit_price': 100},
+    ],
+})
+
+invoice.total                      # '100.00' — what the merchant is owed
+invoice.cover_fee_quote.cc_total   # '104.32' — charged if they pay by card
+invoice.cover_fee_quote.ach_total  # '101.26' — charged if they pay by bank
+```
+
+The card figure is the higher of the two and is what the invoice and its emails lead with. A partial
+payment re-quotes the fee against the partial amount, so treat the quote as "settling in full today"
+rather than a fixed charge. `cover_fee_quote` is `None` when no fee is required.
+
+To reconcile a payment, `amount` was credited to the invoice and `cover_fee` was charged on top:
+
+```python
+payment = invoice.payments[0]
+payment.amount     # '100.00' — applied to the balance
+payment.cover_fee  # '4.32'   — the fee the customer also paid
+# The customer was charged amount + cover_fee.
+```
+
+`pay()` behaves the same way: the fee for the `payment_type` you pass is added to `amount`, so the
+card or bank account is debited more than the invoice is credited.
+
 ### Recurring invoices
 
-Templates that emit an invoice on a schedule.
+Templates that emit an invoice on a schedule. `cover_fee_required` is copied onto every invoice a
+template generates.
 
 ```python
 ri = dime.recurring_invoices.create('000010', {
@@ -277,6 +325,7 @@ ri = dime.recurring_invoices.create('000010', {
     'payment_terms': 'net_30',
     'recurring_frequency': 'Monthly',  # Weekly | Biweekly | FirstFifteenth | Monthly | Yearly
     'recurring_start_date': '2026-09-01',
+    'cover_fee_required': True,  # optional
     'lines': [
         {'item_id': item.id, 'name': 'Retainer', 'quantity': 1, 'unit_price': 500},
     ],

{dime_python_sdk-1.2.0.dist-info → dime_python_sdk-1.3.1.dist-info}/RECORD

@@ -1,24 +1,25 @@
 dime_payments/__init__.py,sha256=nJGtKtehbZMxar3wgdk8RIG_nNPSb6G9rmMyC2PnjqM,638
 dime_payments/client.py,sha256=dX_mH2q_hBZrC2s8B3Y3EYy3AWAvUYgTDNf1M0i9aFM,1328
-dime_payments/config.py,sha256=uRmAy2Pon8Uz1CzVPQp47Gk1VQl5aRsQRXf-FA9xSPY,847
+dime_payments/config.py,sha256=v9v2TmbjnDo-80IPhI5cMplEoIvkP5Tnyhp5JGjPXmQ,847
 dime_payments/data_objects/__init__.py,sha256=fuavK4aZ-IFM_PyMpJ8fIZlip7-V5m5LOHTCr2XnZng,1409
 dime_payments/data_objects/address.py,sha256=ocnxRM3JDLr4mDtlnVgsnUb6Hy5u6vNQlWVRFHzuMIw,950
+dime_payments/data_objects/cover_fee_quote.py,sha256=KuS1GMVe-Stixate6crTswvvhnq8e9Jfq3v4C2pRYr0,1717
 dime_payments/data_objects/customer.py,sha256=fSUPB9PynX_R3Jntnjr130ExeZtgrmRZSVfds54rmV0,1141
 dime_payments/data_objects/deposit.py,sha256=b0rQdNgdprMtP0pdMrepsWG3jBt7fJ4FGZ1EuHTRQhA,1139
 dime_payments/data_objects/deposit_group.py,sha256=kmfwnDO0YgmvmlSvIakb4cMFYOMfYDDnXMR4eiabSKA,813
 dime_payments/data_objects/deposit_with_transactions.py,sha256=HjmWB5v2R67z5xgqoZt1rlV5nxvixrTmySS-zzUFA0c,1420
 dime_payments/data_objects/form_link.py,sha256=rPU7cJynsrfb_1QjT8DkZ8ShvXVXUScBqJNZVASeJCI,280
-dime_payments/data_objects/invoice.py,sha256=x2_UplLFnmj2_BwTI2tgzflQJbCXdCk9jmmAoOlrWxg,2622
+dime_payments/data_objects/invoice.py,sha256=GQ6g-9e4toNsgJF-2WsnJ0S3mgeizrtYbBYhI3ur46E,3251
 dime_payments/data_objects/invoice_customer.py,sha256=GtnomaFO8xlpRuElMPPAAtlT5DwJLyp3NB5wGqdW9Bc,528
 dime_payments/data_objects/invoice_event.py,sha256=dvKOfcB9sxE6ehFQyB_lsfpA6iMFX3oK5WAUjSIpgDk,646
 dime_payments/data_objects/invoice_item.py,sha256=aVgO0UM7vqJB2VjvtYMBpLsCWXKHus0r7pA9I7UHwxo,856
 dime_payments/data_objects/invoice_link.py,sha256=kiWSXkl4jtsCZ-ODsEaFU12mTk3soe0qZ7ICDJ2MiEE,452
-dime_payments/data_objects/invoice_payment.py,sha256=jDllzFpRdaWAa0s89iNPdQG0dy61S47hvEMIbnKEpv8,635
+dime_payments/data_objects/invoice_payment.py,sha256=EPvs8FhhDyxEyRo8RoiVSRZK5LIBEwF5Iwjcw7DM0Ac,983
 dime_payments/data_objects/line_item.py,sha256=EJtpxnSOoCOlZJcrq8jDarieICPHtQK-g6jipTDMDAg,1024
 dime_payments/data_objects/merchant.py,sha256=U6RbP3QJACjOtrSExyodfz9zOzeU2hThXwGD6M0XATI,1900
 dime_payments/data_objects/message_result.py,sha256=2gZYbokwPRdlBUz_vGgYzrJpxMnjMuzwtTdjXhUv1GM,299
 dime_payments/data_objects/payment_method.py,sha256=-3kcHBGoXD12mzHocMoKU0aBwoNJ_9GJFx5eldXUJxA,2460
-dime_payments/data_objects/recurring_invoice.py,sha256=r5Qf656ByedP0LhmoEg9KVsIpC_svaPGEu231Mqqiy8,2612
+dime_payments/data_objects/recurring_invoice.py,sha256=pS4DEZdMnxhA6qwcM3bUH7k-yb0NU8-OvJdrk_cdihA,2785
 dime_payments/data_objects/recurring_payment.py,sha256=E6F3oX6aqWeE2Ek4ePqDDbZ79APdIKKXVip4bTcFU-g,2209
 dime_payments/data_objects/recurring_payment_method.py,sha256=P22ITvvxAUJ4NaEc7MH2ItCFm6wk1mEuxRs4ffSUDrg,402
 dime_payments/data_objects/tokenize_result.py,sha256=i27Hc0A-dFM8cX8s9A71yM95kd48ih25fvnb3SEml54,295
@@ -36,7 +37,7 @@ dime_payments/exceptions/server_exception.py,sha256=SCUubaM1wTwFMW3E9mBSxry4A-0Q
 dime_payments/exceptions/validation_exception.py,sha256=_HGMPN-5iFq6RWJY-06Oaak565MeD-yRf6GnbXp7Sog,689
 dime_payments/http/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dime_payments/http/error_handler.py,sha256=dqClsyDIcCPS6CtiqtGvEwTnORj24m2muXThXfHdhX0,2873
-dime_payments/http/transport.py,sha256=xYJ1OWHDTuTGuZgZPCLsV75AXEHUDyH1enBoIwwurac,2642
+dime_payments/http/transport.py,sha256=WkmSUgGbBPDHxuulejsflOE3awwzVhFahMgvXqHYznU,2642
 dime_payments/pagination/__init__.py,sha256=J2k8htn29Nu92KQh4wtEeN0StyMc8cWxVY8jQydF-dQ,62
 dime_payments/pagination/cursor_page.py,sha256=Xpbt33ceBy_HQlqe3wFbxA93bUfx3rHcqXfhVAkOQJ0,2263
 dime_payments/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -44,15 +45,15 @@ dime_payments/resources/abstract_resource.py,sha256=-XmnqJvk2tVNe44JeY_TTAzD4UiU
 dime_payments/resources/addresses.py,sha256=sg0q3YCnkdGlGM0onbBh_UsatrIu4VyzAA1BdZ1QRZ0,1713
 dime_payments/resources/customers.py,sha256=6_9gG9tc2uHN-onhzNFP0NO67NxGOYqbwZmF96vU4bo,1545
 dime_payments/resources/deposits.py,sha256=k8wE7kT_baHjXmXxzN9v6_2BqDb0GSUlINPRVtjmyUI,1213
-dime_payments/resources/invoices.py,sha256=_n2MPmBgn4IvQ9nhq9q8gSuVrxDDjfs5251S9PpywwA,7062
+dime_payments/resources/invoices.py,sha256=NOgfRP8q0BuRhGAl1w_0Cz0qNlJfgByK7g1SHJQ3Z0w,8027
 dime_payments/resources/merchants.py,sha256=blVx7JIAps9ktdpLjjQofEnVkK_KgXOQP8beBPkHrkg,1370
 dime_payments/resources/payment_methods.py,sha256=KJWryjnZadyohG1r6pmULjwPIjPIjScSK7ekQYamvYA,1775
-dime_payments/resources/recurring_invoices.py,sha256=mn-I-0o_uac6w-8HiwIWS2y0ptCZpVLZm3F60cyhl8w,1431
+dime_payments/resources/recurring_invoices.py,sha256=gJ4sNPvxv4qyNppsGZnW_orOfEVw4ROTa6yrN71Ax4g,1726
 dime_payments/resources/recurring_payments.py,sha256=DPihjc-C7oLLfPrP5UveNpEKHmUxayv4k3hFpguJ35c,2940
 dime_payments/resources/transactions.py,sha256=Q0VwYDicdGuM1WQXqxPX_KS313A0KZVCeuVCyKS_G7k,2742
 dime_payments/support/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dime_payments/support/arr.py,sha256=_mboi_q3HGn_Sx_MgU2exkbl-fnP2gdDY8yeSC8hkNc,1722
-dime_python_sdk-1.2.0.dist-info/METADATA,sha256=RwVXCQEwsDl3sm2uRGyIORwqFTAIP-o_6lQMuDVsGhk,12723
-dime_python_sdk-1.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-dime_python_sdk-1.2.0.dist-info/licenses/LICENSE,sha256=-Xc5dLgfuFLVQLsSKNYmJKtNZCUU1_9ErffdGiwH-DU,1072
-dime_python_sdk-1.2.0.dist-info/RECORD,,
+dime_python_sdk-1.3.1.dist-info/METADATA,sha256=Dd-xsvQGvO0ORUA2dK8EVYbdmrFT2qJrouHEKSqSNFs,15122
+dime_python_sdk-1.3.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dime_python_sdk-1.3.1.dist-info/licenses/LICENSE,sha256=-Xc5dLgfuFLVQLsSKNYmJKtNZCUU1_9ErffdGiwH-DU,1072
+dime_python_sdk-1.3.1.dist-info/RECORD,,

{dime_python_sdk-1.2.0.dist-info → dime_python_sdk-1.3.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any