Metadata-Version: 2.4
Name: dime-python-sdk
Version: 1.3.0
Summary: Python client for the Dime Payments API
Author: Dime Technology
License: MIT License
        
        Copyright (c) 2026 Dime Technology
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,dime,payments,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Dime Payments Python SDK

A typed Python client for the [Dime Payments](https://dimepayments.com) API.
Works with Python 3.10+ on any platform.

```python
from dime_payments import Client

dime = Client('your-api-token')

txn = dime.transactions.charge_card('000010', {
    'amount': '49.99',
    'token': 'tok_abc123',
})

print(txn.transaction_status)  # "Success"
```

## Requirements

- Python 3.10+
- A Dime API token (a Laravel Sanctum personal access token). Tokens are minted inside the
  Dime application, not via this SDK, and carry abilities (e.g. `transaction:charge-card-token`,
  `customer:read`) that gate which calls succeed.

## Installation

```bash
pip install dime-python-sdk
```

## Configuration

The simplest setup needs only a token:

```python
dime = Client('your-api-token')
```

Point it at another environment, or use `Config` for full control:

```python
from dime_payments import Client, Config

# Staging environment
dime = Client('your-api-token', 'https://staging.dimepayments.com')

# Full control
dime = Client(Config(
    token='your-api-token',
    base_url='https://app.dimepayments.com',
    timeout=30.0,       # seconds
    max_retries=2,      # retries 429 / 5xx / network errors with backoff
    retry_base_delay=0.5,
))
```

The SDK sends `Authorization: Bearer <token>` and JSON headers on every request. Transient
failures (HTTP 429 and 5xx, network errors) are retried with exponential backoff, honoring the
`Retry-After` header when present.

## Resources

Every resource hangs off the client as a property. The merchant `sid` is always passed
explicitly; remaining fields go in an `attributes` or `filters` dict. All amounts are
returned as strings to avoid float rounding.

| Property                        | Endpoints                                                             |
| ------------------------------- | --------------------------------------------------------------------- |
| `dime.transactions`             | charge_card, charge_ach, tokenize_card, refund, void, show, list     |
| `dime.customers`                | list, show, create, update, delete                                    |
| `dime.payment_methods`          | list, show, create, update, delete                                    |
| `dime.merchants`                | list, show, create, update, get_form_link                             |
| `dime.addresses`                | list, show, create, update, delete                                    |
| `dime.deposits`                 | list, list_with_transactions, show                                    |
| `dime.recurring_payments`       | list, show, create, edit, pause, cancel, activate, delete             |
| `dime.invoices`                 | list, show, create, update, delete, send, mark_sent, void, duplicate, pay, get_link, list_items, add_line_item, update_line_item, delete_line_item, create_item |
| `dime.recurring_invoices`       | list, show, create, cancel                                            |

### Transactions

```python
# Charge a stored token
txn = dime.transactions.charge_card('000010', {
    'amount': '100.00',
    'token': 'tok_abc123',
    'email': 'customer@example.com',
})

# Charge raw card details (merchant must be PCI compliant)
txn = dime.transactions.charge_card('000010', {
    'amount': '100.00',
    'cardholder_name': 'John Doe',
    'card_number': '4111111111111111',
    'expiration_date': '01/2027',
    'cvv': '123',
})

# ACH
txn = dime.transactions.charge_ach('000010', {
    'routing_number': '123456789',
    'account_number': '9876543210',
    'account_type': 'Checking',
    'account_name': 'John Doe',
    'amount': '75.00',
})

# Tokenize without charging
result = dime.transactions.tokenize_card('000010', {
    'cardholder_name': 'John Doe',
    'card_number': '4111111111111111',
    'expiration_date': '01/2027',
})
print(result.token)

# Refund / void
dime.transactions.refund('000010', {'amount': '25.00', 'transaction_info_id': 123456})
dime.transactions.void('000010', 'CC', 123456)

# Read
txn = dime.transactions.show('000010', {'transaction_info_id': 123456})
```

### Customers, payment methods, addresses

```python
customer = dime.customers.create('000010', {
    'first_name': 'Jane',
    'last_name': 'Doe',
    'email': 'jane@example.com',
})

pm = dime.payment_methods.create('000010', {
    'uuid': customer.uuid,
    'type': 'cc',
    'cc_name_on_card': 'Jane Doe',
    'cc_number': '4111111111111111',
    'cc_expiration_date': '01/2027',
    'cc_brand': 'Visa',
    'default': True,
})

address = dime.addresses.create('000010', customer.uuid, {
    'recipient': 'Jane Doe',
    'line_one': '123 Main St',
    'city': 'Atlanta',
    'state': 'GA',
    'zip': '30301',
})
```

### Recurring payments

```python
rp = dime.recurring_payments.create('000010', {
    'name': 'Monthly donation',
    'amount': '25.00',
    'start_date': '2026-07-01 00:00:00',
    'recurrence_schedule': 'Monthly',
    'payment_method': pm.id,
    'customer_uuid': customer.uuid,
})

dime.recurring_payments.pause('000010', rp.id, '2026-09-01 00:00:00')
dime.recurring_payments.activate('000010', rp.id)
dime.recurring_payments.cancel('000010', rp.id)
```

### Invoices

Invoices are scoped to a merchant `sid` and built from line items that each reference a merchant
item (a fund or designation). Draft invoices can be edited; once sent they are locked.

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.

```python
# Look up (or create) the merchant items a line can reference
items = dime.invoices.list_items('000010')
item = dime.invoices.create_item('000010', {
    'name': 'Consulting',
    'description': 'Professional services',
    'price': 125,
    'tax_deductible': False,
})

# Create a draft invoice with one or more line items
invoice = dime.invoices.create('000010', {
    'customer_uuid': customer.uuid,
    'customer_name': 'Jane Doe',
    'customer_email': 'jane@example.com',
    'payment_terms': 'net_15',  # due_on_receipt | net_15 | net_30 | net_60
    'lines': [
        {'item_id': item.id, 'name': 'Consulting', 'description': '2 hours',
         'quantity': 2, 'unit_price': 125},
    ],
})

# Line-item edits return the refreshed invoice, with totals recalculated
invoice = dime.invoices.add_line_item('000010', invoice.id, {
    'item_id': item.id, 'name': 'Setup', 'quantity': 1, 'unit_price': 50,
})
invoice = dime.invoices.update_line_item('000010', invoice.id, invoice.items[0].id, {'quantity': 3})
invoice = dime.invoices.delete_line_item('000010', invoice.id, invoice.items[0].id)

# Email it to the customer, or activate the pay link without emailing
dime.invoices.send('000010', invoice.id)
dime.invoices.mark_sent('000010', invoice.id)

# Share the public pay link
link = dime.invoices.get_link('000010', invoice.id)
print(link.public_url)

# Take a merchant-initiated payment. payment_type is required; omit amount to
# pay the full balance.
dime.invoices.pay('000010', invoice.id, {
    'payment_type': 'cc',  # cc | ach
    'token': pm.token,
    'amount': 125,
})

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. `cover_fee_required` is copied onto every invoice a
template generates.

```python
ri = dime.recurring_invoices.create('000010', {
    'customer_uuid': customer.uuid,
    '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},
    ],
})

