moolah-poynt 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- moolah_poynt-0.1.0/.gitignore +29 -0
- moolah_poynt-0.1.0/LICENSE +21 -0
- moolah_poynt-0.1.0/PKG-INFO +240 -0
- moolah_poynt-0.1.0/README.md +217 -0
- moolah_poynt-0.1.0/pyproject.toml +40 -0
- moolah_poynt-0.1.0/src/moolah_poynt/__init__.py +44 -0
- moolah_poynt-0.1.0/src/moolah_poynt/_client.py +42 -0
- moolah_poynt-0.1.0/src/moolah_poynt/_http.py +260 -0
- moolah_poynt-0.1.0/src/moolah_poynt/_version.py +1 -0
- moolah_poynt-0.1.0/src/moolah_poynt/errors.py +75 -0
- moolah_poynt-0.1.0/src/moolah_poynt/models_generated.py +259 -0
- moolah_poynt-0.1.0/src/moolah_poynt/py.typed +0 -0
- moolah_poynt-0.1.0/src/moolah_poynt/resources.py +372 -0
- moolah_poynt-0.1.0/src/moolah_poynt/types.py +48 -0
- moolah_poynt-0.1.0/src/moolah_poynt/webhooks.py +206 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Node
|
|
2
|
+
node_modules/
|
|
3
|
+
typescript/dist/
|
|
4
|
+
*.tgz
|
|
5
|
+
|
|
6
|
+
# Python
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.py[cod]
|
|
9
|
+
*.egg-info/
|
|
10
|
+
.venv/
|
|
11
|
+
python/dist/
|
|
12
|
+
python/build/
|
|
13
|
+
|
|
14
|
+
# PHP
|
|
15
|
+
php/vendor/
|
|
16
|
+
php/composer.lock
|
|
17
|
+
.phpunit.result.cache
|
|
18
|
+
|
|
19
|
+
# .NET
|
|
20
|
+
bin/
|
|
21
|
+
obj/
|
|
22
|
+
*.nupkg
|
|
23
|
+
*.snupkg
|
|
24
|
+
TestResults/
|
|
25
|
+
|
|
26
|
+
# Editors / OS
|
|
27
|
+
.vscode/
|
|
28
|
+
.idea/
|
|
29
|
+
.DS_Store
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Moolah LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: moolah-poynt
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Official Python client for the Moolah Poynt API
|
|
5
|
+
Project-URL: Documentation, https://docs.moolahpay.cc
|
|
6
|
+
Author: Moolah
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: dental,moolah,payments,poynt,webhooks
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# moolah-poynt
|
|
25
|
+
|
|
26
|
+
Official Python client for the Moolah Poynt API: saved-card and ACH charges,
|
|
27
|
+
terminal payments, refunds, transactions and webhook verification.
|
|
28
|
+
|
|
29
|
+
- Python 3.11 or later. No dependencies (standard library `urllib`).
|
|
30
|
+
- Fully typed (`py.typed`); responses are plain dicts typed as `TypedDict`s.
|
|
31
|
+
- All amounts are **integer cents** (`2500` = $25.00).
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pip install moolah-poynt
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quickstart: tokenize, charge, refund
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import os
|
|
43
|
+
from moolah_poynt import MoolahClient, FundingSourceType
|
|
44
|
+
|
|
45
|
+
moolah = MoolahClient(os.environ["MOOLAH_API_KEY"])
|
|
46
|
+
|
|
47
|
+
# 1. Turn a Poynt Collect nonce from your payment form into a reusable token.
|
|
48
|
+
token = moolah.tokens.tokenize(nonce=nonce, save_card_on_file=True)["paymentToken"]
|
|
49
|
+
|
|
50
|
+
# 2. Charge it. If the card is surcharged and you send no surcharge,
|
|
51
|
+
# the API quotes it and charges it on top of `amount`.
|
|
52
|
+
sale = moolah.tokens.charge(
|
|
53
|
+
amount=2500,
|
|
54
|
+
payment_token=token,
|
|
55
|
+
funding_source_type=FundingSourceType.CARD,
|
|
56
|
+
transaction_number="INV-1001",
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
# 3. Refund part of it (repeatable against the same parent_id).
|
|
60
|
+
moolah.tokens.refund(
|
|
61
|
+
parent_id=sale["id"],
|
|
62
|
+
amount=1000,
|
|
63
|
+
payment_token=token,
|
|
64
|
+
funding_source_type=FundingSourceType.CARD,
|
|
65
|
+
)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`funding_source_type` is required whenever you send `payment_token`: `CARD` for
|
|
69
|
+
cards, `CHEQUE` (`FundingSourceType.ACH`) for bank accounts. The SDK enforces this
|
|
70
|
+
because the API treats a bare `paymentToken` as ACH.
|
|
71
|
+
|
|
72
|
+
Use `sale["processorResponse"]["approvedAmount"]` for what was actually approved
|
|
73
|
+
(it can be lower than `amounts.orderAmount` on a partial approval).
|
|
74
|
+
|
|
75
|
+
## Card on file: `intent` and `mit`
|
|
76
|
+
|
|
77
|
+
Stored-card charges are classified for the card networks. Both are optional; the API
|
|
78
|
+
defaults to `UNSCHEDULED_COF_TXN` and merchant-initiated.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
from moolah_poynt import CardOnFileIntent
|
|
82
|
+
|
|
83
|
+
moolah.tokens.charge(
|
|
84
|
+
amount=4900,
|
|
85
|
+
payment_token=token,
|
|
86
|
+
funding_source_type="CARD",
|
|
87
|
+
intent=CardOnFileIntent.RECURRING, # or INSTALLMENT, UNSCHEDULED
|
|
88
|
+
mit=True, # merchant-initiated; False when the cardholder is present and approving
|
|
89
|
+
)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
| `intent` | Use for |
|
|
93
|
+
|---|---|
|
|
94
|
+
| `UNSCHEDULED_COF_TXN` | Stored card charged at no fixed schedule (default) |
|
|
95
|
+
| `RECURRING_COF_TXN` | Fixed-schedule charges, e.g. a monthly membership plan |
|
|
96
|
+
| `INSTALLMENT_COF_TXN` | One of a fixed number of payments for one purchase, e.g. a treatment plan |
|
|
97
|
+
|
|
98
|
+
`mit` is only sent when you pass it, so an explicit `mit=False` reaches the API.
|
|
99
|
+
|
|
100
|
+
Tokenize a saved card by agreement instead of a nonce with
|
|
101
|
+
`moolah.tokens.tokenize(card_agreement_id="...")`.
|
|
102
|
+
|
|
103
|
+
ACH: check `moolah.business.ach_status()["allowAch"]` first; tokenizing a bank account
|
|
104
|
+
needs `financial_instrument_agreement` (the authorization the customer accepted).
|
|
105
|
+
|
|
106
|
+
## Terminal payments and reconciliation
|
|
107
|
+
|
|
108
|
+
`payments.terminal` pushes a sale to a Poynt terminal and waits (up to about 90
|
|
109
|
+
seconds) for the cardholder. If the outcome is unknown it raises
|
|
110
|
+
`TerminalNoResponseError`. **Do not retry blindly**: the payment may still complete
|
|
111
|
+
on the terminal. Reconcile first.
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from moolah_poynt import ReconcileOutcome, TerminalNoResponseError
|
|
115
|
+
|
|
116
|
+
try:
|
|
117
|
+
result = moolah.payments.terminal(device_id, amount=7500, reference_id="visit-8812")
|
|
118
|
+
except TerminalNoResponseError as err:
|
|
119
|
+
rec = moolah.payments.reconcile(err.reference_id)
|
|
120
|
+
if rec["outcome"] == ReconcileOutcome.COMPLETED:
|
|
121
|
+
... # it happened: record rec["transactions"], do not retry
|
|
122
|
+
elif rec["outcome"] == ReconcileOutcome.NOT_COMPLETED:
|
|
123
|
+
... # safe to try again
|
|
124
|
+
else: # PENDING
|
|
125
|
+
... # still unknown: ask again later; a retry may double-charge
|
|
126
|
+
# rec["matchedBy"] == "TIME_WINDOW" means no result was received and
|
|
127
|
+
# rec["transactions"] is the terminal's activity around that time. Check it.
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- Pass your own `reference_id` (otherwise the SDK generates a UUID) so every attempt can be reconciled.
|
|
131
|
+
- `TerminalNoResponseError` covers the API's `504 TERMINAL_NO_RESPONSE` and also a timeout,
|
|
132
|
+
dropped connection or gateway 502/503/504 during a terminal payment (`status` is 0 when no
|
|
133
|
+
response was received).
|
|
134
|
+
- Terminal payments are never retried automatically.
|
|
135
|
+
- List terminals with `moolah.devices.list()`.
|
|
136
|
+
|
|
137
|
+
Refund a terminal sale with `moolah.transactions.refund(transaction_id, amount=...)`
|
|
138
|
+
(omit `amount` for a full refund or void).
|
|
139
|
+
|
|
140
|
+
## Transactions
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from datetime import datetime, timezone
|
|
144
|
+
|
|
145
|
+
page = moolah.transactions.list(start_at=datetime(2026, 10, 1, tzinfo=timezone.utc), limit=50, order_by="desc")
|
|
146
|
+
txn = moolah.transactions.get(txn_id)
|
|
147
|
+
moolah.transactions.capture(auth_id) # full capture
|
|
148
|
+
moolah.transactions.capture(auth_id, amount=1500) # partial
|
|
149
|
+
moolah.transactions.refund(txn_id, amount=500) # partial refund
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Webhooks
|
|
153
|
+
|
|
154
|
+
Endpoints and their signing secrets are managed in the Moolah Developer Portal
|
|
155
|
+
(there is no API for registering them). Verify every delivery against the **raw**
|
|
156
|
+
request body:
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from flask import Flask, request
|
|
160
|
+
from moolah_poynt import verify_webhook, WebhookVerificationError
|
|
161
|
+
|
|
162
|
+
@app.post("/webhooks/moolah")
|
|
163
|
+
def moolah_webhook():
|
|
164
|
+
try:
|
|
165
|
+
event = verify_webhook(request.get_data(), request.headers, os.environ["MOOLAH_WEBHOOK_SECRET"])
|
|
166
|
+
except WebhookVerificationError:
|
|
167
|
+
return "", 400
|
|
168
|
+
enqueue(event) # respond within 15 s; de-duplicate on event.id
|
|
169
|
+
return "", 204
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
The event is thin (no amounts or card data):
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
event.type # "transaction.captured" (also authorized, refunded, updated, declined, voided)
|
|
176
|
+
event.event_type # "TRANSACTION_CAPTURED", as sent
|
|
177
|
+
event.business_id # which business; one endpoint receives events for all of your businesses
|
|
178
|
+
event.resource_id # the transaction id: fetch it with the API key for that business
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Verification follows Standard Webhooks: HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`,
|
|
182
|
+
any `v1,` signature in `webhook-signature` may match (secret rotation), constant-time comparison,
|
|
183
|
+
and timestamps more than 5 minutes from your clock are rejected (`tolerance_seconds=` to change).
|
|
184
|
+
Headers may be any mapping (looked up case-insensitively) or a list of `(name, value)` pairs.
|
|
185
|
+
`client.webhooks.verify(...)` is the same function.
|
|
186
|
+
|
|
187
|
+
## Errors
|
|
188
|
+
|
|
189
|
+
| Exception | When |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `MoolahApiError` | Non-2xx response. `status`, `code` (str, if the API sent one), `message`, `request_id`, `body`. |
|
|
192
|
+
| `TerminalNoResponseError` | Terminal payment outcome unknown. Adds `reference_id`. Subclass of `MoolahApiError`. |
|
|
193
|
+
| `MoolahConnectionError` | Network failure or timeout (`timed_out`). |
|
|
194
|
+
| `WebhookVerificationError` | Webhook failed verification. |
|
|
195
|
+
| `ValueError` / `TypeError` | Invalid arguments (e.g. a float `amount`), raised before any request. |
|
|
196
|
+
|
|
197
|
+
All SDK exceptions derive from `MoolahError`. Refund failures carry numeric API codes as strings:
|
|
198
|
+
`"101"` cash payment, `"102"` already voided, `"103"` partial refund of an unsettled transaction
|
|
199
|
+
(void it in full instead), `"104"` already refunded, `"105"` processor rejected.
|
|
200
|
+
|
|
201
|
+
`request_id` comes from the `X-Request-Id` (or `X-Poynt-Request-Id`) response header; include it
|
|
202
|
+
when contacting support.
|
|
203
|
+
|
|
204
|
+
## Retries
|
|
205
|
+
|
|
206
|
+
The client retries up to `max_retries` times (default 2) with exponential backoff, honouring
|
|
207
|
+
`Retry-After`, on `429`, `502`, `503`, `504` and network errors, but only for requests that are
|
|
208
|
+
safe to repeat:
|
|
209
|
+
|
|
210
|
+
- `GET` requests: always.
|
|
211
|
+
- Charge, authorize and refund calls: only when you pass `transaction_number`.
|
|
212
|
+
- Tokenize, capture and terminal payments: never.
|
|
213
|
+
|
|
214
|
+
`transaction_number` is your reference for the charge. The API does not document server-side
|
|
215
|
+
de-duplication on it, so a retried charge can, in rare cases, be processed twice: pass
|
|
216
|
+
`max_retries=0` if you would rather handle every failure yourself.
|
|
217
|
+
|
|
218
|
+
## Configuration
|
|
219
|
+
|
|
220
|
+
```python
|
|
221
|
+
MoolahClient(
|
|
222
|
+
api_key,
|
|
223
|
+
base_url="https://process.moolahpay.cc", # default
|
|
224
|
+
timeout=120.0, # seconds per socket operation; must exceed the 90 s terminal wait
|
|
225
|
+
max_retries=2,
|
|
226
|
+
user_agent="my-practice-app/1.4", # appended to the SDK's User-Agent
|
|
227
|
+
)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Methods also accept `timeout=` and (where retries apply) `max_retries=`. Redirects are never
|
|
231
|
+
followed. Proxies are taken from the standard `HTTPS_PROXY`/`NO_PROXY` environment variables.
|
|
232
|
+
|
|
233
|
+
## Development
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
python -m unittest discover -s tests -t . # with PYTHONPATH=src, or after pip install -e .
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The tests run against a local fake HTTP server. `src/moolah_poynt/models_generated.py` is
|
|
240
|
+
generated from `../spec/openapi-public.json` by `../spec/tools/gen_models.py`; do not edit it.
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# moolah-poynt
|
|
2
|
+
|
|
3
|
+
Official Python client for the Moolah Poynt API: saved-card and ACH charges,
|
|
4
|
+
terminal payments, refunds, transactions and webhook verification.
|
|
5
|
+
|
|
6
|
+
- Python 3.11 or later. No dependencies (standard library `urllib`).
|
|
7
|
+
- Fully typed (`py.typed`); responses are plain dicts typed as `TypedDict`s.
|
|
8
|
+
- All amounts are **integer cents** (`2500` = $25.00).
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
pip install moolah-poynt
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Quickstart: tokenize, charge, refund
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
import os
|
|
20
|
+
from moolah_poynt import MoolahClient, FundingSourceType
|
|
21
|
+
|
|
22
|
+
moolah = MoolahClient(os.environ["MOOLAH_API_KEY"])
|
|
23
|
+
|
|
24
|
+
# 1. Turn a Poynt Collect nonce from your payment form into a reusable token.
|
|
25
|
+
token = moolah.tokens.tokenize(nonce=nonce, save_card_on_file=True)["paymentToken"]
|
|
26
|
+
|
|
27
|
+
# 2. Charge it. If the card is surcharged and you send no surcharge,
|
|
28
|
+
# the API quotes it and charges it on top of `amount`.
|
|
29
|
+
sale = moolah.tokens.charge(
|
|
30
|
+
amount=2500,
|
|
31
|
+
payment_token=token,
|
|
32
|
+
funding_source_type=FundingSourceType.CARD,
|
|
33
|
+
transaction_number="INV-1001",
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
# 3. Refund part of it (repeatable against the same parent_id).
|
|
37
|
+
moolah.tokens.refund(
|
|
38
|
+
parent_id=sale["id"],
|
|
39
|
+
amount=1000,
|
|
40
|
+
payment_token=token,
|
|
41
|
+
funding_source_type=FundingSourceType.CARD,
|
|
42
|
+
)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`funding_source_type` is required whenever you send `payment_token`: `CARD` for
|
|
46
|
+
cards, `CHEQUE` (`FundingSourceType.ACH`) for bank accounts. The SDK enforces this
|
|
47
|
+
because the API treats a bare `paymentToken` as ACH.
|
|
48
|
+
|
|
49
|
+
Use `sale["processorResponse"]["approvedAmount"]` for what was actually approved
|
|
50
|
+
(it can be lower than `amounts.orderAmount` on a partial approval).
|
|
51
|
+
|
|
52
|
+
## Card on file: `intent` and `mit`
|
|
53
|
+
|
|
54
|
+
Stored-card charges are classified for the card networks. Both are optional; the API
|
|
55
|
+
defaults to `UNSCHEDULED_COF_TXN` and merchant-initiated.
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
from moolah_poynt import CardOnFileIntent
|
|
59
|
+
|
|
60
|
+
moolah.tokens.charge(
|
|
61
|
+
amount=4900,
|
|
62
|
+
payment_token=token,
|
|
63
|
+
funding_source_type="CARD",
|
|
64
|
+
intent=CardOnFileIntent.RECURRING, # or INSTALLMENT, UNSCHEDULED
|
|
65
|
+
mit=True, # merchant-initiated; False when the cardholder is present and approving
|
|
66
|
+
)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| `intent` | Use for |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `UNSCHEDULED_COF_TXN` | Stored card charged at no fixed schedule (default) |
|
|
72
|
+
| `RECURRING_COF_TXN` | Fixed-schedule charges, e.g. a monthly membership plan |
|
|
73
|
+
| `INSTALLMENT_COF_TXN` | One of a fixed number of payments for one purchase, e.g. a treatment plan |
|
|
74
|
+
|
|
75
|
+
`mit` is only sent when you pass it, so an explicit `mit=False` reaches the API.
|
|
76
|
+
|
|
77
|
+
Tokenize a saved card by agreement instead of a nonce with
|
|
78
|
+
`moolah.tokens.tokenize(card_agreement_id="...")`.
|
|
79
|
+
|
|
80
|
+
ACH: check `moolah.business.ach_status()["allowAch"]` first; tokenizing a bank account
|
|
81
|
+
needs `financial_instrument_agreement` (the authorization the customer accepted).
|
|
82
|
+
|
|
83
|
+
## Terminal payments and reconciliation
|
|
84
|
+
|
|
85
|
+
`payments.terminal` pushes a sale to a Poynt terminal and waits (up to about 90
|
|
86
|
+
seconds) for the cardholder. If the outcome is unknown it raises
|
|
87
|
+
`TerminalNoResponseError`. **Do not retry blindly**: the payment may still complete
|
|
88
|
+
on the terminal. Reconcile first.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from moolah_poynt import ReconcileOutcome, TerminalNoResponseError
|
|
92
|
+
|
|
93
|
+
try:
|
|
94
|
+
result = moolah.payments.terminal(device_id, amount=7500, reference_id="visit-8812")
|
|
95
|
+
except TerminalNoResponseError as err:
|
|
96
|
+
rec = moolah.payments.reconcile(err.reference_id)
|
|
97
|
+
if rec["outcome"] == ReconcileOutcome.COMPLETED:
|
|
98
|
+
... # it happened: record rec["transactions"], do not retry
|
|
99
|
+
elif rec["outcome"] == ReconcileOutcome.NOT_COMPLETED:
|
|
100
|
+
... # safe to try again
|
|
101
|
+
else: # PENDING
|
|
102
|
+
... # still unknown: ask again later; a retry may double-charge
|
|
103
|
+
# rec["matchedBy"] == "TIME_WINDOW" means no result was received and
|
|
104
|
+
# rec["transactions"] is the terminal's activity around that time. Check it.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- Pass your own `reference_id` (otherwise the SDK generates a UUID) so every attempt can be reconciled.
|
|
108
|
+
- `TerminalNoResponseError` covers the API's `504 TERMINAL_NO_RESPONSE` and also a timeout,
|
|
109
|
+
dropped connection or gateway 502/503/504 during a terminal payment (`status` is 0 when no
|
|
110
|
+
response was received).
|
|
111
|
+
- Terminal payments are never retried automatically.
|
|
112
|
+
- List terminals with `moolah.devices.list()`.
|
|
113
|
+
|
|
114
|
+
Refund a terminal sale with `moolah.transactions.refund(transaction_id, amount=...)`
|
|
115
|
+
(omit `amount` for a full refund or void).
|
|
116
|
+
|
|
117
|
+
## Transactions
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from datetime import datetime, timezone
|
|
121
|
+
|
|
122
|
+
page = moolah.transactions.list(start_at=datetime(2026, 10, 1, tzinfo=timezone.utc), limit=50, order_by="desc")
|
|
123
|
+
txn = moolah.transactions.get(txn_id)
|
|
124
|
+
moolah.transactions.capture(auth_id) # full capture
|
|
125
|
+
moolah.transactions.capture(auth_id, amount=1500) # partial
|
|
126
|
+
moolah.transactions.refund(txn_id, amount=500) # partial refund
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Webhooks
|
|
130
|
+
|
|
131
|
+
Endpoints and their signing secrets are managed in the Moolah Developer Portal
|
|
132
|
+
(there is no API for registering them). Verify every delivery against the **raw**
|
|
133
|
+
request body:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from flask import Flask, request
|
|
137
|
+
from moolah_poynt import verify_webhook, WebhookVerificationError
|
|
138
|
+
|
|
139
|
+
@app.post("/webhooks/moolah")
|
|
140
|
+
def moolah_webhook():
|
|
141
|
+
try:
|
|
142
|
+
event = verify_webhook(request.get_data(), request.headers, os.environ["MOOLAH_WEBHOOK_SECRET"])
|
|
143
|
+
except WebhookVerificationError:
|
|
144
|
+
return "", 400
|
|
145
|
+
enqueue(event) # respond within 15 s; de-duplicate on event.id
|
|
146
|
+
return "", 204
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The event is thin (no amounts or card data):
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
event.type # "transaction.captured" (also authorized, refunded, updated, declined, voided)
|
|
153
|
+
event.event_type # "TRANSACTION_CAPTURED", as sent
|
|
154
|
+
event.business_id # which business; one endpoint receives events for all of your businesses
|
|
155
|
+
event.resource_id # the transaction id: fetch it with the API key for that business
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Verification follows Standard Webhooks: HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`,
|
|
159
|
+
any `v1,` signature in `webhook-signature` may match (secret rotation), constant-time comparison,
|
|
160
|
+
and timestamps more than 5 minutes from your clock are rejected (`tolerance_seconds=` to change).
|
|
161
|
+
Headers may be any mapping (looked up case-insensitively) or a list of `(name, value)` pairs.
|
|
162
|
+
`client.webhooks.verify(...)` is the same function.
|
|
163
|
+
|
|
164
|
+
## Errors
|
|
165
|
+
|
|
166
|
+
| Exception | When |
|
|
167
|
+
|---|---|
|
|
168
|
+
| `MoolahApiError` | Non-2xx response. `status`, `code` (str, if the API sent one), `message`, `request_id`, `body`. |
|
|
169
|
+
| `TerminalNoResponseError` | Terminal payment outcome unknown. Adds `reference_id`. Subclass of `MoolahApiError`. |
|
|
170
|
+
| `MoolahConnectionError` | Network failure or timeout (`timed_out`). |
|
|
171
|
+
| `WebhookVerificationError` | Webhook failed verification. |
|
|
172
|
+
| `ValueError` / `TypeError` | Invalid arguments (e.g. a float `amount`), raised before any request. |
|
|
173
|
+
|
|
174
|
+
All SDK exceptions derive from `MoolahError`. Refund failures carry numeric API codes as strings:
|
|
175
|
+
`"101"` cash payment, `"102"` already voided, `"103"` partial refund of an unsettled transaction
|
|
176
|
+
(void it in full instead), `"104"` already refunded, `"105"` processor rejected.
|
|
177
|
+
|
|
178
|
+
`request_id` comes from the `X-Request-Id` (or `X-Poynt-Request-Id`) response header; include it
|
|
179
|
+
when contacting support.
|
|
180
|
+
|
|
181
|
+
## Retries
|
|
182
|
+
|
|
183
|
+
The client retries up to `max_retries` times (default 2) with exponential backoff, honouring
|
|
184
|
+
`Retry-After`, on `429`, `502`, `503`, `504` and network errors, but only for requests that are
|
|
185
|
+
safe to repeat:
|
|
186
|
+
|
|
187
|
+
- `GET` requests: always.
|
|
188
|
+
- Charge, authorize and refund calls: only when you pass `transaction_number`.
|
|
189
|
+
- Tokenize, capture and terminal payments: never.
|
|
190
|
+
|
|
191
|
+
`transaction_number` is your reference for the charge. The API does not document server-side
|
|
192
|
+
de-duplication on it, so a retried charge can, in rare cases, be processed twice: pass
|
|
193
|
+
`max_retries=0` if you would rather handle every failure yourself.
|
|
194
|
+
|
|
195
|
+
## Configuration
|
|
196
|
+
|
|
197
|
+
```python
|
|
198
|
+
MoolahClient(
|
|
199
|
+
api_key,
|
|
200
|
+
base_url="https://process.moolahpay.cc", # default
|
|
201
|
+
timeout=120.0, # seconds per socket operation; must exceed the 90 s terminal wait
|
|
202
|
+
max_retries=2,
|
|
203
|
+
user_agent="my-practice-app/1.4", # appended to the SDK's User-Agent
|
|
204
|
+
)
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Methods also accept `timeout=` and (where retries apply) `max_retries=`. Redirects are never
|
|
208
|
+
followed. Proxies are taken from the standard `HTTPS_PROXY`/`NO_PROXY` environment variables.
|
|
209
|
+
|
|
210
|
+
## Development
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
python -m unittest discover -s tests -t . # with PYTHONPATH=src, or after pip install -e .
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The tests run against a local fake HTTP server. `src/moolah_poynt/models_generated.py` is
|
|
217
|
+
generated from `../spec/openapi-public.json` by `../spec/tools/gen_models.py`; do not edit it.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "moolah-poynt"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Official Python client for the Moolah Poynt API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [{ name = "Moolah" }]
|
|
14
|
+
keywords = ["moolah", "poynt", "payments", "dental", "webhooks"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Programming Language :: Python :: 3.14",
|
|
24
|
+
"Programming Language :: Python :: 3.15",
|
|
25
|
+
"Topic :: Office/Business :: Financial",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
dependencies = []
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Documentation = "https://docs.moolahpay.cc"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.version]
|
|
34
|
+
path = "src/moolah_poynt/_version.py"
|
|
35
|
+
|
|
36
|
+
[tool.hatch.build.targets.wheel]
|
|
37
|
+
packages = ["src/moolah_poynt"]
|
|
38
|
+
|
|
39
|
+
[tool.hatch.build.targets.sdist]
|
|
40
|
+
include = ["src", "README.md", "LICENSE", "pyproject.toml"]
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Official Python client for the Moolah Poynt API."""
|
|
2
|
+
|
|
3
|
+
from ._client import MoolahClient
|
|
4
|
+
from ._http import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
|
|
5
|
+
from ._version import __version__
|
|
6
|
+
from .errors import (
|
|
7
|
+
TERMINAL_NO_RESPONSE,
|
|
8
|
+
MoolahApiError,
|
|
9
|
+
MoolahConnectionError,
|
|
10
|
+
MoolahError,
|
|
11
|
+
TerminalNoResponseError,
|
|
12
|
+
WebhookVerificationError,
|
|
13
|
+
)
|
|
14
|
+
from .types import CardOnFileIntent, FundingSourceType, ReconcileMatchedBy, ReconcileOutcome
|
|
15
|
+
from .webhooks import (
|
|
16
|
+
DEFAULT_TOLERANCE_SECONDS,
|
|
17
|
+
WebhookEvent,
|
|
18
|
+
WebhookEventType,
|
|
19
|
+
portal_event_type,
|
|
20
|
+
verify_webhook,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
__all__ = [
|
|
24
|
+
"MoolahClient",
|
|
25
|
+
"DEFAULT_BASE_URL",
|
|
26
|
+
"DEFAULT_MAX_RETRIES",
|
|
27
|
+
"DEFAULT_TIMEOUT",
|
|
28
|
+
"DEFAULT_TOLERANCE_SECONDS",
|
|
29
|
+
"TERMINAL_NO_RESPONSE",
|
|
30
|
+
"MoolahError",
|
|
31
|
+
"MoolahApiError",
|
|
32
|
+
"MoolahConnectionError",
|
|
33
|
+
"TerminalNoResponseError",
|
|
34
|
+
"WebhookVerificationError",
|
|
35
|
+
"CardOnFileIntent",
|
|
36
|
+
"FundingSourceType",
|
|
37
|
+
"ReconcileOutcome",
|
|
38
|
+
"ReconcileMatchedBy",
|
|
39
|
+
"WebhookEvent",
|
|
40
|
+
"WebhookEventType",
|
|
41
|
+
"portal_event_type",
|
|
42
|
+
"verify_webhook",
|
|
43
|
+
"__version__",
|
|
44
|
+
]
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
from ._http import HttpCore
|
|
6
|
+
from .resources import Business, Devices, Payments, Tokens, Transactions
|
|
7
|
+
from .webhooks import Webhooks
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class MoolahClient:
|
|
11
|
+
"""Client for the Moolah Poynt API.
|
|
12
|
+
|
|
13
|
+
>>> moolah = MoolahClient(os.environ["MOOLAH_API_KEY"])
|
|
14
|
+
>>> txn = moolah.tokens.charge(amount=2500, payment_token=token, funding_source_type="CARD")
|
|
15
|
+
|
|
16
|
+
:param api_key: your Moolah API key (sent as a Bearer token).
|
|
17
|
+
:param base_url: defaults to ``https://process.moolahpay.cc``.
|
|
18
|
+
:param timeout: seconds per attempt (socket-level), default 120; must exceed the 90 s terminal wait.
|
|
19
|
+
:param max_retries: retries for retry-eligible requests, default 2.
|
|
20
|
+
:param user_agent: appended to the SDK's User-Agent.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __init__(
|
|
24
|
+
self,
|
|
25
|
+
api_key: str,
|
|
26
|
+
*,
|
|
27
|
+
base_url: Optional[str] = None,
|
|
28
|
+
timeout: Optional[float] = None,
|
|
29
|
+
max_retries: Optional[int] = None,
|
|
30
|
+
user_agent: Optional[str] = None,
|
|
31
|
+
) -> None:
|
|
32
|
+
self._core = HttpCore(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries, user_agent=user_agent)
|
|
33
|
+
self.tokens = Tokens(self._core)
|
|
34
|
+
self.transactions = Transactions(self._core)
|
|
35
|
+
self.payments = Payments(self._core)
|
|
36
|
+
self.devices = Devices(self._core)
|
|
37
|
+
self.business = Business(self._core)
|
|
38
|
+
self.webhooks = Webhooks()
|
|
39
|
+
|
|
40
|
+
@property
|
|
41
|
+
def base_url(self) -> str:
|
|
42
|
+
return self._core.base_url
|