paga-python 0.1.0__py3-none-any.whl
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.
- paga/__init__.py +206 -0
- paga/actions.py +246 -0
- paga/auth.py +509 -0
- paga/business.py +858 -0
- paga/checkout.py +228 -0
- paga/client.py +346 -0
- paga/codes.py +197 -0
- paga/customer.py +287 -0
- paga/direct_debit.py +356 -0
- paga/directory.py +523 -0
- paga/exceptions.py +86 -0
- paga/models.py +1001 -0
- paga/outcome.py +122 -0
- paga/persistent.py +212 -0
- paga/webhooks.py +405 -0
- paga_python-0.1.0.dist-info/METADATA +424 -0
- paga_python-0.1.0.dist-info/RECORD +19 -0
- paga_python-0.1.0.dist-info/WHEEL +4 -0
- paga_python-0.1.0.dist-info/licenses/LICENSE +674 -0
paga/business.py
ADDED
|
@@ -0,0 +1,858 @@
|
|
|
1
|
+
"""Business and subsidiary account operations for the Paga Engine API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any, Dict, Optional
|
|
6
|
+
|
|
7
|
+
from .auth import (
|
|
8
|
+
ACCOUNT_BALANCE_HASH_FIELDS,
|
|
9
|
+
DISPENSE_CASH_HASH_FIELDS,
|
|
10
|
+
GET_OPERATION_STATUS_HASH_FIELDS,
|
|
11
|
+
MONEY_TRANSFER_BULK_HASH_FIELDS,
|
|
12
|
+
ONBOARD_MERCHANT_HASH_FIELDS,
|
|
13
|
+
PAGA_WALLET_TRANSFER_HASH_FIELDS,
|
|
14
|
+
SUBSIDIARY_ACCOUNT_HASH_FIELDS,
|
|
15
|
+
SUBSIDIARY_BALANCE_HASH_FIELDS,
|
|
16
|
+
SUBSIDIARY_CHARGE_HASH_FIELDS,
|
|
17
|
+
SUBSIDIARY_HISTORY_HASH_FIELDS,
|
|
18
|
+
SUBSIDIARY_RETRIEVE_HASH_FIELDS,
|
|
19
|
+
SUBSIDIARY_TOPUP_HASH_FIELDS,
|
|
20
|
+
SUBSIDIARY_TRANSFER_HASH_FIELDS,
|
|
21
|
+
SUBSIDIARY_UPDATE_HASH_FIELDS,
|
|
22
|
+
TRANSACTION_HISTORY_HASH_FIELDS,
|
|
23
|
+
VALIDATE_MONEY_TRANSFER_HASH_FIELDS,
|
|
24
|
+
)
|
|
25
|
+
from .models import (
|
|
26
|
+
AccountBalanceResponse,
|
|
27
|
+
BulkMoneyTransferResponse,
|
|
28
|
+
DispenseCashResponse,
|
|
29
|
+
MoneyTransferResponse,
|
|
30
|
+
OnboardMerchantResponse,
|
|
31
|
+
OperationStatusResponse,
|
|
32
|
+
PagaResponse,
|
|
33
|
+
SubsidiaryAccountResponse,
|
|
34
|
+
SubsidiaryBalanceResponse,
|
|
35
|
+
SubsidiaryHistoryResponse,
|
|
36
|
+
SubsidiaryMoneyResponse,
|
|
37
|
+
SubsidiaryTransferResponse,
|
|
38
|
+
TransactionHistoryResponse,
|
|
39
|
+
ValidateMoneyTransferResponse,
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class BusinessMixin:
|
|
44
|
+
"""Business account operations and subsidiary account management."""
|
|
45
|
+
|
|
46
|
+
async def get_business_balance(self, *, reference_number: str) -> AccountBalanceResponse:
|
|
47
|
+
"""Check the business account balance.
|
|
48
|
+
|
|
49
|
+
Operation: Your business account - Check your balance.
|
|
50
|
+
|
|
51
|
+
Returns the business account balance. Check ``availableBalance``, not
|
|
52
|
+
``totalBalance``, before a payout run: it is what you can actually send.
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
reference_number: Your unique balance check reference.
|
|
56
|
+
|
|
57
|
+
Returns:
|
|
58
|
+
The parsed :class:`AccountBalanceResponse`.
|
|
59
|
+
"""
|
|
60
|
+
response = await self._request(
|
|
61
|
+
"POST",
|
|
62
|
+
"/accountBalance",
|
|
63
|
+
{"referenceNumber": reference_number},
|
|
64
|
+
use_hash=True,
|
|
65
|
+
use_basic=False,
|
|
66
|
+
base_url=self.business_base_url,
|
|
67
|
+
hash_fields=ACCOUNT_BALANCE_HASH_FIELDS,
|
|
68
|
+
raise_on_error=False,
|
|
69
|
+
)
|
|
70
|
+
return AccountBalanceResponse.model_validate(response.model_dump())
|
|
71
|
+
|
|
72
|
+
async def get_business_transactions(
|
|
73
|
+
self,
|
|
74
|
+
*,
|
|
75
|
+
reference_number: str,
|
|
76
|
+
start_date_utc: str,
|
|
77
|
+
end_date_utc: str,
|
|
78
|
+
locale: Optional[str] = None,
|
|
79
|
+
) -> TransactionHistoryResponse:
|
|
80
|
+
"""Get the business transaction history.
|
|
81
|
+
|
|
82
|
+
Operation: Your business account - Get your transaction history.
|
|
83
|
+
|
|
84
|
+
Returns every transaction on the business account between two dates:
|
|
85
|
+
money in, money out and fees, up to 10,000 at a time.
|
|
86
|
+
|
|
87
|
+
Args:
|
|
88
|
+
reference_number: Your unique history reference.
|
|
89
|
+
start_date_utc: Start of the range, in UTC.
|
|
90
|
+
end_date_utc: End of the range, in UTC.
|
|
91
|
+
locale: Optional IETF language tag.
|
|
92
|
+
|
|
93
|
+
Returns:
|
|
94
|
+
The parsed :class:`TransactionHistoryResponse`.
|
|
95
|
+
"""
|
|
96
|
+
payload: Dict[str, Any] = {
|
|
97
|
+
"referenceNumber": reference_number,
|
|
98
|
+
"startDateUTC": start_date_utc,
|
|
99
|
+
"endDateUTC": end_date_utc,
|
|
100
|
+
}
|
|
101
|
+
if locale is not None:
|
|
102
|
+
payload["locale"] = locale
|
|
103
|
+
response = await self._request(
|
|
104
|
+
"POST",
|
|
105
|
+
"/transactionHistory",
|
|
106
|
+
payload,
|
|
107
|
+
use_hash=True,
|
|
108
|
+
use_basic=False,
|
|
109
|
+
base_url=self.business_base_url,
|
|
110
|
+
hash_fields=TRANSACTION_HISTORY_HASH_FIELDS,
|
|
111
|
+
)
|
|
112
|
+
return TransactionHistoryResponse.model_validate(response.model_dump())
|
|
113
|
+
|
|
114
|
+
async def create_subsidiary_account(
|
|
115
|
+
self,
|
|
116
|
+
*,
|
|
117
|
+
reference_number: str,
|
|
118
|
+
account_reference: str,
|
|
119
|
+
account_name: str,
|
|
120
|
+
first_name: Optional[str] = None,
|
|
121
|
+
last_name: Optional[str] = None,
|
|
122
|
+
phone_number: Optional[str] = None,
|
|
123
|
+
email: Optional[str] = None,
|
|
124
|
+
iifi_number: Optional[str] = None,
|
|
125
|
+
funding_transaction_limit: Optional[float] = None,
|
|
126
|
+
funding_daily_limit: Optional[float] = None,
|
|
127
|
+
status: Optional[str] = None,
|
|
128
|
+
auto_sweep_destination: Optional[str] = None,
|
|
129
|
+
auto_sweep_bank_public_id: Optional[str] = None,
|
|
130
|
+
auto_sweep_account_number: Optional[str] = None,
|
|
131
|
+
callback_url: Optional[str] = None,
|
|
132
|
+
) -> SubsidiaryAccountResponse:
|
|
133
|
+
"""Create a subsidiary account.
|
|
134
|
+
|
|
135
|
+
Operation: Subsidiary Accounts - Create an account.
|
|
136
|
+
|
|
137
|
+
Creates a subsidiary account. Leave out ``auto_sweep_destination`` for a
|
|
138
|
+
ledger-backed account that holds funds; set it to ``"VIRTUAL_ACCOUNT"`` or
|
|
139
|
+
``"BANK"`` for a virtual account that settles straight away.
|
|
140
|
+
|
|
141
|
+
Reusing a ``reference_number`` or ``account_reference`` returns status
|
|
142
|
+
code ``102`` (duplicate) and never creates a second account.
|
|
143
|
+
|
|
144
|
+
Args:
|
|
145
|
+
reference_number: Your unique reference for this request.
|
|
146
|
+
account_reference: Your permanent ID for the account (e.g.
|
|
147
|
+
``CUST-000184-WALLET``).
|
|
148
|
+
account_name: Account holder name.
|
|
149
|
+
first_name: Optional first name of the account holder.
|
|
150
|
+
last_name: Optional last name of the account holder.
|
|
151
|
+
phone_number: Optional phone number of the account holder.
|
|
152
|
+
email: Optional email address of the account holder.
|
|
153
|
+
iifi_number: BVN or NIN of the account holder. Hash value 3.
|
|
154
|
+
funding_transaction_limit: Optional funding transaction limit.
|
|
155
|
+
funding_daily_limit: Optional funding daily limit.
|
|
156
|
+
status: Optional account status, e.g. ``"ACTIVE"`` or ``"DISABLED"``.
|
|
157
|
+
auto_sweep_destination: Optional ``"VIRTUAL_ACCOUNT"`` or ``"BANK"``.
|
|
158
|
+
auto_sweep_bank_public_id: Bank public ID, only when the destination
|
|
159
|
+
is ``"BANK"``.
|
|
160
|
+
auto_sweep_account_number: Bank account number, only when the
|
|
161
|
+
destination is ``"BANK"``.
|
|
162
|
+
callback_url: Where Paga sends callbacks. Optional.
|
|
163
|
+
|
|
164
|
+
Returns:
|
|
165
|
+
The parsed :class:`SubsidiaryAccountResponse`.
|
|
166
|
+
|
|
167
|
+
``status_code`` of ``"102"`` means a duplicate reference was used.
|
|
168
|
+
"""
|
|
169
|
+
payload: Dict[str, Any] = {
|
|
170
|
+
"referenceNumber": reference_number,
|
|
171
|
+
"accountReference": account_reference,
|
|
172
|
+
"accountName": account_name,
|
|
173
|
+
}
|
|
174
|
+
if first_name is not None:
|
|
175
|
+
payload["firstName"] = first_name
|
|
176
|
+
if last_name is not None:
|
|
177
|
+
payload["lastName"] = last_name
|
|
178
|
+
if phone_number is not None:
|
|
179
|
+
payload["phoneNumber"] = phone_number
|
|
180
|
+
if email is not None:
|
|
181
|
+
payload["email"] = email
|
|
182
|
+
if iifi_number is not None:
|
|
183
|
+
payload["iifiNumber"] = iifi_number
|
|
184
|
+
if funding_transaction_limit is not None:
|
|
185
|
+
payload["fundingTransactionLimit"] = funding_transaction_limit
|
|
186
|
+
if funding_daily_limit is not None:
|
|
187
|
+
payload["fundingDailyLimit"] = funding_daily_limit
|
|
188
|
+
if status is not None:
|
|
189
|
+
payload["status"] = status
|
|
190
|
+
if auto_sweep_destination is not None:
|
|
191
|
+
auto_sweep: Dict[str, Any] = {"destination": auto_sweep_destination}
|
|
192
|
+
if auto_sweep_destination == "BANK":
|
|
193
|
+
if auto_sweep_bank_public_id is not None:
|
|
194
|
+
auto_sweep["bankPublicId"] = auto_sweep_bank_public_id
|
|
195
|
+
if auto_sweep_account_number is not None:
|
|
196
|
+
auto_sweep["accountNumber"] = auto_sweep_account_number
|
|
197
|
+
payload["autoSweep"] = auto_sweep
|
|
198
|
+
if callback_url is not None:
|
|
199
|
+
payload["callbackUrl"] = callback_url
|
|
200
|
+
|
|
201
|
+
response = await self._request(
|
|
202
|
+
"POST",
|
|
203
|
+
"/subsidiary-accounts",
|
|
204
|
+
payload,
|
|
205
|
+
use_hash=True,
|
|
206
|
+
use_basic=True,
|
|
207
|
+
hash_fields=SUBSIDIARY_ACCOUNT_HASH_FIELDS,
|
|
208
|
+
)
|
|
209
|
+
return SubsidiaryAccountResponse.model_validate(response.model_dump())
|
|
210
|
+
|
|
211
|
+
async def charge_subsidiary_account(
|
|
212
|
+
self,
|
|
213
|
+
*,
|
|
214
|
+
account_reference: str,
|
|
215
|
+
reference_number: str,
|
|
216
|
+
amount: float,
|
|
217
|
+
currency: str = "NGN",
|
|
218
|
+
narration: Optional[str] = None,
|
|
219
|
+
) -> SubsidiaryMoneyResponse:
|
|
220
|
+
"""Charge a ledger-backed subsidiary account.
|
|
221
|
+
|
|
222
|
+
Operation: Subsidiary Accounts - Charge an account.
|
|
223
|
+
|
|
224
|
+
Debits a ledger-backed account. Not available on virtual accounts. Retrying
|
|
225
|
+
with the same ``reference_number`` never moves money twice.
|
|
226
|
+
|
|
227
|
+
Args:
|
|
228
|
+
account_reference: The account's ``accountReference`` (the
|
|
229
|
+
``accountIdentifier``).
|
|
230
|
+
reference_number: Your unique charge reference.
|
|
231
|
+
amount: Amount to debit.
|
|
232
|
+
currency: Transaction currency. Defaults to ``"NGN"``.
|
|
233
|
+
narration: Optional narration for the charge.
|
|
234
|
+
|
|
235
|
+
Returns:
|
|
236
|
+
The parsed :class:`SubsidiaryMoneyResponse`.
|
|
237
|
+
"""
|
|
238
|
+
payload: Dict[str, Any] = {
|
|
239
|
+
"referenceNumber": reference_number,
|
|
240
|
+
"amount": amount,
|
|
241
|
+
"currency": currency,
|
|
242
|
+
}
|
|
243
|
+
if narration is not None:
|
|
244
|
+
payload["narration"] = narration
|
|
245
|
+
response = await self._request(
|
|
246
|
+
"POST",
|
|
247
|
+
f"/subsidiary-accounts/{account_reference}/charge",
|
|
248
|
+
payload,
|
|
249
|
+
use_hash=True,
|
|
250
|
+
use_basic=True,
|
|
251
|
+
hash_fields=SUBSIDIARY_CHARGE_HASH_FIELDS,
|
|
252
|
+
)
|
|
253
|
+
return SubsidiaryMoneyResponse.model_validate(response.model_dump())
|
|
254
|
+
|
|
255
|
+
async def top_up_subsidiary_account(
|
|
256
|
+
self,
|
|
257
|
+
*,
|
|
258
|
+
account_reference: str,
|
|
259
|
+
reference_number: str,
|
|
260
|
+
amount: float,
|
|
261
|
+
currency: str = "NGN",
|
|
262
|
+
narration: Optional[str] = None,
|
|
263
|
+
) -> SubsidiaryMoneyResponse:
|
|
264
|
+
"""Top up a ledger-backed subsidiary account.
|
|
265
|
+
|
|
266
|
+
Operation: Subsidiary Accounts - Top up an account.
|
|
267
|
+
|
|
268
|
+
Credits a ledger-backed account from your business balance. Not available
|
|
269
|
+
on virtual accounts.
|
|
270
|
+
|
|
271
|
+
Args:
|
|
272
|
+
account_reference: The account's ``accountReference`` (the
|
|
273
|
+
``accountIdentifier``).
|
|
274
|
+
reference_number: Your unique top-up reference.
|
|
275
|
+
amount: Amount to credit.
|
|
276
|
+
currency: Transaction currency. Defaults to ``"NGN"``.
|
|
277
|
+
narration: Optional narration for the top-up.
|
|
278
|
+
|
|
279
|
+
Returns:
|
|
280
|
+
The parsed :class:`SubsidiaryMoneyResponse`.
|
|
281
|
+
"""
|
|
282
|
+
payload: Dict[str, Any] = {
|
|
283
|
+
"referenceNumber": reference_number,
|
|
284
|
+
"amount": amount,
|
|
285
|
+
"currency": currency,
|
|
286
|
+
}
|
|
287
|
+
if narration is not None:
|
|
288
|
+
payload["narration"] = narration
|
|
289
|
+
response = await self._request(
|
|
290
|
+
"POST",
|
|
291
|
+
f"/subsidiary-accounts/{account_reference}/topup",
|
|
292
|
+
payload,
|
|
293
|
+
use_hash=True,
|
|
294
|
+
use_basic=True,
|
|
295
|
+
hash_fields=SUBSIDIARY_TOPUP_HASH_FIELDS,
|
|
296
|
+
)
|
|
297
|
+
return SubsidiaryMoneyResponse.model_validate(response.model_dump())
|
|
298
|
+
|
|
299
|
+
async def transfer_between_subsidiary_accounts(
|
|
300
|
+
self,
|
|
301
|
+
*,
|
|
302
|
+
source_account_reference: str,
|
|
303
|
+
destination_account_reference: str,
|
|
304
|
+
reference_number: str,
|
|
305
|
+
amount: float,
|
|
306
|
+
currency: str = "NGN",
|
|
307
|
+
narration: Optional[str] = None,
|
|
308
|
+
) -> SubsidiaryTransferResponse:
|
|
309
|
+
"""Transfer money between two subsidiary accounts.
|
|
310
|
+
|
|
311
|
+
Operation: Subsidiary Accounts - Transfer between accounts.
|
|
312
|
+
|
|
313
|
+
Moves money between two ledger-backed accounts. Paga sends one callback,
|
|
314
|
+
for the source account only.
|
|
315
|
+
|
|
316
|
+
Args:
|
|
317
|
+
source_account_reference: The source account's ``accountReference``.
|
|
318
|
+
destination_account_reference: The destination account's
|
|
319
|
+
``accountReference``.
|
|
320
|
+
reference_number: Your unique transfer reference.
|
|
321
|
+
amount: Amount to move.
|
|
322
|
+
currency: Transaction currency. Defaults to ``"NGN"``.
|
|
323
|
+
narration: Optional narration for the transfer.
|
|
324
|
+
|
|
325
|
+
Returns:
|
|
326
|
+
The parsed :class:`SubsidiaryTransferResponse`.
|
|
327
|
+
"""
|
|
328
|
+
payload: Dict[str, Any] = {
|
|
329
|
+
"referenceNumber": reference_number,
|
|
330
|
+
"sourceAccountIdentifier": source_account_reference,
|
|
331
|
+
"destinationAccountIdentifier": destination_account_reference,
|
|
332
|
+
"amount": amount,
|
|
333
|
+
"currency": currency,
|
|
334
|
+
}
|
|
335
|
+
if narration is not None:
|
|
336
|
+
payload["narration"] = narration
|
|
337
|
+
response = await self._request(
|
|
338
|
+
"POST",
|
|
339
|
+
"/subsidiary-accounts/transfer",
|
|
340
|
+
payload,
|
|
341
|
+
use_hash=True,
|
|
342
|
+
use_basic=True,
|
|
343
|
+
hash_fields=SUBSIDIARY_TRANSFER_HASH_FIELDS,
|
|
344
|
+
)
|
|
345
|
+
return SubsidiaryTransferResponse.model_validate(response.model_dump())
|
|
346
|
+
|
|
347
|
+
async def retrieve_subsidiary_account(
|
|
348
|
+
self,
|
|
349
|
+
*,
|
|
350
|
+
account_reference: str,
|
|
351
|
+
reference_number: str,
|
|
352
|
+
) -> SubsidiaryAccountResponse:
|
|
353
|
+
"""Retrieve a subsidiary account.
|
|
354
|
+
|
|
355
|
+
Operation: Subsidiary Accounts - Retrieve an account.
|
|
356
|
+
|
|
357
|
+
Returns an account's details, limits, callback URL and balance.
|
|
358
|
+
|
|
359
|
+
Args:
|
|
360
|
+
account_reference: The account's ``accountReference`` (the
|
|
361
|
+
``accountIdentifier``).
|
|
362
|
+
reference_number: Your unique retrieve reference.
|
|
363
|
+
|
|
364
|
+
Returns:
|
|
365
|
+
The parsed :class:`SubsidiaryAccountResponse`.
|
|
366
|
+
"""
|
|
367
|
+
response = await self._request(
|
|
368
|
+
"GET",
|
|
369
|
+
f"/subsidiary-accounts/{account_reference}",
|
|
370
|
+
{"referenceNumber": reference_number, "accountIdentifier": account_reference},
|
|
371
|
+
use_hash=True,
|
|
372
|
+
use_basic=True,
|
|
373
|
+
base_url=self.base_url,
|
|
374
|
+
hash_fields=SUBSIDIARY_RETRIEVE_HASH_FIELDS,
|
|
375
|
+
params={"referenceNumber": reference_number},
|
|
376
|
+
)
|
|
377
|
+
return SubsidiaryAccountResponse.model_validate(response.model_dump())
|
|
378
|
+
|
|
379
|
+
async def update_subsidiary_account(
|
|
380
|
+
self,
|
|
381
|
+
*,
|
|
382
|
+
account_reference: str,
|
|
383
|
+
reference_number: str,
|
|
384
|
+
account_name: Optional[str] = None,
|
|
385
|
+
iifi_number: Optional[str] = None,
|
|
386
|
+
status: Optional[str] = None,
|
|
387
|
+
auto_sweep_destination: Optional[str] = None,
|
|
388
|
+
auto_sweep_bank_public_id: Optional[str] = None,
|
|
389
|
+
auto_sweep_account_number: Optional[str] = None,
|
|
390
|
+
callback_url: Optional[str] = None,
|
|
391
|
+
) -> SubsidiaryAccountResponse:
|
|
392
|
+
"""Update a subsidiary account.
|
|
393
|
+
|
|
394
|
+
Operation: Subsidiary Accounts - Update an account.
|
|
395
|
+
|
|
396
|
+
Changes an account. Send only what you want to change. ``accountNumber``
|
|
397
|
+
and ``accountReference`` can't be changed.
|
|
398
|
+
|
|
399
|
+
Args:
|
|
400
|
+
account_reference: The account's ``accountReference`` (the
|
|
401
|
+
``accountIdentifier``).
|
|
402
|
+
reference_number: Your unique update reference.
|
|
403
|
+
account_name: Optional new account holder name.
|
|
404
|
+
iifi_number: Optional new BVN / NIN.
|
|
405
|
+
status: Optional new account status, e.g. ``"ACTIVE"`` or ``"DISABLED"``.
|
|
406
|
+
auto_sweep_destination: Optional ``"VIRTUAL_ACCOUNT"`` or ``"BANK"``.
|
|
407
|
+
auto_sweep_bank_public_id: Bank public ID, only when the destination
|
|
408
|
+
is ``"BANK"``.
|
|
409
|
+
auto_sweep_account_number: Bank account number, only when the
|
|
410
|
+
destination is ``"BANK"``.
|
|
411
|
+
callback_url: Optional new callback URL.
|
|
412
|
+
|
|
413
|
+
Returns:
|
|
414
|
+
The parsed :class:`SubsidiaryAccountResponse`.
|
|
415
|
+
"""
|
|
416
|
+
payload: Dict[str, Any] = {
|
|
417
|
+
"referenceNumber": reference_number,
|
|
418
|
+
"accountIdentifier": account_reference,
|
|
419
|
+
}
|
|
420
|
+
if account_name is not None:
|
|
421
|
+
payload["accountName"] = account_name
|
|
422
|
+
if iifi_number is not None:
|
|
423
|
+
payload["iifiNumber"] = iifi_number
|
|
424
|
+
if status is not None:
|
|
425
|
+
payload["status"] = status
|
|
426
|
+
if auto_sweep_destination is not None:
|
|
427
|
+
auto_sweep: Dict[str, Any] = {"destination": auto_sweep_destination}
|
|
428
|
+
if auto_sweep_destination == "BANK":
|
|
429
|
+
if auto_sweep_bank_public_id is not None:
|
|
430
|
+
auto_sweep["bankPublicId"] = auto_sweep_bank_public_id
|
|
431
|
+
if auto_sweep_account_number is not None:
|
|
432
|
+
auto_sweep["accountNumber"] = auto_sweep_account_number
|
|
433
|
+
payload["autoSweep"] = auto_sweep
|
|
434
|
+
if callback_url is not None:
|
|
435
|
+
payload["callbackUrl"] = callback_url
|
|
436
|
+
response = await self._request(
|
|
437
|
+
"PUT",
|
|
438
|
+
f"/subsidiary-accounts/{account_reference}",
|
|
439
|
+
payload,
|
|
440
|
+
use_hash=True,
|
|
441
|
+
use_basic=True,
|
|
442
|
+
hash_fields=SUBSIDIARY_UPDATE_HASH_FIELDS,
|
|
443
|
+
)
|
|
444
|
+
return SubsidiaryAccountResponse.model_validate(response.model_dump())
|
|
445
|
+
|
|
446
|
+
async def get_subsidiary_balance(
|
|
447
|
+
self,
|
|
448
|
+
*,
|
|
449
|
+
account_reference: str,
|
|
450
|
+
reference_number: str,
|
|
451
|
+
) -> SubsidiaryBalanceResponse:
|
|
452
|
+
"""Get a subsidiary account balance.
|
|
453
|
+
|
|
454
|
+
Operation: Subsidiary Accounts - Get the balance.
|
|
455
|
+
|
|
456
|
+
Returns an account's balance.
|
|
457
|
+
|
|
458
|
+
Args:
|
|
459
|
+
account_reference: The account's ``accountReference`` (the
|
|
460
|
+
``accountIdentifier``).
|
|
461
|
+
reference_number: Your unique balance check reference.
|
|
462
|
+
|
|
463
|
+
Returns:
|
|
464
|
+
The parsed :class:`SubsidiaryBalanceResponse`.
|
|
465
|
+
"""
|
|
466
|
+
response = await self._request(
|
|
467
|
+
"GET",
|
|
468
|
+
f"/subsidiary-accounts/{account_reference}/balance",
|
|
469
|
+
{"referenceNumber": reference_number, "accountIdentifier": account_reference},
|
|
470
|
+
use_hash=True,
|
|
471
|
+
use_basic=True,
|
|
472
|
+
base_url=self.base_url,
|
|
473
|
+
hash_fields=SUBSIDIARY_BALANCE_HASH_FIELDS,
|
|
474
|
+
params={"referenceNumber": reference_number},
|
|
475
|
+
)
|
|
476
|
+
return SubsidiaryBalanceResponse.model_validate(response.model_dump())
|
|
477
|
+
|
|
478
|
+
async def get_subsidiary_history(
|
|
479
|
+
self,
|
|
480
|
+
*,
|
|
481
|
+
account_reference: str,
|
|
482
|
+
reference_number: str,
|
|
483
|
+
start_date_time_utc: str,
|
|
484
|
+
end_date_time_utc: str,
|
|
485
|
+
page_number: int = 0,
|
|
486
|
+
page_size: int = 20,
|
|
487
|
+
) -> SubsidiaryHistoryResponse:
|
|
488
|
+
"""Get a subsidiary account transaction history.
|
|
489
|
+
|
|
490
|
+
Operation: Subsidiary Accounts - Get transaction history.
|
|
491
|
+
|
|
492
|
+
Returns an account's transactions, up to 3 months at a time. Pages start
|
|
493
|
+
at ``0``. ``reference_number`` is required, but isn't part of this hash.
|
|
494
|
+
|
|
495
|
+
Args:
|
|
496
|
+
account_reference: The account's ``accountReference`` (the
|
|
497
|
+
``accountIdentifier``).
|
|
498
|
+
reference_number: Your unique history reference (query only).
|
|
499
|
+
start_date_time_utc: Start of the range, in UTC.
|
|
500
|
+
end_date_time_utc: End of the range, in UTC.
|
|
501
|
+
page_number: Page number to fetch. Defaults to ``0``.
|
|
502
|
+
page_size: Page size. Defaults to ``20``.
|
|
503
|
+
|
|
504
|
+
Returns:
|
|
505
|
+
The parsed :class:`SubsidiaryHistoryResponse`.
|
|
506
|
+
"""
|
|
507
|
+
response = await self._request(
|
|
508
|
+
"GET",
|
|
509
|
+
f"/subsidiary-accounts/{account_reference}/history",
|
|
510
|
+
{
|
|
511
|
+
"accountIdentifier": account_reference,
|
|
512
|
+
"startDateTimeUTC": start_date_time_utc,
|
|
513
|
+
"endDateTimeUTC": end_date_time_utc,
|
|
514
|
+
},
|
|
515
|
+
use_hash=True,
|
|
516
|
+
use_basic=False,
|
|
517
|
+
base_url=self.business_base_url,
|
|
518
|
+
hash_fields=SUBSIDIARY_HISTORY_HASH_FIELDS,
|
|
519
|
+
params={
|
|
520
|
+
"referenceNumber": reference_number,
|
|
521
|
+
"startDateTimeUTC": start_date_time_utc,
|
|
522
|
+
"endDateTimeUTC": end_date_time_utc,
|
|
523
|
+
"pageSize": page_size,
|
|
524
|
+
"pageNumber": page_number,
|
|
525
|
+
},
|
|
526
|
+
)
|
|
527
|
+
return SubsidiaryHistoryResponse.model_validate(response.model_dump())
|
|
528
|
+
|
|
529
|
+
# ----------------------------------------------------------------- #
|
|
530
|
+
# Transfers to Paga wallets
|
|
531
|
+
# ----------------------------------------------------------------- #
|
|
532
|
+
|
|
533
|
+
async def transfer_to_paga_wallet(
|
|
534
|
+
self,
|
|
535
|
+
*,
|
|
536
|
+
reference_number: str,
|
|
537
|
+
amount: float,
|
|
538
|
+
destination_account: str,
|
|
539
|
+
currency: str = "NGN",
|
|
540
|
+
destination_bank: Optional[str] = None,
|
|
541
|
+
send_withdrawal_code: bool = True,
|
|
542
|
+
source_of_funds: Optional[str] = None,
|
|
543
|
+
transfer_reference: Optional[str] = None,
|
|
544
|
+
suppress_recipient_message: bool = False,
|
|
545
|
+
alternate_sender_name: Optional[str] = None,
|
|
546
|
+
locale: Optional[str] = None,
|
|
547
|
+
) -> MoneyTransferResponse:
|
|
548
|
+
"""Send money to a Paga wallet.
|
|
549
|
+
|
|
550
|
+
Operation: Business API - Money transfer to a Paga wallet.
|
|
551
|
+
|
|
552
|
+
Sends money from the business balance to a Paga user, identified by
|
|
553
|
+
their phone number, nickname or account number. This is the
|
|
554
|
+
Paga-wallet sibling of :meth:`send_money`, which sends to a bank
|
|
555
|
+
account.
|
|
556
|
+
|
|
557
|
+
Args:
|
|
558
|
+
reference_number: Your unique transfer reference. At most 50
|
|
559
|
+
characters.
|
|
560
|
+
amount: The amount to send.
|
|
561
|
+
destination_account: The recipient's phone number, nickname or
|
|
562
|
+
account number.
|
|
563
|
+
currency: Transaction currency. Defaults to ``"NGN"``.
|
|
564
|
+
destination_bank: Bank code, when transferring to a bank account.
|
|
565
|
+
send_withdrawal_code: Whether to issue the recipient a withdrawal
|
|
566
|
+
code. Defaults to ``True``.
|
|
567
|
+
source_of_funds: Defaults to the sender's own Paga account.
|
|
568
|
+
transfer_reference: An alternative reconciliation reference.
|
|
569
|
+
suppress_recipient_message: Whether to suppress the recipient's
|
|
570
|
+
message. Defaults to ``False``.
|
|
571
|
+
alternate_sender_name: An alternate sender name, at most 16
|
|
572
|
+
characters. Only when the sender principal is absent.
|
|
573
|
+
locale: Optional IETF language tag.
|
|
574
|
+
|
|
575
|
+
Returns:
|
|
576
|
+
The parsed :class:`MoneyTransferResponse`.
|
|
577
|
+
"""
|
|
578
|
+
payload: Dict[str, Any] = {
|
|
579
|
+
"referenceNumber": reference_number,
|
|
580
|
+
"amount": amount,
|
|
581
|
+
"currency": currency,
|
|
582
|
+
"destinationAccount": destination_account,
|
|
583
|
+
"sendWithdrawalCode": send_withdrawal_code,
|
|
584
|
+
"suppressRecipientMessage": suppress_recipient_message,
|
|
585
|
+
}
|
|
586
|
+
if destination_bank is not None:
|
|
587
|
+
payload["destinationBank"] = destination_bank
|
|
588
|
+
if source_of_funds is not None:
|
|
589
|
+
payload["sourceOfFunds"] = source_of_funds
|
|
590
|
+
if transfer_reference is not None:
|
|
591
|
+
payload["transferReference"] = transfer_reference
|
|
592
|
+
if alternate_sender_name is not None:
|
|
593
|
+
payload["alternateSenderName"] = alternate_sender_name
|
|
594
|
+
if locale is not None:
|
|
595
|
+
payload["locale"] = locale
|
|
596
|
+
|
|
597
|
+
response = await self._request(
|
|
598
|
+
"POST",
|
|
599
|
+
"/moneyTransfer",
|
|
600
|
+
payload,
|
|
601
|
+
use_hash=True,
|
|
602
|
+
use_basic=False,
|
|
603
|
+
base_url=self.business_base_url,
|
|
604
|
+
hash_fields=PAGA_WALLET_TRANSFER_HASH_FIELDS,
|
|
605
|
+
raise_on_error=False,
|
|
606
|
+
)
|
|
607
|
+
return MoneyTransferResponse.model_validate(response.model_dump())
|
|
608
|
+
|
|
609
|
+
async def validate_money_transfer(
|
|
610
|
+
self,
|
|
611
|
+
*,
|
|
612
|
+
reference_number: str,
|
|
613
|
+
amount: float,
|
|
614
|
+
destination_account: str,
|
|
615
|
+
currency: str = "NGN",
|
|
616
|
+
) -> ValidateMoneyTransferResponse:
|
|
617
|
+
"""Validate a Paga wallet transfer before sending it.
|
|
618
|
+
|
|
619
|
+
Operation: Business API - Validate a money transfer.
|
|
620
|
+
|
|
621
|
+
Confirms the recipient exists and returns their name, registration
|
|
622
|
+
status, KYC level and the fee, before any money moves.
|
|
623
|
+
|
|
624
|
+
Args:
|
|
625
|
+
reference_number: Your unique reference for this request.
|
|
626
|
+
amount: The amount you intend to send.
|
|
627
|
+
destination_account: The recipient's phone number, nickname or
|
|
628
|
+
account number.
|
|
629
|
+
currency: Transaction currency. Defaults to ``"NGN"``.
|
|
630
|
+
|
|
631
|
+
Returns:
|
|
632
|
+
The parsed :class:`ValidateMoneyTransferResponse`.
|
|
633
|
+
"""
|
|
634
|
+
response = await self._request(
|
|
635
|
+
"POST",
|
|
636
|
+
"/validateMoneyTransfer",
|
|
637
|
+
{
|
|
638
|
+
"referenceNumber": reference_number,
|
|
639
|
+
"amount": amount,
|
|
640
|
+
"currency": currency,
|
|
641
|
+
"destinationAccount": destination_account,
|
|
642
|
+
},
|
|
643
|
+
use_hash=True,
|
|
644
|
+
use_basic=False,
|
|
645
|
+
base_url=self.business_base_url,
|
|
646
|
+
hash_fields=VALIDATE_MONEY_TRANSFER_HASH_FIELDS,
|
|
647
|
+
raise_on_error=False,
|
|
648
|
+
)
|
|
649
|
+
return ValidateMoneyTransferResponse.model_validate(response.model_dump())
|
|
650
|
+
|
|
651
|
+
async def send_bulk_money_transfer(
|
|
652
|
+
self,
|
|
653
|
+
*,
|
|
654
|
+
items: List[Dict[str, Any]],
|
|
655
|
+
bulk_reference_number: Optional[str] = None,
|
|
656
|
+
) -> BulkMoneyTransferResponse:
|
|
657
|
+
"""Send up to 300 money transfers in one call.
|
|
658
|
+
|
|
659
|
+
Operation: Business API - Bulk money transfer.
|
|
660
|
+
|
|
661
|
+
Each item needs a ``referenceNumber``, an ``amount`` and a
|
|
662
|
+
``destinationAccount``; ``currency``, ``destinationBank``,
|
|
663
|
+
``transferReference`` and ``suppressRecipientMessage`` are optional.
|
|
664
|
+
Sending more than 300 items is rejected with response code ``-3``.
|
|
665
|
+
|
|
666
|
+
Paga hashes the **first item's** reference number, amount and
|
|
667
|
+
destination account, followed by the total number of items — the SDK
|
|
668
|
+
does that for you.
|
|
669
|
+
|
|
670
|
+
Args:
|
|
671
|
+
items: The transfers to send.
|
|
672
|
+
bulk_reference_number: Your reference for the batch as a whole.
|
|
673
|
+
|
|
674
|
+
Returns:
|
|
675
|
+
The parsed :class:`BulkMoneyTransferResponse`. Check every entry
|
|
676
|
+
in ``results`` — a bulk transfer can partially succeed.
|
|
677
|
+
"""
|
|
678
|
+
if not items:
|
|
679
|
+
raise ValueError("items must not be empty")
|
|
680
|
+
if len(items) > 300:
|
|
681
|
+
raise ValueError("a bulk money transfer may contain at most 300 items")
|
|
682
|
+
|
|
683
|
+
payload: Dict[str, Any] = {"items": [dict(item) for item in items]}
|
|
684
|
+
if bulk_reference_number is not None:
|
|
685
|
+
payload["bulkReferenceNumber"] = bulk_reference_number
|
|
686
|
+
|
|
687
|
+
first = items[0]
|
|
688
|
+
hash_payload = {
|
|
689
|
+
"referenceNumber": first.get("referenceNumber"),
|
|
690
|
+
"amount": first.get("amount"),
|
|
691
|
+
"destinationAccount": first.get("destinationAccount"),
|
|
692
|
+
"itemCount": len(items),
|
|
693
|
+
}
|
|
694
|
+
response = await self._request(
|
|
695
|
+
"POST",
|
|
696
|
+
"/moneyTransferBulk",
|
|
697
|
+
payload,
|
|
698
|
+
use_hash=True,
|
|
699
|
+
use_basic=False,
|
|
700
|
+
base_url=self.business_base_url,
|
|
701
|
+
hash_fields=MONEY_TRANSFER_BULK_HASH_FIELDS,
|
|
702
|
+
hash_payload=hash_payload,
|
|
703
|
+
raise_on_error=False,
|
|
704
|
+
)
|
|
705
|
+
return BulkMoneyTransferResponse.model_validate(response.model_dump())
|
|
706
|
+
|
|
707
|
+
# ----------------------------------------------------------------- #
|
|
708
|
+
# Operations, merchants and cash
|
|
709
|
+
# ----------------------------------------------------------------- #
|
|
710
|
+
|
|
711
|
+
async def get_operation_status(
|
|
712
|
+
self,
|
|
713
|
+
*,
|
|
714
|
+
reference_number: str,
|
|
715
|
+
locale: Optional[str] = None,
|
|
716
|
+
) -> OperationStatusResponse:
|
|
717
|
+
"""Check an operation's status.
|
|
718
|
+
|
|
719
|
+
Operation: Business API - Get an operation status.
|
|
720
|
+
|
|
721
|
+
Args:
|
|
722
|
+
reference_number: The reference number the operation was sent
|
|
723
|
+
with.
|
|
724
|
+
locale: Optional IETF language tag.
|
|
725
|
+
|
|
726
|
+
Returns:
|
|
727
|
+
The parsed :class:`OperationStatusResponse`. The status is in
|
|
728
|
+
``transactionStatus``, not ``status``.
|
|
729
|
+
"""
|
|
730
|
+
payload: Dict[str, Any] = {"referenceNumber": reference_number}
|
|
731
|
+
if locale is not None:
|
|
732
|
+
payload["locale"] = locale
|
|
733
|
+
|
|
734
|
+
response = await self._request(
|
|
735
|
+
"POST",
|
|
736
|
+
"/getOperationStatus",
|
|
737
|
+
payload,
|
|
738
|
+
use_hash=True,
|
|
739
|
+
use_basic=False,
|
|
740
|
+
base_url=self.business_base_url,
|
|
741
|
+
hash_fields=GET_OPERATION_STATUS_HASH_FIELDS,
|
|
742
|
+
raise_on_error=False,
|
|
743
|
+
)
|
|
744
|
+
return OperationStatusResponse.model_validate(response.model_dump())
|
|
745
|
+
|
|
746
|
+
async def onboard_merchant(
|
|
747
|
+
self,
|
|
748
|
+
*,
|
|
749
|
+
reference: str,
|
|
750
|
+
merchant_external_id: str,
|
|
751
|
+
legal_entity: Dict[str, Any],
|
|
752
|
+
legal_entity_representative: Dict[str, Any],
|
|
753
|
+
integration: Dict[str, Any],
|
|
754
|
+
additional_parameters: Optional[Dict[str, Any]] = None,
|
|
755
|
+
) -> OnboardMerchantResponse:
|
|
756
|
+
"""Onboard a merchant.
|
|
757
|
+
|
|
758
|
+
Operation: Business API - Onboard a merchant.
|
|
759
|
+
|
|
760
|
+
For aggregators only.
|
|
761
|
+
|
|
762
|
+
Paga signs the request over the reference, the merchant's external
|
|
763
|
+
id, the legal entity's ``name`` and the representative's ``phone``
|
|
764
|
+
and ``email`` — the SDK assembles that from the arguments.
|
|
765
|
+
|
|
766
|
+
Args:
|
|
767
|
+
reference: Your unique reference. Paga names this field
|
|
768
|
+
``reference``, not ``referenceNumber``.
|
|
769
|
+
merchant_external_id: Your own identifier for the merchant.
|
|
770
|
+
legal_entity: The legal entity. Needs at least ``name``.
|
|
771
|
+
legal_entity_representative: The representative. Needs
|
|
772
|
+
``firstName``, ``lastName``, ``phone``, ``email`` and
|
|
773
|
+
``dateOfBirth``.
|
|
774
|
+
integration: How Paga notifies the merchant. Either
|
|
775
|
+
``{"type": "EMAIL_NOTIFICATION", "financeAdminEmail": ...}``
|
|
776
|
+
or ``{"type": "MERCHANT_NOTIFICATION_REVERSE_API",
|
|
777
|
+
"callbackUrl": ..., "username": ..., "password": ...}``.
|
|
778
|
+
additional_parameters: Optional extra merchant parameters. Needs
|
|
779
|
+
at least ``displayName`` and ``establishedDate``.
|
|
780
|
+
|
|
781
|
+
Returns:
|
|
782
|
+
The parsed :class:`OnboardMerchantResponse`.
|
|
783
|
+
"""
|
|
784
|
+
merchant_info: Dict[str, Any] = {
|
|
785
|
+
"legalEntity": legal_entity,
|
|
786
|
+
"legalEntityRepresentative": legal_entity_representative,
|
|
787
|
+
"additionalParameters": additional_parameters or {},
|
|
788
|
+
}
|
|
789
|
+
payload: Dict[str, Any] = {
|
|
790
|
+
"reference": reference,
|
|
791
|
+
"merchantExternalId": merchant_external_id,
|
|
792
|
+
"merchantInfo": merchant_info,
|
|
793
|
+
"integration": integration,
|
|
794
|
+
}
|
|
795
|
+
|
|
796
|
+
hash_payload = {
|
|
797
|
+
"referenceNumber": reference,
|
|
798
|
+
"merchantExternalId": merchant_external_id,
|
|
799
|
+
"name": legal_entity.get("name"),
|
|
800
|
+
"phone": legal_entity_representative.get("phone"),
|
|
801
|
+
"email": legal_entity_representative.get("email"),
|
|
802
|
+
}
|
|
803
|
+
response = await self._request(
|
|
804
|
+
"POST",
|
|
805
|
+
"/onboardMerchant",
|
|
806
|
+
payload,
|
|
807
|
+
use_hash=True,
|
|
808
|
+
use_basic=False,
|
|
809
|
+
base_url=self.business_base_url,
|
|
810
|
+
hash_fields=ONBOARD_MERCHANT_HASH_FIELDS,
|
|
811
|
+
hash_payload=hash_payload,
|
|
812
|
+
raise_on_error=False,
|
|
813
|
+
)
|
|
814
|
+
return OnboardMerchantResponse.model_validate(response.model_dump())
|
|
815
|
+
|
|
816
|
+
async def dispense_cash(
|
|
817
|
+
self,
|
|
818
|
+
*,
|
|
819
|
+
reference_number: str,
|
|
820
|
+
customer_phone_number: str,
|
|
821
|
+
amount: float,
|
|
822
|
+
withdrawal_code: str,
|
|
823
|
+
locale: Optional[str] = None,
|
|
824
|
+
) -> DispenseCashResponse:
|
|
825
|
+
"""Dispense cash against a customer's withdrawal code.
|
|
826
|
+
|
|
827
|
+
Operation: Business API - Dispense cash.
|
|
828
|
+
|
|
829
|
+
Args:
|
|
830
|
+
reference_number: Your unique reference for this request.
|
|
831
|
+
customer_phone_number: The customer's phone number.
|
|
832
|
+
amount: The amount to dispense.
|
|
833
|
+
withdrawal_code: The customer's withdrawal code.
|
|
834
|
+
locale: Optional IETF language tag.
|
|
835
|
+
|
|
836
|
+
Returns:
|
|
837
|
+
The parsed :class:`DispenseCashResponse`.
|
|
838
|
+
"""
|
|
839
|
+
payload: Dict[str, Any] = {
|
|
840
|
+
"referenceNumber": reference_number,
|
|
841
|
+
"customerPhoneNumber": customer_phone_number,
|
|
842
|
+
"amount": amount,
|
|
843
|
+
"withdrawalCode": withdrawal_code,
|
|
844
|
+
}
|
|
845
|
+
if locale is not None:
|
|
846
|
+
payload["locale"] = locale
|
|
847
|
+
|
|
848
|
+
response = await self._request(
|
|
849
|
+
"POST",
|
|
850
|
+
"/dispenseCash",
|
|
851
|
+
payload,
|
|
852
|
+
use_hash=True,
|
|
853
|
+
use_basic=False,
|
|
854
|
+
base_url=self.business_base_url,
|
|
855
|
+
hash_fields=DISPENSE_CASH_HASH_FIELDS,
|
|
856
|
+
raise_on_error=False,
|
|
857
|
+
)
|
|
858
|
+
return DispenseCashResponse.model_validate(response.model_dump())
|