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/models.py ADDED
@@ -0,0 +1,1001 @@
1
+ """Response and payload models for the Paga Engine API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Dict, List, Optional, Union
6
+
7
+ from pydantic import BaseModel, ConfigDict, Field, model_validator
8
+
9
+
10
+ class PagaResponse(BaseModel):
11
+ """Normalized envelope returned by Paga Engine API operations."""
12
+
13
+ model_config = ConfigDict(extra="allow")
14
+
15
+ responseCode: int = Field(default=0, description="Status code of the response. 0 indicates success.")
16
+ responseCategoryCode: Optional[int] = Field(default=None)
17
+ message: Optional[str] = Field(default=None)
18
+ referenceNumber: Optional[str] = Field(default=None)
19
+ transactionId: Optional[str] = Field(default=None)
20
+ withdrawalCode: Optional[str] = Field(default=None)
21
+ reversalId: Optional[str] = Field(default=None)
22
+ currency: Optional[str] = Field(default=None)
23
+ exchangeRate: Optional[float] = Field(default=None)
24
+ fee: Optional[float] = Field(default=None)
25
+ receiverRegistrationStatus: Optional[str] = Field(default=None)
26
+ recipientAccountHolderName: Optional[str] = Field(default=None)
27
+
28
+ @property
29
+ def is_success(self) -> bool:
30
+ """Return True when the operation completed successfully."""
31
+ return self.responseCode == 0
32
+
33
+
34
+ class CollectPaymentMethodResult(BaseModel):
35
+ """Payment method details returned as part of a payment request."""
36
+
37
+ model_config = ConfigDict(extra="allow")
38
+
39
+ name: Optional[str] = None
40
+ properties: Dict[str, Any] = Field(default_factory=dict)
41
+
42
+
43
+ class CollectPaymentRequestResponse(BaseModel):
44
+ """Response returned when creating a Paga payment request."""
45
+
46
+ model_config = ConfigDict(extra="allow")
47
+
48
+ referenceNumber: Optional[str] = None
49
+ statusCode: Optional[str] = None
50
+ statusMessage: Optional[str] = None
51
+ requestAmount: Optional[float] = None
52
+ totalPaymentAmount: Optional[float] = None
53
+ paymentMethods: List[CollectPaymentMethodResult] = Field(default_factory=list)
54
+ expiryDateTimeUTC: Optional[str] = None
55
+ isPayerPagaAccountHolder: Optional[bool] = None
56
+ bankName: Optional[str] = None
57
+
58
+
59
+ class CheckoutVerifyChargeResponse(BaseModel):
60
+ """Response returned when verifying a checkout charge."""
61
+
62
+ model_config = ConfigDict(extra="allow")
63
+
64
+ status_code: Optional[int] = None
65
+ status_message: Optional[str] = None
66
+ chargeId: Optional[str] = None
67
+ amount: Optional[float] = None
68
+ currency: Optional[str] = None
69
+
70
+
71
+ class MerchantPaymentResponse(BaseModel):
72
+ """Response returned when paying a bill."""
73
+
74
+ model_config = ConfigDict(extra="allow")
75
+
76
+ responseCode: Optional[int] = None
77
+ responseCategoryCode: Optional[int] = None
78
+ message: Optional[str] = None
79
+ referenceNumber: Optional[str] = None
80
+ merchantTransactionReference: Optional[str] = None
81
+ transactionId: Optional[str] = None
82
+ reversalId: Optional[str] = None
83
+ currency: Optional[str] = None
84
+ exchangeRate: Optional[float] = None
85
+ fee: Optional[float] = None
86
+ integrationStatus: Optional[str] = None
87
+ additionalProperties: Optional[Dict[str, Any]] = None
88
+
89
+
90
+ class PurchaseResponse(BaseModel):
91
+ """Response returned when buying airtime or data."""
92
+
93
+ model_config = ConfigDict(extra="allow")
94
+
95
+ responseCode: Optional[int] = None
96
+ responseCategoryCode: Optional[int] = None
97
+ message: Optional[str] = None
98
+ referenceNumber: Optional[str] = None
99
+ transactionId: Optional[str] = None
100
+ reversalId: Optional[str] = None
101
+ currency: Optional[str] = None
102
+ exchangeRate: Optional[float] = None
103
+ integrationStatus: Optional[str] = None
104
+ fee: Optional[float] = None
105
+
106
+
107
+ class AccountBalanceResponse(BaseModel):
108
+ """Response returned when checking the business account balance."""
109
+
110
+ model_config = ConfigDict(extra="allow")
111
+
112
+ referenceNumber: Optional[str] = None
113
+ responseCode: Optional[int] = None
114
+ totalBalance: Optional[str] = None
115
+ availableBalance: Optional[float] = None
116
+ currency: Optional[str] = None
117
+
118
+
119
+ class SubsidiaryAccountResponse(BaseModel):
120
+ """Response returned when creating a subsidiary account."""
121
+
122
+ model_config = ConfigDict(extra="allow")
123
+
124
+ referenceNumber: Optional[str] = None
125
+ statusCode: Optional[str] = None
126
+ statusMessage: Optional[str] = None
127
+ accountNumber: Optional[str] = None
128
+ accountReference: Optional[str] = None
129
+ status: Optional[str] = None
130
+ balance: Optional[float] = None
131
+ currency: Optional[str] = None
132
+
133
+
134
+ class SubsidiaryMoneyResponse(BaseModel):
135
+ """Response returned when charging or topping up a subsidiary account."""
136
+
137
+ model_config = ConfigDict(extra="allow")
138
+
139
+ referenceNumber: Optional[str] = None
140
+ statusCode: Optional[str] = None
141
+ statusMessage: Optional[str] = None
142
+ transactionId: Optional[str] = None
143
+ newBalance: Optional[float] = None
144
+
145
+
146
+ class SubsidiaryTransferResponse(BaseModel):
147
+ """Response returned when transferring between subsidiary accounts."""
148
+
149
+ model_config = ConfigDict(extra="allow")
150
+
151
+ referenceNumber: Optional[str] = None
152
+ statusCode: Optional[str] = None
153
+ statusMessage: Optional[str] = None
154
+ transactionId: Optional[str] = None
155
+ source: Optional[Dict[str, Any]] = None
156
+ destination: Optional[Dict[str, Any]] = None
157
+
158
+
159
+ class SubsidiaryBalanceResponse(BaseModel):
160
+ """Response returned when getting a subsidiary account balance."""
161
+
162
+ model_config = ConfigDict(extra="allow")
163
+
164
+ statusCode: Optional[str] = None
165
+ accountReference: Optional[str] = None
166
+ accountNumber: Optional[str] = None
167
+ balance: Optional[float] = None
168
+ currency: Optional[str] = None
169
+ timeStamp: Optional[str] = None
170
+
171
+
172
+ class SubsidiaryHistoryResponse(BaseModel):
173
+ """Response returned when getting a subsidiary account history."""
174
+
175
+ model_config = ConfigDict(extra="allow")
176
+
177
+ statusCode: Optional[str] = None
178
+ itemCount: Optional[int] = None
179
+ totalItems: Optional[int] = None
180
+ totalPages: Optional[int] = None
181
+ currentPage: Optional[int] = None
182
+ transactions: List[TransactionItem] = Field(default_factory=list)
183
+
184
+
185
+ class TransactionItem(BaseModel):
186
+ """A single transaction in a business transaction history."""
187
+
188
+ model_config = ConfigDict(extra="allow")
189
+
190
+ referenceNumber: Optional[str] = None
191
+ status: Optional[str] = None
192
+ amount: Optional[float] = None
193
+ fee: Optional[float] = None
194
+ balance: Optional[float] = None
195
+ dateUTC: Optional[int] = None
196
+
197
+
198
+ class TransactionHistoryResponse(BaseModel):
199
+ """Response returned when fetching the business transaction history."""
200
+
201
+ model_config = ConfigDict(extra="allow")
202
+
203
+ referenceNumber: Optional[str] = None
204
+ responseCode: Optional[int] = None
205
+ items: List[TransactionItem] = Field(default_factory=list)
206
+
207
+
208
+ class PaymentStatusData(BaseModel):
209
+ """Payment status details nested in a payment status response."""
210
+
211
+ model_config = ConfigDict(extra="allow")
212
+
213
+ referenceNumber: Optional[str] = None
214
+ statusCode: Optional[str] = None
215
+ statusMessage: Optional[str] = None
216
+ requestAmount: Optional[float] = None
217
+ totalPaymentAmount: Optional[float] = None
218
+ expiryDateTimeUTC: Optional[str] = None
219
+ additionalData: Optional[Dict[str, Any]] = None
220
+ refundStatus: Optional[str] = None
221
+
222
+
223
+ class PaymentStatusResponse(BaseModel):
224
+ """Response returned when checking the status of a payment request."""
225
+
226
+ model_config = ConfigDict(extra="allow")
227
+
228
+ referenceNumber: Optional[str] = None
229
+ statusCode: Optional[str] = None
230
+ statusMessage: Optional[str] = None
231
+ data: Optional[PaymentStatusData] = None
232
+
233
+
234
+ class DepositToBankResponse(BaseModel):
235
+ """Response returned when sending money to a bank account or Paga wallet."""
236
+
237
+ model_config = ConfigDict(extra="allow")
238
+
239
+ referenceNumber: Optional[str] = None
240
+ responseCode: Optional[int] = None
241
+ message: Optional[str] = None
242
+ transactionId: Optional[str] = None
243
+ destinationAccountHolderNameAtBank: Optional[str] = None
244
+ fee: Optional[float] = None
245
+ vat: Optional[float] = None
246
+ currency: Optional[str] = None
247
+ exchangeRate: Optional[float] = None
248
+ sessionId: Optional[str] = None
249
+
250
+
251
+ class RefundResponse(BaseModel):
252
+ """Response returned when refunding or cancelling a payment request."""
253
+
254
+ model_config = ConfigDict(extra="allow")
255
+
256
+ referenceNumber: Optional[str] = None
257
+ statusCode: Optional[str] = None
258
+ statusMessage: Optional[str] = None
259
+ refundAmount: Optional[float] = None
260
+ currency: Optional[str] = None
261
+ refundDestination: Optional[str] = None
262
+
263
+
264
+ class PagaPaymentCallback(BaseModel):
265
+ """Normalized payment callback (notification) payload sent by Paga."""
266
+
267
+ model_config = ConfigDict(extra="allow")
268
+
269
+ event: Optional[str] = None
270
+ notificationId: Optional[str] = None
271
+ statusCode: Optional[str] = None
272
+ statusMessage: Optional[str] = None
273
+ externalReferenceNumber: Optional[str] = None
274
+ state: Optional[str] = None
275
+ outstandingBalance: Optional[float] = None
276
+ paymentAmount: Optional[float] = None
277
+ cumulativePaymentAmount: Optional[float] = None
278
+ collectionFee: Optional[float] = None
279
+ fundingDetails: Optional[Dict[str, Any]] = None
280
+ hash: Optional[str] = None
281
+
282
+
283
+ # --------------------------------------------------------------------------- #
284
+ # Directory lookups (banks, operators, bundles, billers)
285
+ # --------------------------------------------------------------------------- #
286
+
287
+
288
+ class CollectBank(BaseModel):
289
+ """A bank a customer can pay from, as listed by the Collect API."""
290
+
291
+ model_config = ConfigDict(extra="allow")
292
+
293
+ name: Optional[str] = None
294
+ uuid: Optional[str] = None
295
+
296
+
297
+ class CollectBanksResponse(BaseModel):
298
+ """Response returned when listing the banks available to a customer."""
299
+
300
+ model_config = ConfigDict(extra="allow")
301
+
302
+ referenceNumber: Optional[str] = None
303
+ statusCode: Optional[str] = None
304
+ statusMessage: Optional[str] = None
305
+ banks: List[CollectBank] = Field(default_factory=list)
306
+
307
+
308
+ class Bank(BaseModel):
309
+ """An institution that can be paid, as listed by the Business API."""
310
+
311
+ model_config = ConfigDict(extra="allow")
312
+
313
+ uuid: Optional[str] = None
314
+ name: Optional[str] = None
315
+ interInstitutionCode: Optional[str] = None
316
+ sortCode: Optional[str] = None
317
+
318
+
319
+ class BanksResponse(BaseModel):
320
+ """Response returned when listing payable institutions.
321
+
322
+ ``uuid`` is what you send as ``destinationBankUUID``. Paga's own UUID is
323
+ ``AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA`` (send to a Paga wallet).
324
+ """
325
+
326
+ model_config = ConfigDict(extra="allow")
327
+
328
+ referenceNumber: Optional[str] = None
329
+ responseCode: Optional[int] = None
330
+ message: Optional[str] = None
331
+ banks: List[Bank] = Field(default_factory=list)
332
+
333
+ @model_validator(mode="before")
334
+ @classmethod
335
+ def _accept_singular_bank_key(cls, data: Any) -> Any:
336
+ """Accept the singular ``bank`` key Paga's legacy docs show.
337
+
338
+ The current Business API returns ``banks``; the legacy operations
339
+ page documents ``bank``. Read both.
340
+ """
341
+ if isinstance(data, dict) and not data.get("banks") and data.get("bank"):
342
+ data = dict(data)
343
+ data["banks"] = data.pop("bank")
344
+ return data
345
+
346
+
347
+ class MobileOperator(BaseModel):
348
+ """A mobile network that can be topped up."""
349
+
350
+ model_config = ConfigDict(extra="allow")
351
+
352
+ name: Optional[str] = None
353
+ mobileOperatorCode: Optional[str] = None
354
+
355
+
356
+ class MobileOperatorsResponse(BaseModel):
357
+ """Response returned when listing mobile operators.
358
+
359
+ ``mobileOperatorCode`` is what you send as ``mobileOperatorPublicId`` when
360
+ buying airtime, and as ``operatorPublicId`` when listing data bundles.
361
+ """
362
+
363
+ model_config = ConfigDict(extra="allow")
364
+
365
+ referenceNumber: Optional[str] = None
366
+ responseCode: Optional[int] = None
367
+ message: Optional[str] = None
368
+ mobileOperator: List[MobileOperator] = Field(default_factory=list)
369
+
370
+
371
+ class DataBundle(BaseModel):
372
+ """A data bundle offered by a mobile operator."""
373
+
374
+ model_config = ConfigDict(extra="allow")
375
+
376
+ serviceId: Optional[str] = None
377
+ serviceName: Optional[str] = None
378
+ servicePrice: Optional[float] = None
379
+ validityPeriod: Optional[str] = None
380
+ dataValue: Optional[str] = None
381
+
382
+
383
+ class DataBundlesResponse(BaseModel):
384
+ """Response returned when listing an operator's data bundles.
385
+
386
+ Send ``serviceId`` as ``mobileOperatorServiceId`` and **exactly**
387
+ ``servicePrice`` as ``amount``.
388
+ """
389
+
390
+ model_config = ConfigDict(extra="allow")
391
+
392
+ referenceNumber: Optional[str] = None
393
+ responseCode: Optional[int] = None
394
+ message: Optional[str] = None
395
+ mobileOperatorServices: List[DataBundle] = Field(default_factory=list)
396
+
397
+
398
+ class Merchant(BaseModel):
399
+ """A biller that can be paid."""
400
+
401
+ model_config = ConfigDict(extra="allow")
402
+
403
+ displayName: Optional[str] = None
404
+ name: Optional[str] = None
405
+ description: Optional[str] = None
406
+ uuid: Optional[str] = None
407
+
408
+
409
+ class MerchantsResponse(BaseModel):
410
+ """Response returned when listing billers.
411
+
412
+ ``uuid`` is what you send as ``merchantAccount``.
413
+ """
414
+
415
+ model_config = ConfigDict(extra="allow")
416
+
417
+ referenceNumber: Optional[str] = None
418
+ responseCode: Optional[int] = None
419
+ message: Optional[str] = None
420
+ merchants: List[Merchant] = Field(default_factory=list)
421
+
422
+
423
+ class MerchantService(BaseModel):
424
+ """Something a biller can be paid for."""
425
+
426
+ model_config = ConfigDict(extra="allow")
427
+
428
+ name: Optional[str] = None
429
+ code: Optional[str] = None
430
+ price: Optional[float] = None
431
+ shortCode: Optional[str] = None
432
+
433
+
434
+ class MerchantServicesResponse(BaseModel):
435
+ """Response returned when listing a biller's services.
436
+
437
+ An empty ``services`` list means any amount is allowed. A ``price`` of
438
+ ``0.0`` means the customer chooses the amount. Otherwise pay the
439
+ service's ``price``.
440
+ """
441
+
442
+ model_config = ConfigDict(extra="allow")
443
+
444
+ referenceNumber: Optional[str] = None
445
+ responseCode: Optional[int] = None
446
+ message: Optional[str] = None
447
+ services: List[MerchantService] = Field(default_factory=list)
448
+
449
+
450
+ class MerchantAccountDetailsResponse(BaseModel):
451
+ """Response returned when validating a customer's account at a biller.
452
+
453
+ ``details`` varies per biller, so it is left as a free-form mapping.
454
+ """
455
+
456
+ model_config = ConfigDict(extra="allow")
457
+
458
+ referenceNumber: Optional[str] = None
459
+ responseCode: Optional[int] = None
460
+ message: Optional[str] = None
461
+ customerName: Optional[str] = None
462
+ phoneNumber: Optional[str] = None
463
+ accountNumber: Optional[str] = None
464
+ address: Optional[str] = None
465
+ details: Optional[Dict[str, Any]] = None
466
+
467
+
468
+ class ValidateDepositToBankResponse(BaseModel):
469
+ """Response returned when validating a destination bank account.
470
+
471
+ ``fee`` and ``vat`` quote what the transfer will cost, before you send it.
472
+ """
473
+
474
+ model_config = ConfigDict(extra="allow")
475
+
476
+ referenceNumber: Optional[str] = None
477
+ responseCode: Optional[int] = None
478
+ responseCategoryCode: Optional[int] = None
479
+ message: Optional[str] = None
480
+ destinationAccountHolderNameAtBank: Optional[str] = None
481
+ fee: Optional[float] = None
482
+ vat: Optional[float] = None
483
+
484
+
485
+ # --------------------------------------------------------------------------- #
486
+ # Status lookups
487
+ # --------------------------------------------------------------------------- #
488
+
489
+
490
+ class TransactionStatusResponse(BaseModel):
491
+ """Response returned when checking a transaction's status.
492
+
493
+ Covers the last 48 hours only. ``status`` is human-readable and may be
494
+ reworded at any time — branch on ``responseCode``, never on ``status``.
495
+ """
496
+
497
+ model_config = ConfigDict(extra="allow")
498
+
499
+ referenceNumber: Optional[str] = None
500
+ responseCode: Optional[int] = None
501
+ responseCategoryCode: Optional[int] = None
502
+ message: Optional[str] = None
503
+ status: Optional[str] = None
504
+ transactionId: Optional[str] = None
505
+ transactionReference: Optional[str] = None
506
+ transactionType: Optional[str] = None
507
+ dateUTC: Optional[int] = None
508
+ amount: Optional[float] = None
509
+ currency: Optional[str] = None
510
+ merchantTransactionReference: Optional[str] = None
511
+ additionalProperties: Optional[Dict[str, Any]] = None
512
+ reversalId: Optional[str] = None
513
+ exchangeRate: Optional[float] = None
514
+ fee: Optional[float] = None
515
+ integrationStatus: Optional[str] = None
516
+ commissionEarned: Optional[float] = None
517
+
518
+
519
+ class RecentTransaction(BaseModel):
520
+ """A single transaction on the business account."""
521
+
522
+ model_config = ConfigDict(extra="allow")
523
+
524
+ itemNumber: Optional[int] = None
525
+ dateUTC: Optional[int] = None
526
+ description: Optional[str] = None
527
+ amount: Optional[float] = None
528
+ status: Optional[str] = None
529
+ transactionId: Optional[str] = None
530
+ referenceNumber: Optional[str] = None
531
+ currency: Optional[str] = None
532
+ exchangeRate: Optional[float] = None
533
+
534
+
535
+ class RecentTransactionsResponse(BaseModel):
536
+ """Response returned when listing the five most recent transactions."""
537
+
538
+ model_config = ConfigDict(extra="allow")
539
+
540
+ referenceNumber: Optional[str] = None
541
+ responseCode: Optional[int] = None
542
+ message: Optional[str] = None
543
+ recordCount: Optional[int] = None
544
+ currency: Optional[str] = None
545
+ items: List[RecentTransaction] = Field(default_factory=list)
546
+
547
+
548
+ class RefundStatusResponse(BaseModel):
549
+ """Response returned when checking whether a payment request was refunded.
550
+
551
+ Call with the **original payment request's** ``referenceNumber``.
552
+ ``data.refundStatus`` becomes ``"refunded"`` once the refund is made.
553
+ """
554
+
555
+ model_config = ConfigDict(extra="allow")
556
+
557
+ referenceNumber: Optional[str] = None
558
+ statusCode: Optional[str] = None
559
+ statusMessage: Optional[str] = None
560
+ data: Optional[PaymentStatusData] = None
561
+
562
+ @property
563
+ def refundStatus(self) -> Optional[str]:
564
+ """The refund status of the underlying payment request."""
565
+ return self.data.refundStatus if self.data is not None else None
566
+
567
+ @property
568
+ def isRefunded(self) -> bool:
569
+ """Whether the payment request has been refunded."""
570
+ return (self.refundStatus or "").strip().lower() == "refunded"
571
+
572
+
573
+ # --------------------------------------------------------------------------- #
574
+ # Callback payloads
575
+ # --------------------------------------------------------------------------- #
576
+
577
+
578
+ class MoneyTransferNotification(BaseModel):
579
+ """Notification Paga sends when a money transfer is processed.
580
+
581
+ Operation: Money transfer - Handle the notification.
582
+
583
+ Sent to your ``statusCallbackUrl`` once a transfer is processed. Paga
584
+ retries until you answer HTTP 200 with ``{"status": "SUCCESS"}``, so
585
+ de-duplicate on ``referenceNumber``.
586
+ """
587
+
588
+ model_config = ConfigDict(extra="allow")
589
+
590
+ responseCode: Optional[int] = None
591
+ responseCategoryCode: Optional[int] = None
592
+ message: Optional[str] = None
593
+ referenceNumber: Optional[str] = None
594
+ transactionId: Optional[str] = None
595
+ transactionReference: Optional[str] = None
596
+ transactionType: Optional[str] = None
597
+ transactionDate: Optional[str] = None
598
+ amount: Optional[str] = None
599
+ currency: Optional[str] = None
600
+ fee: Optional[float] = None
601
+ vat: Optional[float] = None
602
+ sessionId: Optional[str] = None
603
+ destinationAccountHolderNameAtBank: Optional[str] = None
604
+ reversalId: Optional[str] = None
605
+ exchangeRate: Optional[float] = None
606
+ integrationStatus: Optional[str] = None
607
+
608
+
609
+ class UsdPaymentWebhook(BaseModel):
610
+ """Webhook Paga sends for a USD (ACH, Wire, Swift) payment.
611
+
612
+ Operation: Bank transfer (ACH, Wire and Swift) - Handle the webhook.
613
+
614
+ This webhook carries **no signature** — there is no hash to verify.
615
+ Authenticate it at the transport layer (TLS plus, ideally, an allow-listed
616
+ source IP) and de-duplicate on ``referenceNumber`` + ``paymentId``.
617
+ """
618
+
619
+ model_config = ConfigDict(extra="allow")
620
+
621
+ event: Optional[str] = None
622
+ referenceNumber: Optional[str] = None
623
+ paymentId: Optional[str] = None
624
+ paymentStatus: Optional[str] = None
625
+ receivedAmounts: Optional[Dict[str, Any]] = None
626
+ serviceDetails: Optional[Dict[str, Any]] = None
627
+ errorCode: Optional[str] = None
628
+ errorMessage: Optional[Dict[str, Any]] = None
629
+
630
+ @property
631
+ def isCaptured(self) -> bool:
632
+ """Whether the dollar payment cleared."""
633
+ return (self.event or "").strip().upper() == "CAPTURED"
634
+
635
+ @property
636
+ def isFundingFailed(self) -> bool:
637
+ """Whether the dollar payment failed to clear."""
638
+ return (self.event or "").strip().upper() == "FUNDING_FAILED"
639
+
640
+
641
+ # --------------------------------------------------------------------------- #
642
+ # Direct Debit (Open Banking)
643
+ # --------------------------------------------------------------------------- #
644
+
645
+
646
+ class DirectDebitSessionMetadata(BaseModel):
647
+ """Metadata describing a hosted Direct Debit set-up session."""
648
+
649
+ model_config = ConfigDict(extra="allow")
650
+
651
+ amountLimit: Optional[float] = None
652
+ authorizationAmount: Optional[float] = None
653
+ currency: Optional[str] = None
654
+ accountReference: Optional[str] = None
655
+ allowPartialPayment: Optional[bool] = None
656
+ allowMultipleUse: Optional[bool] = None
657
+
658
+
659
+ class DirectDebitSessionData(BaseModel):
660
+ """The set-up session Paga created for you to redirect the customer to."""
661
+
662
+ model_config = ConfigDict(extra="allow")
663
+
664
+ referenceNumber: Optional[str] = None
665
+ sessionKey: Optional[str] = None
666
+ status: Optional[str] = None
667
+ checkoutUrl: Optional[str] = None
668
+ redirectUrl: Optional[str] = None
669
+ callbackUrl: Optional[str] = None
670
+ enabledPaymentMethods: List[str] = Field(default_factory=list)
671
+ initiatedAt: Optional[str] = None
672
+ sessionExpiresAt: Optional[str] = None
673
+ paymentExpiresAt: Optional[str] = None
674
+ metadata: Optional[DirectDebitSessionMetadata] = None
675
+
676
+
677
+ class DirectDebitSessionResponse(BaseModel):
678
+ """Response returned when starting a hosted Direct Debit set-up session."""
679
+
680
+ model_config = ConfigDict(extra="allow")
681
+
682
+ statusCode: Optional[str] = None
683
+ statusMessage: Optional[str] = None
684
+ data: Optional[DirectDebitSessionData] = None
685
+
686
+ @property
687
+ def checkoutUrl(self) -> Optional[str]:
688
+ """Where to redirect the customer to complete the mandate set-up."""
689
+ return self.data.checkoutUrl if self.data is not None else None
690
+
691
+
692
+ class MandateProcess(BaseModel):
693
+ """A single mandate in a mandate status response."""
694
+
695
+ model_config = ConfigDict(extra="allow")
696
+
697
+ ProcessStatusId: Optional[str] = None
698
+ AccountReference: Optional[str] = None
699
+ StatusMessage: Optional[str] = None
700
+ CreatedDateTimeUTC: Optional[str] = None
701
+
702
+
703
+ class MandateAdditionalData(BaseModel):
704
+ """The ``additionalData`` block of a mandate status response."""
705
+
706
+ model_config = ConfigDict(extra="allow")
707
+
708
+ mandate: List[MandateProcess] = Field(default_factory=list)
709
+
710
+
711
+ class MandateStatusData(BaseModel):
712
+ """The ``data`` block of a mandate status response."""
713
+
714
+ model_config = ConfigDict(extra="allow")
715
+
716
+ referenceNumber: Optional[str] = None
717
+ statusCode: Optional[str] = None
718
+ statusMessage: Optional[str] = None
719
+ requestAmount: Optional[float] = None
720
+ totalPaymentAmount: Optional[float] = None
721
+ paymentMethods: List[CollectPaymentMethodResult] = Field(default_factory=list)
722
+ expiryDateTimeUTC: Optional[str] = None
723
+ isPayerPagaAccountHolder: Optional[bool] = None
724
+ additionalData: Optional[MandateAdditionalData] = None
725
+
726
+
727
+ class MandateStatusResponse(BaseModel):
728
+ """Response returned when checking a mandate's status.
729
+
730
+ ``data.statusCode`` stays ``"1"`` / ``"pending"`` forever, so it tells
731
+ you nothing. Read ``data.additionalData.mandate[].ProcessStatusId``
732
+ instead — ``PENDING``, ``VERIFIED``, ``APPROVED`` or ``REJECTED``. Charge
733
+ only when it is ``APPROVED``.
734
+ """
735
+
736
+ model_config = ConfigDict(extra="allow")
737
+
738
+ referenceNumber: Optional[str] = None
739
+ statusCode: Optional[str] = None
740
+ statusMessage: Optional[str] = None
741
+ data: Optional[MandateStatusData] = None
742
+
743
+ @property
744
+ def mandateStatus(self) -> Optional[str]:
745
+ """The mandate's ``ProcessStatusId``, if Paga reported one."""
746
+ data = self.data
747
+ if data is None or data.additionalData is None:
748
+ return None
749
+ mandates = data.additionalData.mandate
750
+ if not mandates:
751
+ return None
752
+ return mandates[0].ProcessStatusId
753
+
754
+ @property
755
+ def isApproved(self) -> bool:
756
+ """Whether the mandate may be charged."""
757
+ return (self.mandateStatus or "").strip().upper() == "APPROVED"
758
+
759
+
760
+ class ChargeMandateResponse(BaseModel):
761
+ """Response returned when charging a mandate.
762
+
763
+ A success here means the charge was **accepted**, not completed. Fulfil
764
+ only once the charge callback confirms it.
765
+ """
766
+
767
+ model_config = ConfigDict(extra="allow")
768
+
769
+ referenceNumber: Optional[str] = None
770
+ statusCode: Optional[str] = None
771
+ statusMessage: Optional[str] = None
772
+
773
+
774
+ class ChargeMandateStatusData(BaseModel):
775
+ """The ``data`` block of a charge status response.
776
+
777
+ Paga capitalises these keys, so they are kept verbatim.
778
+ """
779
+
780
+ model_config = ConfigDict(extra="allow")
781
+
782
+ statusCode: Optional[int] = None
783
+ ReferenceNumber: Optional[str] = None
784
+ Amount: Optional[float] = None
785
+ ProcessStatusId: Optional[str] = None
786
+
787
+
788
+ class ChargeMandateStatusResponse(BaseModel):
789
+ """Response returned when checking a mandate charge's status.
790
+
791
+ ``data.statusCode`` is ``0`` charged, ``1`` pending, ``-1`` invalid (wrong
792
+ details, expired, or limit exceeded) and ``-4`` unknown.
793
+ """
794
+
795
+ model_config = ConfigDict(extra="allow")
796
+
797
+ statusCode: Optional[str] = None
798
+ statusMessage: Optional[str] = None
799
+ data: Optional[ChargeMandateStatusData] = None
800
+
801
+ @property
802
+ def chargeStatus(self) -> Optional[int]:
803
+ """The charge's own status code, when Paga reported one."""
804
+ return self.data.statusCode if self.data is not None else None
805
+
806
+
807
+ class DisableMandateResponse(BaseModel):
808
+ """Response returned when disabling a mandate.
809
+
810
+ Afterwards the mandate's ``ProcessStatusId`` becomes ``REJECTED`` and it
811
+ can never be charged again.
812
+ """
813
+
814
+ model_config = ConfigDict(extra="allow")
815
+
816
+ statusCode: Optional[str] = None
817
+ statusMessage: Optional[str] = None
818
+ referenceNumber: Optional[str] = None
819
+ data: Optional[Any] = None
820
+
821
+
822
+ # --------------------------------------------------------------------------- #
823
+ # Persistent payment accounts and customers
824
+ # --------------------------------------------------------------------------- #
825
+
826
+
827
+ class PersistentPaymentAccountResponse(BaseModel):
828
+ """Response returned for a persistent payment account operation."""
829
+
830
+ model_config = ConfigDict(extra="allow")
831
+
832
+ referenceNumber: Optional[str] = None
833
+ statusCode: Optional[str] = None
834
+ statusMessage: Optional[str] = None
835
+ responseCode: Optional[int] = None
836
+ message: Optional[str] = None
837
+ accountNumber: Optional[str] = None
838
+ accountReference: Optional[str] = None
839
+ financialIdentificationNumber: Optional[str] = None
840
+ creditBankId: Optional[str] = None
841
+ creditBankAccountNumber: Optional[str] = None
842
+ callbackUrl: Optional[str] = None
843
+ status: Optional[str] = None
844
+ balance: Optional[float] = None
845
+ currency: Optional[str] = None
846
+
847
+
848
+ class CustomerResponse(BaseModel):
849
+ """Response returned when registering a customer."""
850
+
851
+ model_config = ConfigDict(extra="allow")
852
+
853
+ referenceNumber: Optional[str] = None
854
+ responseCode: Optional[int] = None
855
+ responseCategoryCode: Optional[int] = None
856
+ message: Optional[str] = None
857
+ customerReference: Optional[str] = None
858
+ customerPhoneNumber: Optional[str] = None
859
+ customerFirstName: Optional[str] = None
860
+ customerLastName: Optional[str] = None
861
+ customerEmail: Optional[str] = None
862
+ customerDateOfBirth: Optional[str] = None
863
+ customerAddress: Optional[str] = None
864
+ status: Optional[str] = None
865
+
866
+
867
+ class MoneyTransferItem(BaseModel):
868
+ """One item in a bulk money transfer."""
869
+
870
+ model_config = ConfigDict(extra="allow")
871
+
872
+ referenceNumber: Optional[str] = None
873
+ amount: Optional[str] = None
874
+ destinationAccount: Optional[str] = None
875
+ remarks: Optional[str] = None
876
+ currency: Optional[str] = None
877
+
878
+
879
+ class BulkTransferResult(BaseModel):
880
+ """The outcome of one item in a bulk money transfer."""
881
+
882
+ model_config = ConfigDict(extra="allow")
883
+
884
+ referenceNumber: Optional[str] = None
885
+ responseCode: Optional[int] = None
886
+ message: Optional[str] = None
887
+ transactionId: Optional[str] = None
888
+ withdrawalCode: Optional[str] = None
889
+ exchangeRate: Optional[float] = None
890
+ fee: Optional[float] = None
891
+ currency: Optional[str] = None
892
+ receiverRegistrationStatus: Optional[str] = None
893
+
894
+
895
+ class BulkMoneyTransferResponse(BaseModel):
896
+ """Response returned when sending a bulk money transfer.
897
+
898
+ ``responseCode`` ``1`` means the bulk partially succeeded: some items
899
+ moved and some did not. Check each entry in ``results``.
900
+ """
901
+
902
+ model_config = ConfigDict(extra="allow")
903
+
904
+ bulkReferenceNumber: Optional[str] = None
905
+ responseCode: Optional[int] = None
906
+ message: Optional[str] = None
907
+ results: List[BulkTransferResult] = Field(default_factory=list)
908
+
909
+
910
+ class MoneyTransferResponse(BaseModel):
911
+ """Response returned when sending money to a Paga wallet."""
912
+
913
+ model_config = ConfigDict(extra="allow")
914
+
915
+ referenceNumber: Optional[str] = None
916
+ responseCode: Optional[int] = None
917
+ responseCategoryCode: Optional[int] = None
918
+ message: Optional[str] = None
919
+ withdrawalCode: Optional[str] = None
920
+ transactionId: Optional[str] = None
921
+ reversalId: Optional[str] = None
922
+ currency: Optional[str] = None
923
+ exchangeRate: Optional[float] = None
924
+ fee: Optional[float] = None
925
+ receiverRegistrationStatus: Optional[str] = None
926
+ recipientAccountHolderName: Optional[str] = None
927
+
928
+
929
+ class ValidateMoneyTransferResponse(BaseModel):
930
+ """Response returned when validating a money transfer to a Paga wallet."""
931
+
932
+ model_config = ConfigDict(extra="allow")
933
+
934
+ referenceNumber: Optional[str] = None
935
+ responseCode: Optional[int] = None
936
+ message: Optional[str] = None
937
+ fee: Optional[float] = None
938
+ vat: Optional[float] = None
939
+ recipientAccountHolderName: Optional[str] = None
940
+ recipientRegistrationStatus: Optional[str] = None
941
+ recipientKYCLevel: Optional[str] = None
942
+
943
+
944
+ class OperationStatusResponse(BaseModel):
945
+ """Response returned when checking an operation's status.
946
+
947
+ Note the field is ``transactionStatus``, not ``status``.
948
+ """
949
+
950
+ model_config = ConfigDict(extra="allow")
951
+
952
+ referenceNumber: Optional[str] = None
953
+ responseCode: Optional[Union[int, str]] = None
954
+ transactionStatus: Optional[str] = None
955
+ message: Optional[str] = None
956
+ transactionId: Optional[str] = None
957
+ fee: Optional[float] = None
958
+
959
+
960
+ class OnboardMerchantCredentials(BaseModel):
961
+ """The credentials Paga issues for an onboarded merchant."""
962
+
963
+ model_config = ConfigDict(extra="allow")
964
+
965
+ merchantPublicId: Optional[str] = None
966
+ merchantSecretKey: Optional[str] = None
967
+ merchantHmac: Optional[str] = None
968
+
969
+
970
+ class OnboardMerchantUpdate(BaseModel):
971
+ """The onboarding outcome for a merchant."""
972
+
973
+ model_config = ConfigDict(extra="allow")
974
+
975
+ status: Optional[str] = None
976
+ credentials: Optional[OnboardMerchantCredentials] = None
977
+
978
+
979
+ class OnboardMerchantResponse(BaseModel):
980
+ """Response returned when onboarding a merchant.
981
+
982
+ Aggregators only.
983
+ """
984
+
985
+ model_config = ConfigDict(extra="allow")
986
+
987
+ responseCode: Optional[int] = None
988
+ message: Optional[str] = None
989
+ onboardingUpdate: Optional[OnboardMerchantUpdate] = None
990
+
991
+
992
+ class DispenseCashResponse(BaseModel):
993
+ """Response returned when dispensing cash against a withdrawal code."""
994
+
995
+ model_config = ConfigDict(extra="allow")
996
+
997
+ responseCode: Optional[int] = None
998
+ message: Optional[str] = None
999
+ transactionId: Optional[str] = None
1000
+ agentCommission: Optional[float] = None
1001
+ customerName: Optional[str] = None