print(ri.next_run_date, ri.upcoming_run_dates)

dime.recurring_invoices.cancel('000010', ri.id)
```

## Pagination

List endpoints return a `CursorPage`. Iterate one page, walk pages manually, or stream every
item across all pages with `auto_paging()`:

```python
page = dime.transactions.list('000010', {
    'start_date': '2026-01-01 00:00:00',
    'end_date': '2026-01-31 23:59:59',
})

# First page only
for txn in page:
    print(txn.amount)

# Next page manually
if page.has_more():
    next_page = page.next()

# Every transaction across every page (fetches lazily)
for txn in page.auto_paging():
    print(txn.transaction_number)
```

## Error handling

Every failure raises a `DimeException` subclass. Catch the base type, or a specific one:

```python
from dime_payments import (
    DimeException,
    ValidationException,
    RateLimitException,
)
import time

try:
    dime.transactions.charge_card('000010', {'amount': '0'})
except ValidationException as e:
    e.get_errors()   # {'data.amount': ['must be greater than 0']}
    e.first_error()
except RateLimitException as e:
    wait = e.get_retry_after() or 1
    time.sleep(wait)
except DimeException as e:
    e.get_status_code()    # HTTP status
    e.get_response_body()  # decoded API body
```

| Exception                    | When                                                         |
| ---------------------------- | ------------------------------------------------------------ |
| `ValidationException`        | HTTP 400/422 with field errors                               |
| `AuthenticationException`    | HTTP 401 (missing/invalid token)                             |
| `PermissionDeniedException`  | HTTP 403 (belongs-to-company guard)                          |
| `NotFoundException`          | HTTP 404                                                     |
| `RateLimitException`         | HTTP 429 (carries `Retry-After`)                             |
| `ServerException`            | HTTP 5xx                                                     |
| `ConnectionException`        | No HTTP response (DNS, timeout, network error)               |
| `ApiException`               | Any other non-2xx                                            |

## Notes

- **GET requests carry a JSON body.** The Dime API expects read parameters in the request body
  even for `GET` endpoints; the SDK handles this transparently. Point `base_url` at an `https://`
  origin — an `http://` URL that 301-redirects to `https` will have its request body dropped by the
  redirect, which surfaces as a `403` "You do not have access to this company." from the API.
- **No API versioning.** Endpoints live under `/api` with no version prefix.

## Development

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest                  # run tests
```

## License

MIT. See [LICENSE](LICENSE).
