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 ADDED
@@ -0,0 +1,206 @@
1
+ """Async Python SDK for the Paga Engine API."""
2
+
3
+ from .auth import PAYMENT_REQUEST_FULL_HASH_FIELDS
4
+ from .client import (
5
+ DEFAULT_CHECKOUT_LIVE_BASE_URL,
6
+ DEFAULT_CHECKOUT_TEST_BASE_URL,
7
+ DEFAULT_COLLECT_LIVE_BASE_URL,
8
+ DEFAULT_COLLECT_TEST_BASE_URL,
9
+ PagaClient,
10
+ )
11
+ from .codes import (
12
+ BusinessErrorCode,
13
+ ChargeStatusCode,
14
+ CollectStatusCode,
15
+ MandateProcessStatus,
16
+ MandateStatusCode,
17
+ PaymentRequestState,
18
+ )
19
+ from .exceptions import (
20
+ PagaAPIError,
21
+ PagaAuthenticationError,
22
+ PagaError,
23
+ PagaRateLimitError,
24
+ )
25
+ from .models import (
26
+ AccountBalanceResponse,
27
+ Bank,
28
+ BanksResponse,
29
+ BulkMoneyTransferResponse,
30
+ BulkTransferResult,
31
+ ChargeMandateResponse,
32
+ ChargeMandateStatusData,
33
+ ChargeMandateStatusResponse,
34
+ CheckoutVerifyChargeResponse,
35
+ CollectBank,
36
+ CollectBanksResponse,
37
+ CollectPaymentMethodResult,
38
+ CollectPaymentRequestResponse,
39
+ CustomerResponse,
40
+ DataBundle,
41
+ DataBundlesResponse,
42
+ DepositToBankResponse,
43
+ DisableMandateResponse,
44
+ DirectDebitSessionData,
45
+ DirectDebitSessionMetadata,
46
+ DirectDebitSessionResponse,
47
+ DispenseCashResponse,
48
+ MandateAdditionalData,
49
+ MandateProcess,
50
+ MandateStatusData,
51
+ MandateStatusResponse,
52
+ Merchant,
53
+ MerchantAccountDetailsResponse,
54
+ MerchantPaymentResponse,
55
+ MerchantsResponse,
56
+ MerchantService,
57
+ MerchantServicesResponse,
58
+ MobileOperator,
59
+ MobileOperatorsResponse,
60
+ MoneyTransferItem,
61
+ MoneyTransferNotification,
62
+ MoneyTransferResponse,
63
+ OnboardMerchantCredentials,
64
+ OnboardMerchantResponse,
65
+ OnboardMerchantUpdate,
66
+ OperationStatusResponse,
67
+ PagaPaymentCallback,
68
+ PagaResponse,
69
+ PaymentStatusData,
70
+ PaymentStatusResponse,
71
+ PersistentPaymentAccountResponse,
72
+ PurchaseResponse,
73
+ RecentTransaction,
74
+ RecentTransactionsResponse,
75
+ RefundResponse,
76
+ RefundStatusResponse,
77
+ SubsidiaryAccountResponse,
78
+ SubsidiaryBalanceResponse,
79
+ SubsidiaryHistoryResponse,
80
+ SubsidiaryMoneyResponse,
81
+ SubsidiaryTransferResponse,
82
+ TransactionHistoryResponse,
83
+ TransactionItem,
84
+ TransactionStatusResponse,
85
+ UsdPaymentWebhook,
86
+ ValidateDepositToBankResponse,
87
+ ValidateMoneyTransferResponse,
88
+ )
89
+ from .outcome import OperationOutcome, classify, is_unknown_outcome
90
+ from .webhooks import (
91
+ parse_hash_parameters,
92
+ parse_money_transfer_notification,
93
+ parse_payment_callback,
94
+ parse_usd_payment_webhook,
95
+ verify_charge_callback,
96
+ verify_checkout_notification,
97
+ verify_funding_notification,
98
+ verify_hash,
99
+ verify_hash_header,
100
+ verify_mandate_callback,
101
+ verify_money_transfer_notification,
102
+ verify_payment_callback,
103
+ verify_persistent_payment_account_callback,
104
+ verify_subsidiary_operation,
105
+ )
106
+
107
+ __version__ = "0.1.0"
108
+
109
+ __all__ = [
110
+ "AccountBalanceResponse",
111
+ "Bank",
112
+ "BanksResponse",
113
+ "BulkMoneyTransferResponse",
114
+ "BulkTransferResult",
115
+ "BusinessErrorCode",
116
+ "ChargeMandateResponse",
117
+ "ChargeMandateStatusData",
118
+ "ChargeMandateStatusResponse",
119
+ "ChargeStatusCode",
120
+ "CollectBank",
121
+ "CollectBanksResponse",
122
+ "CollectStatusCode",
123
+ "CustomerResponse",
124
+ "DataBundle",
125
+ "DataBundlesResponse",
126
+ "DEFAULT_CHECKOUT_LIVE_BASE_URL",
127
+ "DEFAULT_CHECKOUT_TEST_BASE_URL",
128
+ "DEFAULT_COLLECT_LIVE_BASE_URL",
129
+ "DEFAULT_COLLECT_TEST_BASE_URL",
130
+ "CheckoutVerifyChargeResponse",
131
+ "CollectPaymentMethodResult",
132
+ "CollectPaymentRequestResponse",
133
+ "DepositToBankResponse",
134
+ "DisableMandateResponse",
135
+ "DirectDebitSessionData",
136
+ "DirectDebitSessionMetadata",
137
+ "DirectDebitSessionResponse",
138
+ "DispenseCashResponse",
139
+ "MandateAdditionalData",
140
+ "MandateProcess",
141
+ "MandateProcessStatus",
142
+ "MandateStatusCode",
143
+ "MandateStatusData",
144
+ "MandateStatusResponse",
145
+ "Merchant",
146
+ "MerchantAccountDetailsResponse",
147
+ "MerchantPaymentResponse",
148
+ "MerchantService",
149
+ "MerchantServicesResponse",
150
+ "MerchantsResponse",
151
+ "MobileOperator",
152
+ "MobileOperatorsResponse",
153
+ "MoneyTransferItem",
154
+ "MoneyTransferNotification",
155
+ "MoneyTransferResponse",
156
+ "OnboardMerchantCredentials",
157
+ "OnboardMerchantResponse",
158
+ "OnboardMerchantUpdate",
159
+ "OperationOutcome",
160
+ "OperationStatusResponse",
161
+ "PAYMENT_REQUEST_FULL_HASH_FIELDS",
162
+ "PagaAPIError",
163
+ "PagaAuthenticationError",
164
+ "PagaClient",
165
+ "PagaError",
166
+ "PagaPaymentCallback",
167
+ "PagaRateLimitError",
168
+ "PagaResponse",
169
+ "PaymentRequestState",
170
+ "PaymentStatusData",
171
+ "PaymentStatusResponse",
172
+ "PersistentPaymentAccountResponse",
173
+ "PurchaseResponse",
174
+ "RecentTransaction",
175
+ "RecentTransactionsResponse",
176
+ "RefundResponse",
177
+ "RefundStatusResponse",
178
+ "SubsidiaryAccountResponse",
179
+ "SubsidiaryBalanceResponse",
180
+ "SubsidiaryHistoryResponse",
181
+ "SubsidiaryMoneyResponse",
182
+ "SubsidiaryTransferResponse",
183
+ "TransactionHistoryResponse",
184
+ "TransactionItem",
185
+ "TransactionStatusResponse",
186
+ "UsdPaymentWebhook",
187
+ "ValidateDepositToBankResponse",
188
+ "ValidateMoneyTransferResponse",
189
+ "__version__",
190
+ "classify",
191
+ "is_unknown_outcome",
192
+ "parse_hash_parameters",
193
+ "parse_money_transfer_notification",
194
+ "parse_payment_callback",
195
+ "parse_usd_payment_webhook",
196
+ "verify_charge_callback",
197
+ "verify_checkout_notification",
198
+ "verify_funding_notification",
199
+ "verify_hash",
200
+ "verify_hash_header",
201
+ "verify_mandate_callback",
202
+ "verify_money_transfer_notification",
203
+ "verify_payment_callback",
204
+ "verify_persistent_payment_account_callback",
205
+ "verify_subsidiary_operation",
206
+ ]
paga/actions.py ADDED
@@ -0,0 +1,246 @@
1
+ """Action operations for the Paga Engine API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Dict, List, Optional
6
+
7
+ from .auth import (
8
+ AIRTIME_HASH_FIELDS,
9
+ BILL_PAYMENT_HASH_FIELDS,
10
+ MONEY_TRANSFER_HASH_FIELDS,
11
+ REFUND_HASH_FIELDS,
12
+ )
13
+ from .models import (
14
+ DepositToBankResponse,
15
+ MerchantPaymentResponse,
16
+ PagaResponse,
17
+ PurchaseResponse,
18
+ RefundResponse,
19
+ )
20
+
21
+
22
+ class ActionMixin:
23
+ """Action operations: refunds, money transfers, airtime and bill payments."""
24
+
25
+ async def refund_payment(
26
+ self,
27
+ *,
28
+ reference_number: str,
29
+ payment_request_reference: str,
30
+ refund_amount: float,
31
+ currency: str = "NGN",
32
+ reason: Optional[str] = None,
33
+ ) -> RefundResponse:
34
+ """Refund or cancel a payment request.
35
+
36
+ Operation: Refunds - Refund or cancel a payment request.
37
+
38
+ Refunds a paid payment request in full or in part, or cancels one that
39
+ has not been paid. Send one request per partial refund, each with its
40
+ own ``reference_number``. Reusing a ``reference_number`` returns status
41
+ code ``102`` and never refunds twice.
42
+
43
+ Args:
44
+ reference_number: Your unique reference for this refund.
45
+ payment_request_reference: The ``reference_number`` of the original
46
+ payment request.
47
+ refund_amount: Amount to refund.
48
+ currency: Transaction currency. Defaults to ``"NGN"``.
49
+ reason: Optional refund reason.
50
+
51
+ Returns:
52
+ The parsed :class:`RefundResponse`.
53
+ """
54
+ payload: Dict[str, Any] = {
55
+ "referenceNumber": reference_number,
56
+ "paymentRequestReference": payment_request_reference,
57
+ "refundAmount": refund_amount,
58
+ "currency": currency,
59
+ }
60
+ if reason is not None:
61
+ payload["reason"] = reason
62
+ response = await self._request(
63
+ "POST",
64
+ "/refund/v2",
65
+ payload,
66
+ use_hash=True,
67
+ use_basic=True,
68
+ hash_fields=REFUND_HASH_FIELDS,
69
+ )
70
+ return RefundResponse.model_validate(response.model_dump())
71
+
72
+ async def send_money(
73
+ self,
74
+ *,
75
+ reference_number: str,
76
+ amount: str,
77
+ destination_bank_uuid: str,
78
+ destination_bank_account_number: str,
79
+ currency: str = "NGN",
80
+ remarks: Optional[str] = None,
81
+ status_callback_url: Optional[str] = None,
82
+ ) -> DepositToBankResponse:
83
+ """Send money from the business balance to a bank account or Paga wallet.
84
+
85
+ Operation: Money transfer - Send the money.
86
+
87
+ Sends money from the business balance to a bank account, or to a Paga
88
+ wallet (using Paga's UUID ``AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA``).
89
+
90
+ Args:
91
+ reference_number: Your unique transfer reference.
92
+ amount: Amount to send (e.g. ``"5000.00"``).
93
+ destination_bank_uuid: The bank's UUID from get banks, or Paga's UUID
94
+ for a wallet.
95
+ destination_bank_account_number: Destination bank account number.
96
+ currency: Transaction currency. Defaults to ``"NGN"``.
97
+ remarks: Optional transfer remarks.
98
+ status_callback_url: Where Paga notifies once the transfer is processed. Optional.
99
+
100
+ Returns:
101
+ The parsed :class:`DepositToBankResponse`.
102
+ """
103
+ payload: Dict[str, Any] = {
104
+ "referenceNumber": reference_number,
105
+ "amount": amount,
106
+ "currency": currency,
107
+ "destinationBankUUID": destination_bank_uuid,
108
+ "destinationBankAccountNumber": destination_bank_account_number,
109
+ }
110
+ if remarks is not None:
111
+ payload["remarks"] = remarks
112
+ if status_callback_url is not None:
113
+ payload["statusCallbackUrl"] = status_callback_url
114
+ response = await self._request(
115
+ "POST",
116
+ "/depositToBank",
117
+ payload,
118
+ use_hash=True,
119
+ use_basic=False,
120
+ base_url=self.business_base_url,
121
+ hash_fields=MONEY_TRANSFER_HASH_FIELDS,
122
+ raise_on_error=False,
123
+ )
124
+ return DepositToBankResponse.model_validate(response.model_dump())
125
+
126
+ async def buy_airtime(
127
+ self,
128
+ *,
129
+ reference_number: str,
130
+ amount: str,
131
+ destination_phone_number: str,
132
+ mobile_operator_public_id: str,
133
+ currency: str = "NGN",
134
+ is_data_bundle: bool = False,
135
+ mobile_operator_service_id: Optional[str] = None,
136
+ is_suppress_recipient_messages: bool = False,
137
+ ) -> PurchaseResponse:
138
+ """Buy airtime or data.
139
+
140
+ Operation: Airtime and data - Buy the airtime or data.
141
+
142
+ Tops up a phone with airtime or data from the business balance. There
143
+ is no callback: decide on ``responseCode``, and check the transaction
144
+ status if needed.
145
+
146
+ Args:
147
+ reference_number: Your unique airtime purchase reference.
148
+ amount: Airtime value, or exactly the bundle's ``servicePrice`` for data.
149
+ destination_phone_number: Phone number to credit.
150
+ mobile_operator_public_id: The network's mobile operator public id.
151
+ currency: Transaction currency. Defaults to ``"NGN"``.
152
+ is_data_bundle: Whether this is a data bundle purchase. Defaults to ``False``.
153
+ mobile_operator_service_id: Data only. The bundle's ``serviceId``.
154
+ is_suppress_recipient_messages: Whether to suppress recipient messages.
155
+
156
+ Returns:
157
+ The parsed :class:`PurchaseResponse`.
158
+ """
159
+ payload: Dict[str, Any] = {
160
+ "referenceNumber": reference_number,
161
+ "amount": amount,
162
+ "destinationPhoneNumber": destination_phone_number,
163
+ "mobileOperatorPublicId": mobile_operator_public_id,
164
+ "currency": currency,
165
+ "isDataBundle": is_data_bundle,
166
+ }
167
+ if mobile_operator_service_id is not None:
168
+ payload["mobileOperatorServiceId"] = mobile_operator_service_id
169
+ if is_suppress_recipient_messages:
170
+ payload["isSuppressRecipientMessages"] = True
171
+
172
+ response = await self._request(
173
+ "POST",
174
+ "/airtimePurchase",
175
+ payload,
176
+ use_hash=True,
177
+ use_basic=False,
178
+ base_url=self.business_base_url,
179
+ hash_fields=AIRTIME_HASH_FIELDS,
180
+ raise_on_error=False,
181
+ )
182
+ return PurchaseResponse.model_validate(response.model_dump())
183
+
184
+ async def pay_bill(
185
+ self,
186
+ *,
187
+ reference_number: str,
188
+ amount: float,
189
+ merchant_account: str,
190
+ merchant_reference_number: str,
191
+ merchant_service: Optional[List[str]] = None,
192
+ currency: str = "NGN",
193
+ payment_channel: Optional[str] = None,
194
+ locale: Optional[str] = None,
195
+ merchant_service_product_code: Optional[str] = None,
196
+ ) -> MerchantPaymentResponse:
197
+ """Pay a bill from the business balance.
198
+
199
+ Operation: Bill payment - Pay the bill.
200
+
201
+ Pays a bill from the business balance. There is no callback: decide on
202
+ ``responseCode``. ``integrationStatus`` is for information only.
203
+
204
+ Args:
205
+ reference_number: Your unique bill payment reference.
206
+ amount: Bill amount.
207
+ merchant_account: The biller's UUID. From the biller lookup.
208
+ merchant_reference_number: The customer's account / meter /
209
+ smart card / account number at the biller.
210
+ merchant_service: Optional chosen service code. Leave out for
211
+ billers with no services.
212
+ currency: Transaction currency. Defaults to ``"NGN"``.
213
+ payment_channel: Optional payment channel.
214
+ locale: Optional locale.
215
+ merchant_service_product_code: Optional chosen service code, as
216
+ returned by :meth:`get_merchant_services`.
217
+
218
+ Returns:
219
+ The parsed :class:`MerchantPaymentResponse`.
220
+ """
221
+ payload: Dict[str, Any] = {
222
+ "referenceNumber": reference_number,
223
+ "amount": amount,
224
+ "merchantAccount": merchant_account,
225
+ "merchantReferenceNumber": merchant_reference_number,
226
+ "currency": currency,
227
+ }
228
+ if merchant_service is not None:
229
+ payload["merchantService"] = merchant_service
230
+ if payment_channel is not None:
231
+ payload["paymentChannel"] = payment_channel
232
+ if locale is not None:
233
+ payload["locale"] = locale
234
+ if merchant_service_product_code is not None:
235
+ payload["merchantServiceProductCode"] = merchant_service_product_code
236
+ response = await self._request(
237
+ "POST",
238
+ "/merchantPayment",
239
+ payload,
240
+ use_hash=True,
241
+ use_basic=False,
242
+ base_url=self.business_base_url,
243
+ hash_fields=BILL_PAYMENT_HASH_FIELDS,
244
+ raise_on_error=False,
245
+ )
246
+ return MerchantPaymentResponse.model_validate(response.model_dump())