dime-python-sdk 1.2.0__tar.gz → 1.3.1__tar.gz

{dime_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/PKG-INFO

@@ -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 → dime_python_sdk-1.3.1}/README.md

@@ -174,6 +174,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')
@@ -223,9 +228,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', {
@@ -233,6 +281,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 → dime_python_sdk-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dime-python-sdk"
-version = "1.2.0"
+version = "1.3.1"
 description = "Python client for the Dime Payments API"
 readme = "README.md"
 requires-python = ">=3.10"

{dime_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.3.1/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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_python_sdk-1.2.0 → dime_python_sdk-1.3.1}/src/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 → dime_python_sdk-1.3.1}/tests/unit/test_invoices.py

@@ -254,3 +254,105 @@ def test_delete_line_item_sends_both_ids_and_returns_invoice():
     assert data['invoice_id'] == 7
     assert data['line_item_id'] == 1
     assert invoice.id == 7
+
+
+# --- Required cover fees -----------------------------------------------------
+#
+# The fee is quoted per payment method against the balance and is deliberately
+# absent from `total`, which stays the amount owed to the merchant.
+
+COVER_FEE_BODY = {
+    **INVOICE_BODY,
+    'subtotal': 100.0,
+    'total': 100.0,
+    'balance': 100.0,
+    'cover_fee_required': True,
+    'cover_fee_quote': {
+        'basis': 'balance',
+        'base': 100.0,
+        'cc': {'fee': 4.32, 'total': 104.32},
+        'ach': {'fee': 1.26, 'total': 101.26},
+    },
+    'payments': [
+        {
+            'amount': 100.0,
+            'cover_fee': 4.32,
+            'paid_at': '2026-08-06T10:00:00+00:00',
+            'method': '+CC',
+            'transaction_id': 91,
+        },
+    ],
+}
+
+
+def test_create_sends_cover_fee_required():
+    client, mock = fake_client([{'status': 201, 'body': {'data': INVOICE_BODY}}])
+    client.invoices.create(
+        '000010',
+        {
+            'customer_uuid': 'cus-uuid',
+            'customer_name': 'Jane Doe',
+            'customer_email': 'jane@example.com',
+            'payment_terms': 'net_15',
+            'cover_fee_required': True,
+            'lines': [{'item_id': 5, 'name': 'Consulting', 'quantity': 1, 'unit_price': 100}],
+        },
+    )
+    assert sent_body(mock)['data']['cover_fee_required'] is True
+
+
+def test_recurring_create_sends_cover_fee_required():
+    client, mock = fake_client([{'status': 201, 'body': {'data': {'id': 3, 'status': 'Active'}}}])
+    client.recurring_invoices.create(
+        '000010',
+        {
+            'customer_uuid': 'cus-uuid',
+            'payment_terms': 'net_30',
+            'cover_fee_required': True,
+            'recurring_frequency': 'Monthly',
+            'recurring_start_date': '2026-09-01',
+            'lines': [{'item_id': 5, 'name': 'Retainer', 'quantity': 1, 'unit_price': 500}],
+        },
+    )
+    assert sent_body(mock)['data']['cover_fee_required'] is True
+
+
+def test_show_parses_the_per_method_quote_and_keeps_it_out_of_total():
+    client, _ = fake_client([{'status': 200, 'body': {'data': COVER_FEE_BODY}}])
+    invoice = client.invoices.show('000010', 7)
+
+    assert invoice.cover_fee_required is True
+    assert invoice.cover_fee_quote is not None
+    assert invoice.cover_fee_quote.basis == 'balance'
+    assert invoice.cover_fee_quote.cc_fee == '4.32'
+    assert invoice.cover_fee_quote.cc_total == '104.32'
+    assert invoice.cover_fee_quote.ach_fee == '1.26'
+    assert invoice.cover_fee_quote.ach_total == '101.26'
+    # The merchant is still owed the invoice amount; the fee sits on top of it.
+    assert invoice.total == '100.0'
+
+
+def test_payment_reports_the_fee_charged_alongside_the_amount_credited():
+    client, _ = fake_client([{'status': 200, 'body': {'data': COVER_FEE_BODY}}])
+    payment = client.invoices.show('000010', 7).payments[0]
+
+    # amount + cover_fee is what the customer was actually charged.
+    assert payment.amount == '100.0'
+    assert payment.cover_fee == '4.32'
+
+
+def test_quote_is_none_when_no_fee_is_required():
+    client, _ = fake_client([invoice_response()])
+    invoice = client.invoices.show('000010', 7)
+
+    assert invoice.cover_fee_required is False
+    assert invoice.cover_fee_quote is None
+
+
+def test_list_reads_the_cover_fee_flag():
+    client, _ = fake_client(
+        [{'status': 200, 'body': {'data': [{**INVOICE_BODY, 'cover_fee_required': True}], 'meta': {}}}]
+    )
+    page = client.invoices.list('000010')
+
+    assert page.data[0].cover_fee_required is True