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/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())