orboni 1.0.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.
- orboni-1.0.0/.gitignore +5 -0
- orboni-1.0.0/CHANGELOG.md +5 -0
- orboni-1.0.0/LICENSE +21 -0
- orboni-1.0.0/PKG-INFO +230 -0
- orboni-1.0.0/README.md +203 -0
- orboni-1.0.0/pyproject.toml +45 -0
- orboni-1.0.0/src/orboni/__init__.py +50 -0
- orboni-1.0.0/src/orboni/_client.py +282 -0
- orboni-1.0.0/src/orboni/_errors.py +177 -0
- orboni-1.0.0/src/orboni/_object.py +122 -0
- orboni-1.0.0/src/orboni/_resources.py +294 -0
- orboni-1.0.0/src/orboni/_version.py +1 -0
- orboni-1.0.0/src/orboni/_webhooks.py +128 -0
- orboni-1.0.0/src/orboni/py.typed +0 -0
- orboni-1.0.0/tests/fixtures/webhooks.json +142 -0
- orboni-1.0.0/tests/test_client.py +586 -0
- orboni-1.0.0/tests/test_webhooks.py +124 -0
orboni-1.0.0/.gitignore
ADDED
orboni-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Orboni
|
|
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.
|
orboni-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: orboni
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Orboni's API for Python: crypto payments (USDT, USDC, BTC and more) paid straight to your own wallets.
|
|
5
|
+
Project-URL: Homepage, https://orboni.com/docs/libraries
|
|
6
|
+
Project-URL: Source, https://github.com/orboni/orboni-python
|
|
7
|
+
Author-email: Orboni <support@orboni.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: bitcoin,checkout,crypto,orboni,payment-gateway,payments,usdc,usdt,webhooks
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.9
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# Orboni for Python
|
|
29
|
+
|
|
30
|
+
The official Python library for the [Orboni API](https://orboni.com/docs): take crypto payments — USDT, USDC, BTC, ETH and more — paid straight to your own wallets. Orboni never holds your money.
|
|
31
|
+
|
|
32
|
+
- Every API call: checkout sessions, payment links, refunds, events, payment methods and currencies.
|
|
33
|
+
- Webhook signatures verified with the standard library's `hmac`, in constant time.
|
|
34
|
+
- Safe retries: each POST carries an idempotency key, and network failures, timeouts, `409`, `429` and `5xx` are tried again.
|
|
35
|
+
- No dependencies: the standard library only. Python 3.9 or later, with type hints (`py.typed`).
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install orboni
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Take a payment
|
|
44
|
+
|
|
45
|
+
Make a checkout session on your server and send the buyer to its `url`. Amounts are in the currency's smallest unit (cents, or whole yen).
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import os
|
|
49
|
+
|
|
50
|
+
import orboni
|
|
51
|
+
|
|
52
|
+
client = orboni.Orboni(os.environ["ORBONI_SECRET_KEY"]) # sk_test_… or sk_live_…
|
|
53
|
+
|
|
54
|
+
session = client.checkout.sessions.create(
|
|
55
|
+
amount=2500,
|
|
56
|
+
currency="usd",
|
|
57
|
+
client_reference_id="order_1042",
|
|
58
|
+
success_url="https://your-store.example/orders/1042",
|
|
59
|
+
cancel_url="https://your-store.example/cart",
|
|
60
|
+
metadata={"order_id": "1042"},
|
|
61
|
+
idempotency_key="order_1042",
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
# redirect the buyer to session.url
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The buyer picks a coin on Orboni's payment page and pays from any wallet or exchange. Fulfil the order when the `checkout.session.completed` webhook arrives, or read the session back:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
paid = client.checkout.sessions.retrieve(session.id)
|
|
71
|
+
if paid.status == "complete" and paid.payment_status == "paid":
|
|
72
|
+
... # fulfil order 1042
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The API's parameters are keyword arguments with the API's own names. `idempotency_key`, `timeout` and `max_retries` are the library's options for that call and are never sent as parameters.
|
|
76
|
+
|
|
77
|
+
## Answers
|
|
78
|
+
|
|
79
|
+
Every answer is an `orboni.OrboniObject`: a `dict` whose fields also read as attributes, nested objects included. `session["url"]` and `session.url` are the same; a missing field raises `KeyError` with brackets and `AttributeError` as an attribute. JSON arrays stay lists, and `json.dumps(session)` works as for any dict. A field named after a Python keyword reads with brackets only: a transaction's `transaction["from"]`.
|
|
80
|
+
|
|
81
|
+
## Webhooks
|
|
82
|
+
|
|
83
|
+
Orboni signs every webhook with your endpoint's signing secret (`whsec_…`, under Developers → Webhooks in the dashboard). Verify it against the **raw** body, before any JSON parser touches it.
|
|
84
|
+
|
|
85
|
+
Flask:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import os
|
|
89
|
+
|
|
90
|
+
import orboni
|
|
91
|
+
from flask import Flask, request
|
|
92
|
+
|
|
93
|
+
app = Flask(__name__)
|
|
94
|
+
|
|
95
|
+
@app.post("/webhooks/orboni")
|
|
96
|
+
def orboni_webhook():
|
|
97
|
+
try:
|
|
98
|
+
event = orboni.Webhook.construct_event(
|
|
99
|
+
request.get_data(),
|
|
100
|
+
request.headers.get("Webhook-Signature"),
|
|
101
|
+
os.environ["ORBONI_WEBHOOK_SECRET"],
|
|
102
|
+
)
|
|
103
|
+
except orboni.SignatureVerificationError as error:
|
|
104
|
+
return str(error), 400
|
|
105
|
+
|
|
106
|
+
if event.type == "checkout.session.completed":
|
|
107
|
+
session = event.data.object # fulfil session.client_reference_id once
|
|
108
|
+
return "", 200
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Django:
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
import os
|
|
115
|
+
|
|
116
|
+
import orboni
|
|
117
|
+
from django.http import HttpResponse, HttpResponseBadRequest
|
|
118
|
+
from django.views.decorators.csrf import csrf_exempt
|
|
119
|
+
from django.views.decorators.http import require_POST
|
|
120
|
+
|
|
121
|
+
@csrf_exempt
|
|
122
|
+
@require_POST
|
|
123
|
+
def orboni_webhook(request):
|
|
124
|
+
try:
|
|
125
|
+
event = orboni.Webhook.construct_event(
|
|
126
|
+
request.body,
|
|
127
|
+
request.headers.get("Webhook-Signature"),
|
|
128
|
+
os.environ["ORBONI_WEBHOOK_SECRET"],
|
|
129
|
+
)
|
|
130
|
+
except orboni.SignatureVerificationError as error:
|
|
131
|
+
return HttpResponseBadRequest(str(error))
|
|
132
|
+
|
|
133
|
+
if event.type == "checkout.session.completed":
|
|
134
|
+
session = event.data.object # fulfil session.client_reference_id once
|
|
135
|
+
return HttpResponse(status=200)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
In FastAPI or Starlette, pass `await request.body()` and `request.headers.get("webhook-signature")`.
|
|
139
|
+
|
|
140
|
+
The same event can arrive more than once and out of order: keep the `id`s you have handled. In production, ignore events whose `livemode` is `False`. While you roll a signing secret, pass both: `construct_event(body, header, [new_secret, old_secret])`. Verifying needs no API key: `orboni.Webhook.construct_event(…)` is a static method, and `client.webhooks.construct_event(…)` is the same. `Webhook.verify_signature(…)` checks the signature only and returns `True`. The signature's time may be at most 300 seconds from now, either way; the fourth argument changes that.
|
|
141
|
+
|
|
142
|
+
## Lists
|
|
143
|
+
|
|
144
|
+
A list call answers one page, an `orboni.ListObject`. `auto_paging_iter()` walks every object across the pages, asking for each next page as it goes:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
page = client.checkout.sessions.list(limit=10, status="complete")
|
|
148
|
+
print(page.data, page.has_more)
|
|
149
|
+
|
|
150
|
+
for refund in client.refunds.list(checkout_session="cs_live_…").auto_paging_iter():
|
|
151
|
+
print(refund.id, refund.amount)
|
|
152
|
+
|
|
153
|
+
recent = client.events.list(created={"gte": 1767225600}).auto_paging_to_list(limit=500)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
A list asked with `ending_before` is walked backwards, each page's objects oldest first. Payment methods and currencies are one page, never paged.
|
|
157
|
+
|
|
158
|
+
## Everything else
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
client.checkout.sessions.expire("cs_live_…") # an order cancelled on your side
|
|
162
|
+
|
|
163
|
+
link = client.payment_links.create(amount=1500, currency="eur", description="Workshop ticket")
|
|
164
|
+
client.payment_links.update(link.id, active=False)
|
|
165
|
+
|
|
166
|
+
# Orboni holds no money: send the refund from your wallet, then record it
|
|
167
|
+
client.refunds.create(checkout_session="cs_live_…", amount=1000, reason="requested_by_customer", transaction="0x…")
|
|
168
|
+
|
|
169
|
+
client.events.resend("evt_…")
|
|
170
|
+
methods = client.payment_methods.list(amount=2500, currency="usd")
|
|
171
|
+
currencies = client.currencies.list()
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The parameters and fields of each call are in the [API reference](https://orboni.com/docs).
|
|
175
|
+
|
|
176
|
+
## Errors
|
|
177
|
+
|
|
178
|
+
A refused call raises an `orboni.OrboniError` subclass named after the API's error `type`. Branch on the class or on `type`, never on the message:
|
|
179
|
+
|
|
180
|
+
| Class | `type` | When |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| `InvalidRequestError` | `invalid_request_error` | A bad parameter (`param` names it), or no such object (`http_status` 404) |
|
|
183
|
+
| `AmountTooSmallError` | `amount_too_small` | Under the minimum of every network the session could be paid on |
|
|
184
|
+
| `IdempotencyError` | `idempotency_error` | An idempotency key reused with other parameters |
|
|
185
|
+
| `AuthenticationError` | `authentication_error` | No key, a wrong one or a revoked one |
|
|
186
|
+
| `PermissionError` | `permission_error` | A suspended or closed account, or a live key before the email is confirmed |
|
|
187
|
+
| `ReceivingFrozenError` | `receiving_frozen` | Receiving is frozen: live keys only read |
|
|
188
|
+
| `AccountPastDueError` | `account_past_due` | An Orboni invoice is past due (live only) |
|
|
189
|
+
| `RateLimitError` | `rate_limit_error` | Too many requests; `retry_after` says how many seconds to wait |
|
|
190
|
+
| `RateUnavailableError` | `rate_unavailable` | No current exchange rate for the currency |
|
|
191
|
+
| `APIError` | `api_error` | Orboni's side; safe to retry with the same idempotency key |
|
|
192
|
+
| `APIConnectionError` | `connection_error` | No answer: the network failed or the call timed out |
|
|
193
|
+
|
|
194
|
+
Each has `type`, `message`, `param`, `http_status`, `headers` (lower-cased names) and `error` (the error object as the API sent it). `PermissionError` is `orboni.PermissionError`, not Python's built-in one: refer to it through the package, as below. `from orboni import *` leaves it out so it never hides the built-in.
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
import orboni
|
|
198
|
+
|
|
199
|
+
try:
|
|
200
|
+
client.checkout.sessions.create(amount=50, currency="usd")
|
|
201
|
+
except orboni.AmountTooSmallError:
|
|
202
|
+
... # offer another way to pay
|
|
203
|
+
except orboni.InvalidRequestError as error:
|
|
204
|
+
print(error.param, error.message)
|
|
205
|
+
except orboni.PermissionError:
|
|
206
|
+
... # the account cannot take payments now
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Configuration
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
client = orboni.Orboni(
|
|
213
|
+
os.environ["ORBONI_SECRET_KEY"],
|
|
214
|
+
timeout=30.0, # seconds a try may wait to connect, and then for each part of the answer
|
|
215
|
+
max_retries=2, # after the first try
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
# per call
|
|
219
|
+
client.checkout.sessions.retrieve("cs_live_…", timeout=5.0, max_retries=0)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Without `idempotency_key` the library makes one for each POST, so its own retries never create a second session or refund. Pass your own (an order ID is a good one) to make retries of your own safe too: Orboni keeps a successful answer for 24 hours and gives it again for the same key.
|
|
223
|
+
|
|
224
|
+
## Test mode
|
|
225
|
+
|
|
226
|
+
A test key (`sk_test_…`) makes test sessions that take no real money. Open a test session's payment page while signed in to the dashboard and press **Simulate payment** to see the whole flow, webhooks included. `client.test_mode` says which kind of key a client has. See [Testing](https://orboni.com/docs/testing).
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT
|
orboni-1.0.0/README.md
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# Orboni for Python
|
|
2
|
+
|
|
3
|
+
The official Python library for the [Orboni API](https://orboni.com/docs): take crypto payments — USDT, USDC, BTC, ETH and more — paid straight to your own wallets. Orboni never holds your money.
|
|
4
|
+
|
|
5
|
+
- Every API call: checkout sessions, payment links, refunds, events, payment methods and currencies.
|
|
6
|
+
- Webhook signatures verified with the standard library's `hmac`, in constant time.
|
|
7
|
+
- Safe retries: each POST carries an idempotency key, and network failures, timeouts, `409`, `429` and `5xx` are tried again.
|
|
8
|
+
- No dependencies: the standard library only. Python 3.9 or later, with type hints (`py.typed`).
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install orboni
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Take a payment
|
|
17
|
+
|
|
18
|
+
Make a checkout session on your server and send the buyer to its `url`. Amounts are in the currency's smallest unit (cents, or whole yen).
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
import os
|
|
22
|
+
|
|
23
|
+
import orboni
|
|
24
|
+
|
|
25
|
+
client = orboni.Orboni(os.environ["ORBONI_SECRET_KEY"]) # sk_test_… or sk_live_…
|
|
26
|
+
|
|
27
|
+
session = client.checkout.sessions.create(
|
|
28
|
+
amount=2500,
|
|
29
|
+
currency="usd",
|
|
30
|
+
client_reference_id="order_1042",
|
|
31
|
+
success_url="https://your-store.example/orders/1042",
|
|
32
|
+
cancel_url="https://your-store.example/cart",
|
|
33
|
+
metadata={"order_id": "1042"},
|
|
34
|
+
idempotency_key="order_1042",
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
# redirect the buyer to session.url
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The buyer picks a coin on Orboni's payment page and pays from any wallet or exchange. Fulfil the order when the `checkout.session.completed` webhook arrives, or read the session back:
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
paid = client.checkout.sessions.retrieve(session.id)
|
|
44
|
+
if paid.status == "complete" and paid.payment_status == "paid":
|
|
45
|
+
... # fulfil order 1042
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The API's parameters are keyword arguments with the API's own names. `idempotency_key`, `timeout` and `max_retries` are the library's options for that call and are never sent as parameters.
|
|
49
|
+
|
|
50
|
+
## Answers
|
|
51
|
+
|
|
52
|
+
Every answer is an `orboni.OrboniObject`: a `dict` whose fields also read as attributes, nested objects included. `session["url"]` and `session.url` are the same; a missing field raises `KeyError` with brackets and `AttributeError` as an attribute. JSON arrays stay lists, and `json.dumps(session)` works as for any dict. A field named after a Python keyword reads with brackets only: a transaction's `transaction["from"]`.
|
|
53
|
+
|
|
54
|
+
## Webhooks
|
|
55
|
+
|
|
56
|
+
Orboni signs every webhook with your endpoint's signing secret (`whsec_…`, under Developers → Webhooks in the dashboard). Verify it against the **raw** body, before any JSON parser touches it.
|
|
57
|
+
|
|
58
|
+
Flask:
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
import os
|
|
62
|
+
|
|
63
|
+
import orboni
|
|
64
|
+
from flask import Flask, request
|
|
65
|
+
|
|
66
|
+
app = Flask(__name__)
|
|
67
|
+
|
|
68
|
+
@app.post("/webhooks/orboni")
|
|
69
|
+
def orboni_webhook():
|
|
70
|
+
try:
|
|
71
|
+
event = orboni.Webhook.construct_event(
|
|
72
|
+
request.get_data(),
|
|
73
|
+
request.headers.get("Webhook-Signature"),
|
|
74
|
+
os.environ["ORBONI_WEBHOOK_SECRET"],
|
|
75
|
+
)
|
|
76
|
+
except orboni.SignatureVerificationError as error:
|
|
77
|
+
return str(error), 400
|
|
78
|
+
|
|
79
|
+
if event.type == "checkout.session.completed":
|
|
80
|
+
session = event.data.object # fulfil session.client_reference_id once
|
|
81
|
+
return "", 200
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Django:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import os
|
|
88
|
+
|
|
89
|
+
import orboni
|
|
90
|
+
from django.http import HttpResponse, HttpResponseBadRequest
|
|
91
|
+
from django.views.decorators.csrf import csrf_exempt
|
|
92
|
+
from django.views.decorators.http import require_POST
|
|
93
|
+
|
|
94
|
+
@csrf_exempt
|
|
95
|
+
@require_POST
|
|
96
|
+
def orboni_webhook(request):
|
|
97
|
+
try:
|
|
98
|
+
event = orboni.Webhook.construct_event(
|
|
99
|
+
request.body,
|
|
100
|
+
request.headers.get("Webhook-Signature"),
|
|
101
|
+
os.environ["ORBONI_WEBHOOK_SECRET"],
|
|
102
|
+
)
|
|
103
|
+
except orboni.SignatureVerificationError as error:
|
|
104
|
+
return HttpResponseBadRequest(str(error))
|
|
105
|
+
|
|
106
|
+
if event.type == "checkout.session.completed":
|
|
107
|
+
session = event.data.object # fulfil session.client_reference_id once
|
|
108
|
+
return HttpResponse(status=200)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
In FastAPI or Starlette, pass `await request.body()` and `request.headers.get("webhook-signature")`.
|
|
112
|
+
|
|
113
|
+
The same event can arrive more than once and out of order: keep the `id`s you have handled. In production, ignore events whose `livemode` is `False`. While you roll a signing secret, pass both: `construct_event(body, header, [new_secret, old_secret])`. Verifying needs no API key: `orboni.Webhook.construct_event(…)` is a static method, and `client.webhooks.construct_event(…)` is the same. `Webhook.verify_signature(…)` checks the signature only and returns `True`. The signature's time may be at most 300 seconds from now, either way; the fourth argument changes that.
|
|
114
|
+
|
|
115
|
+
## Lists
|
|
116
|
+
|
|
117
|
+
A list call answers one page, an `orboni.ListObject`. `auto_paging_iter()` walks every object across the pages, asking for each next page as it goes:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
page = client.checkout.sessions.list(limit=10, status="complete")
|
|
121
|
+
print(page.data, page.has_more)
|
|
122
|
+
|
|
123
|
+
for refund in client.refunds.list(checkout_session="cs_live_…").auto_paging_iter():
|
|
124
|
+
print(refund.id, refund.amount)
|
|
125
|
+
|
|
126
|
+
recent = client.events.list(created={"gte": 1767225600}).auto_paging_to_list(limit=500)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A list asked with `ending_before` is walked backwards, each page's objects oldest first. Payment methods and currencies are one page, never paged.
|
|
130
|
+
|
|
131
|
+
## Everything else
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
client.checkout.sessions.expire("cs_live_…") # an order cancelled on your side
|
|
135
|
+
|
|
136
|
+
link = client.payment_links.create(amount=1500, currency="eur", description="Workshop ticket")
|
|
137
|
+
client.payment_links.update(link.id, active=False)
|
|
138
|
+
|
|
139
|
+
# Orboni holds no money: send the refund from your wallet, then record it
|
|
140
|
+
client.refunds.create(checkout_session="cs_live_…", amount=1000, reason="requested_by_customer", transaction="0x…")
|
|
141
|
+
|
|
142
|
+
client.events.resend("evt_…")
|
|
143
|
+
methods = client.payment_methods.list(amount=2500, currency="usd")
|
|
144
|
+
currencies = client.currencies.list()
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The parameters and fields of each call are in the [API reference](https://orboni.com/docs).
|
|
148
|
+
|
|
149
|
+
## Errors
|
|
150
|
+
|
|
151
|
+
A refused call raises an `orboni.OrboniError` subclass named after the API's error `type`. Branch on the class or on `type`, never on the message:
|
|
152
|
+
|
|
153
|
+
| Class | `type` | When |
|
|
154
|
+
| --- | --- | --- |
|
|
155
|
+
| `InvalidRequestError` | `invalid_request_error` | A bad parameter (`param` names it), or no such object (`http_status` 404) |
|
|
156
|
+
| `AmountTooSmallError` | `amount_too_small` | Under the minimum of every network the session could be paid on |
|
|
157
|
+
| `IdempotencyError` | `idempotency_error` | An idempotency key reused with other parameters |
|
|
158
|
+
| `AuthenticationError` | `authentication_error` | No key, a wrong one or a revoked one |
|
|
159
|
+
| `PermissionError` | `permission_error` | A suspended or closed account, or a live key before the email is confirmed |
|
|
160
|
+
| `ReceivingFrozenError` | `receiving_frozen` | Receiving is frozen: live keys only read |
|
|
161
|
+
| `AccountPastDueError` | `account_past_due` | An Orboni invoice is past due (live only) |
|
|
162
|
+
| `RateLimitError` | `rate_limit_error` | Too many requests; `retry_after` says how many seconds to wait |
|
|
163
|
+
| `RateUnavailableError` | `rate_unavailable` | No current exchange rate for the currency |
|
|
164
|
+
| `APIError` | `api_error` | Orboni's side; safe to retry with the same idempotency key |
|
|
165
|
+
| `APIConnectionError` | `connection_error` | No answer: the network failed or the call timed out |
|
|
166
|
+
|
|
167
|
+
Each has `type`, `message`, `param`, `http_status`, `headers` (lower-cased names) and `error` (the error object as the API sent it). `PermissionError` is `orboni.PermissionError`, not Python's built-in one: refer to it through the package, as below. `from orboni import *` leaves it out so it never hides the built-in.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
import orboni
|
|
171
|
+
|
|
172
|
+
try:
|
|
173
|
+
client.checkout.sessions.create(amount=50, currency="usd")
|
|
174
|
+
except orboni.AmountTooSmallError:
|
|
175
|
+
... # offer another way to pay
|
|
176
|
+
except orboni.InvalidRequestError as error:
|
|
177
|
+
print(error.param, error.message)
|
|
178
|
+
except orboni.PermissionError:
|
|
179
|
+
... # the account cannot take payments now
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Configuration
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
client = orboni.Orboni(
|
|
186
|
+
os.environ["ORBONI_SECRET_KEY"],
|
|
187
|
+
timeout=30.0, # seconds a try may wait to connect, and then for each part of the answer
|
|
188
|
+
max_retries=2, # after the first try
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
# per call
|
|
192
|
+
client.checkout.sessions.retrieve("cs_live_…", timeout=5.0, max_retries=0)
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Without `idempotency_key` the library makes one for each POST, so its own retries never create a second session or refund. Pass your own (an order ID is a good one) to make retries of your own safe too: Orboni keeps a successful answer for 24 hours and gives it again for the same key.
|
|
196
|
+
|
|
197
|
+
## Test mode
|
|
198
|
+
|
|
199
|
+
A test key (`sk_test_…`) makes test sessions that take no real money. Open a test session's payment page while signed in to the dashboard and press **Simulate payment** to see the whole flow, webhooks included. `client.test_mode` says which kind of key a client has. See [Testing](https://orboni.com/docs/testing).
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
MIT
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "orboni"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Orboni's API for Python: crypto payments (USDT, USDC, BTC and more) paid straight to your own wallets."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Orboni", email = "support@orboni.com" }]
|
|
14
|
+
keywords = ["orboni", "crypto", "payments", "usdt", "usdc", "bitcoin", "checkout", "payment-gateway", "webhooks"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 5 - Production/Stable",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.9",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Programming Language :: Python :: 3.14",
|
|
27
|
+
"Topic :: Office/Business :: Financial",
|
|
28
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
29
|
+
"Typing :: Typed",
|
|
30
|
+
]
|
|
31
|
+
dependencies = []
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://orboni.com/docs/libraries"
|
|
35
|
+
Source = "https://github.com/orboni/orboni-python"
|
|
36
|
+
|
|
37
|
+
[tool.hatch.version]
|
|
38
|
+
path = "src/orboni/_version.py"
|
|
39
|
+
|
|
40
|
+
[tool.hatch.build.targets.wheel]
|
|
41
|
+
packages = ["src/orboni"]
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.sdist]
|
|
44
|
+
include = ["src/orboni", "tests", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
|
|
45
|
+
exclude = ["__pycache__"]
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Orboni's API for Python: crypto payments paid straight to your own wallets.
|
|
2
|
+
|
|
3
|
+
import orboni
|
|
4
|
+
|
|
5
|
+
client = orboni.Orboni(os.environ["ORBONI_SECRET_KEY"])
|
|
6
|
+
session = client.checkout.sessions.create(amount=2500, currency="usd")
|
|
7
|
+
|
|
8
|
+
See https://orboni.com/docs/libraries.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from ._client import Orboni
|
|
12
|
+
from ._errors import (
|
|
13
|
+
AccountPastDueError,
|
|
14
|
+
AmountTooSmallError,
|
|
15
|
+
APIConnectionError,
|
|
16
|
+
APIError,
|
|
17
|
+
AuthenticationError,
|
|
18
|
+
IdempotencyError,
|
|
19
|
+
InvalidRequestError,
|
|
20
|
+
OrboniError,
|
|
21
|
+
RateLimitError,
|
|
22
|
+
RateUnavailableError,
|
|
23
|
+
ReceivingFrozenError,
|
|
24
|
+
SignatureVerificationError,
|
|
25
|
+
)
|
|
26
|
+
from ._errors import PermissionError as PermissionError # orboni.PermissionError; not in __all__
|
|
27
|
+
from ._object import ListObject, OrboniObject
|
|
28
|
+
from ._version import __version__ as __version__
|
|
29
|
+
from ._webhooks import Webhook
|
|
30
|
+
|
|
31
|
+
# PermissionError is left out on purpose: `from orboni import *` must never
|
|
32
|
+
# hide Python's built-in PermissionError. Use orboni.PermissionError.
|
|
33
|
+
__all__ = [
|
|
34
|
+
"Orboni",
|
|
35
|
+
"OrboniObject",
|
|
36
|
+
"ListObject",
|
|
37
|
+
"Webhook",
|
|
38
|
+
"OrboniError",
|
|
39
|
+
"InvalidRequestError",
|
|
40
|
+
"IdempotencyError",
|
|
41
|
+
"AuthenticationError",
|
|
42
|
+
"ReceivingFrozenError",
|
|
43
|
+
"AccountPastDueError",
|
|
44
|
+
"AmountTooSmallError",
|
|
45
|
+
"RateLimitError",
|
|
46
|
+
"RateUnavailableError",
|
|
47
|
+
"APIError",
|
|
48
|
+
"APIConnectionError",
|
|
49
|
+
"SignatureVerificationError",
|
|
50
|
+
]
|