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/codes.py ADDED
@@ -0,0 +1,197 @@
1
+ """Paga status and error codes.
2
+
3
+ Paga exposes two different code vocabularies:
4
+
5
+ - The **Collect API** (payments, refunds, subsidiary accounts, Direct Debit)
6
+ reports a ``statusCode`` **string**. ``"0"`` means success.
7
+ - The **Business API** (money transfer, airtime, bill payment, business
8
+ account) reports a ``responseCode`` **integer**. ``0`` means success.
9
+
10
+ They are modelled separately because the same numeric value means different
11
+ things in each family: ``114`` is ``FAILED`` on Collect but
12
+ ``INVALID_ACCOUNT`` on Business.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from enum import Enum
18
+ from typing import Any, Mapping, Optional, Union
19
+
20
+ __all__ = [
21
+ "BusinessErrorCode",
22
+ "ChargeStatusCode",
23
+ "CollectStatusCode",
24
+ "MandateProcessStatus",
25
+ "MandateStatusCode",
26
+ "PaymentRequestState",
27
+ "as_mapping",
28
+ "resolve_business_code",
29
+ "resolve_collect_status",
30
+ ]
31
+
32
+
33
+ class CollectStatusCode(str, Enum):
34
+ """``statusCode`` values returned by the Collect API."""
35
+
36
+ SUCCESS = "0"
37
+ IN_PROCESS = "1"
38
+ PARTIAL_PAYMENT = "2"
39
+ SYSTEM_ERROR = "-1"
40
+ REQUEST_EXPIRED = "-2"
41
+ REQUEST_CANCELLED = "-3"
42
+ FAILED = "114"
43
+ FAILED_NON_REFUNDABLE = "115"
44
+ NOT_FOUND = "121"
45
+
46
+
47
+ class BusinessErrorCode(int, Enum):
48
+ """``responseCode`` values returned by the Business API."""
49
+
50
+ SUCCESS = 0
51
+ BULK_PARTIAL_SUCCESS = 1
52
+ BULK_ALL_FAILED = 2
53
+ PENDING = 3
54
+
55
+ UNKNOWN_ERROR = -1
56
+ UNSUPPORTED_OPERATION = -2
57
+
58
+ INVALID_ACCOUNT_NUMBER = 4
59
+
60
+ INVALID_BANK = 101
61
+ DISABLED_ACCOUNT = 103
62
+ INVALID_PRINCIPAL = 104
63
+ DUPLICATE_REFERENCE = 105
64
+ INVALID_RECIPIENT_ACCOUNT = 107
65
+ INVALID_ORGANISATION_USER = 108
66
+ AIRTIME_ERROR = 109
67
+ INVALID_ORGANISATION = 110
68
+ INVALID_CUSTOMER = 111
69
+ INVALID_BILLER = 112
70
+ INVALID_USER = 113
71
+ INVALID_ACCOUNT = 114
72
+ INVALID_BANK_ACCOUNT = 115
73
+ INVALID_AMOUNT = 116
74
+ MISSING_PARAMETER = 117
75
+ INVALID_USER_IDENTIFIER = 118
76
+ INVALID_PROCESS = 119
77
+ PHOTO_ALREADY_SET = 120
78
+ INVALID_IMAGE_TYPE = 121
79
+ INVALID_IDENTIFICATION_DETAILS = 122
80
+ INVALID_PHONE_NUMBER = 123
81
+ INVALID_FIRST_NAME = 124
82
+ INVALID_LAST_NAME = 125
83
+ INVALID_USERNAME = 126
84
+ INVALID_EMAIL = 127
85
+ EMAIL_ALREADY_EXISTS = 128
86
+ LOCKED_USER_ACCOUNT = 129
87
+ INVALID_NAME = 130
88
+ INVALID_MERCHANT = 131
89
+ INVALID_PROCESS_CHANNEL = 132
90
+ DESTINATION_BANK_NOT_FOUND = 133
91
+ INVALID_DATE_OF_BIRTH = 134
92
+ UNKNOWN_REFERENCE_NUMBER = 135
93
+ EXCEEDS_TRANSACTION_LIMIT = 136
94
+ BELOW_MINIMUM = 137
95
+ EXCEEDS_ACCOUNT_LIMIT = 138
96
+ INSUFFICIENT_BALANCE = 139
97
+ REFERENCE_NUMBER_TOO_LONG = 140
98
+
99
+
100
+ class MandateStatusCode(str, Enum):
101
+ """``statusCode`` values on a Direct Debit mandate callback."""
102
+
103
+ PENDING = "003"
104
+ VERIFIED = "004"
105
+ APPROVED = "0"
106
+ REJECTED = "005"
107
+ UNKNOWN = "006"
108
+ NOT_FOUND = "007"
109
+
110
+
111
+ class MandateProcessStatus(str, Enum):
112
+ """``ProcessStatusId`` values on a mandate.
113
+
114
+ This is the field to branch on. A mandate's ``data.statusCode`` stays
115
+ ``"1"`` / ``"pending"`` forever, so it tells you nothing.
116
+ """
117
+
118
+ PENDING = "PENDING"
119
+ VERIFIED = "VERIFIED"
120
+ APPROVED = "APPROVED"
121
+ REJECTED = "REJECTED"
122
+
123
+
124
+ class ChargeStatusCode(int, Enum):
125
+ """``data.statusCode`` values returned by ``/getChargeMandateStatus``."""
126
+
127
+ CHARGED = 0
128
+ PENDING = 1
129
+ INVALID = -1
130
+ UNKNOWN = -4
131
+
132
+
133
+ class PaymentRequestState(str, Enum):
134
+ """States a payment request moves through."""
135
+
136
+ PENDING = "PENDING"
137
+ CHARGEABLE = "CHARGEABLE"
138
+ CONSUMED = "CONSUMED"
139
+ EXPIRED = "EXPIRED"
140
+ FAILED = "FAILED"
141
+ CANCELLED = "CANCELLED"
142
+
143
+
144
+ def as_mapping(body: Any) -> Optional[Mapping[str, Any]]:
145
+ """Coerce a response body into a plain mapping.
146
+
147
+ Accepts a dict, or any pydantic model exposing ``model_dump()``.
148
+ Returns ``None`` when the body cannot be inspected.
149
+ """
150
+ if body is None:
151
+ return None
152
+ if isinstance(body, Mapping):
153
+ return body
154
+ dump = getattr(body, "model_dump", None)
155
+ if callable(dump):
156
+ try:
157
+ dumped = dump()
158
+ except Exception: # noqa: BLE001 - a broken model is not a code source
159
+ return None
160
+ if isinstance(dumped, Mapping):
161
+ return dumped
162
+ return None
163
+
164
+
165
+ def resolve_collect_status(body: Optional[Mapping[str, Any]]) -> Optional[CollectStatusCode]:
166
+ """Return the :class:`CollectStatusCode` carried by ``body``, if any.
167
+
168
+ Paga sends ``statusCode`` as a string, but some legacy responses send it
169
+ as an integer, so both are accepted.
170
+ """
171
+ body = as_mapping(body)
172
+ if body is None:
173
+ return None
174
+ raw = body.get("statusCode")
175
+ if raw is None:
176
+ return None
177
+ try:
178
+ return CollectStatusCode(str(raw))
179
+ except ValueError:
180
+ return None
181
+
182
+
183
+ def resolve_business_code(body: Optional[Mapping[str, Any]]) -> Optional[BusinessErrorCode]:
184
+ """Return the :class:`BusinessErrorCode` carried by ``body``, if any."""
185
+ body = as_mapping(body)
186
+ if body is None:
187
+ return None
188
+ raw = body.get("responseCode")
189
+ if raw is None:
190
+ return None
191
+ try:
192
+ return BusinessErrorCode(int(raw))
193
+ except (TypeError, ValueError):
194
+ return None
195
+
196
+
197
+ ResolvedCode = Union[CollectStatusCode, BusinessErrorCode, None]
paga/customer.py ADDED
@@ -0,0 +1,287 @@
1
+ """Customer registration and KYC operations for the Paga Engine API.
2
+
3
+ Registering a customer on the Business API is how you open an account for
4
+ someone. The plain registration takes the customer's details; the KYC
5
+ variants additionally take photographs, and are sent as
6
+ ``multipart/form-data``.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import Any, Dict, Optional
12
+
13
+ from .auth import (
14
+ CUSTOMER_ACCOUNT_PHOTO_HASH_FIELDS,
15
+ CUSTOMER_HASH_FIELDS,
16
+ CUSTOMER_IDENTIFICATION_HASH_FIELDS,
17
+ )
18
+ from .models import CustomerResponse
19
+
20
+ __all__ = ["CustomerMixin"]
21
+
22
+
23
+ class CustomerMixin:
24
+ """Customer registration and KYC operations."""
25
+
26
+ async def register_customer(
27
+ self,
28
+ *,
29
+ reference_number: str,
30
+ customer_phone_number: str,
31
+ customer_first_name: str,
32
+ customer_last_name: str,
33
+ customer_email: str,
34
+ customer_date_of_birth: str,
35
+ customer_address: Optional[Dict[str, Any]] = None,
36
+ customer_reference: Optional[str] = None,
37
+ ) -> CustomerResponse:
38
+ """Register a customer.
39
+
40
+ Operation: Business API - Register a customer.
41
+
42
+ Args:
43
+ reference_number: Your unique reference for this request.
44
+ customer_phone_number: The customer's phone number. It must not
45
+ already belong to a registered customer.
46
+ customer_first_name: The customer's first name.
47
+ customer_last_name: The customer's last name.
48
+ customer_email: The customer's email address.
49
+ customer_date_of_birth: The customer's date of birth, as
50
+ ``YYYY-MM-DD``.
51
+ customer_address: Optional address, as an object.
52
+ customer_reference: Optional reference you hold for the customer.
53
+
54
+ Returns:
55
+ The parsed :class:`CustomerResponse`.
56
+ """
57
+ payload: Dict[str, Any] = {
58
+ "referenceNumber": reference_number,
59
+ "customerPhoneNumber": customer_phone_number,
60
+ "customerFirstName": customer_first_name,
61
+ "customerLastName": customer_last_name,
62
+ "customerEmail": customer_email,
63
+ "customerDateOfBirth": customer_date_of_birth,
64
+ }
65
+ if customer_address is not None:
66
+ payload["customerAddress"] = customer_address
67
+ if customer_reference is not None:
68
+ payload["customerReference"] = customer_reference
69
+
70
+ response = await self._request(
71
+ "POST",
72
+ "/registerCustomer",
73
+ payload,
74
+ use_hash=True,
75
+ use_basic=False,
76
+ base_url=self.business_base_url,
77
+ hash_fields=CUSTOMER_HASH_FIELDS,
78
+ )
79
+ return CustomerResponse.model_validate(response.model_dump())
80
+
81
+ async def register_customer_with_kyc(
82
+ self,
83
+ *,
84
+ reference_number: str,
85
+ customer_phone_number: str,
86
+ customer_email: str,
87
+ customer_first_name: str,
88
+ customer_last_name: str,
89
+ customer_date_of_birth: str,
90
+ customer_gender: str,
91
+ customer_account_photo: bytes,
92
+ customer_id_photo: bytes,
93
+ customer_address: Optional[Dict[str, Any]] = None,
94
+ customer_marital_status: Optional[str] = None,
95
+ customer_preferred_language_iso_code: Optional[str] = None,
96
+ customer_id_type: Optional[str] = None,
97
+ customer_id_number: Optional[str] = None,
98
+ customer_id_expiration_date: Optional[str] = None,
99
+ optin_for_wallet_savings: Optional[bool] = None,
100
+ customer_reference: Optional[str] = None,
101
+ account_photo_filename: str = "account-photo.jpg",
102
+ account_photo_content_type: str = "image/jpeg",
103
+ id_photo_filename: str = "id-photo.jpg",
104
+ id_photo_content_type: str = "image/jpeg",
105
+ ) -> CustomerResponse:
106
+ """Register a customer with KYC photographs.
107
+
108
+ Operation: Business API - Register a customer with KYC.
109
+
110
+ Sent as ``multipart/form-data``: a ``customer`` JSON part, plus
111
+ ``customerAccountPhoto`` and ``customerIdPhoto`` image parts. Each
112
+ photograph must be a JPEG of at most 500 KB.
113
+
114
+ Args:
115
+ reference_number: Your unique reference for this request.
116
+ customer_phone_number: The customer's phone number.
117
+ customer_email: The customer's email address.
118
+ customer_first_name: The customer's first name.
119
+ customer_last_name: The customer's last name.
120
+ customer_date_of_birth: The customer's date of birth, as
121
+ ``YYYY-MM-DD``.
122
+ customer_gender: ``"FEMALE"`` or ``"MALE"``.
123
+ customer_account_photo: The account photograph's bytes.
124
+ customer_id_photo: The identification photograph's bytes.
125
+ customer_address: Optional address object.
126
+ customer_marital_status: Optional marital status.
127
+ customer_preferred_language_iso_code: Optional ISO 639-1 code.
128
+ customer_id_type: Optional identification type.
129
+ customer_id_number: Optional identification number.
130
+ customer_id_expiration_date: Optional identification expiry date.
131
+ optin_for_wallet_savings: Optional wallet savings opt-in.
132
+ customer_reference: Optional reference you hold for the customer.
133
+ account_photo_filename: Filename for the account photograph.
134
+ account_photo_content_type: Content type of the account photograph.
135
+ id_photo_filename: Filename for the identification photograph.
136
+ id_photo_content_type: Content type of the identification photograph.
137
+
138
+ Returns:
139
+ The parsed :class:`CustomerResponse`.
140
+ """
141
+ payload: Dict[str, Any] = {
142
+ "referenceNumber": reference_number,
143
+ "customerPhoneNumber": customer_phone_number,
144
+ "customerEmail": customer_email,
145
+ "customerFirstName": customer_first_name,
146
+ "customerLastName": customer_last_name,
147
+ "customerDateOfBirth": customer_date_of_birth,
148
+ "customerGender": customer_gender,
149
+ }
150
+ if customer_address is not None:
151
+ payload["customerAddress"] = customer_address
152
+ if customer_marital_status is not None:
153
+ payload["customerMaritalStatus"] = customer_marital_status
154
+ if customer_preferred_language_iso_code is not None:
155
+ payload["customerPreferredLanguageISOCode"] = customer_preferred_language_iso_code
156
+ if customer_id_type is not None:
157
+ payload["customerIdType"] = customer_id_type
158
+ if customer_id_number is not None:
159
+ payload["customerIdNumber"] = customer_id_number
160
+ if customer_id_expiration_date is not None:
161
+ payload["customerIdExpirationDate"] = customer_id_expiration_date
162
+ if optin_for_wallet_savings is not None:
163
+ payload["optinForWalletSavings"] = optin_for_wallet_savings
164
+ if customer_reference is not None:
165
+ payload["customerReference"] = customer_reference
166
+
167
+ response = await self._multipart_request(
168
+ "POST",
169
+ "/registerCustomerWithKYC",
170
+ {
171
+ "customer": payload,
172
+ "customerAccountPhoto": (
173
+ account_photo_filename,
174
+ bytes(customer_account_photo),
175
+ account_photo_content_type,
176
+ ),
177
+ "customerIdPhoto": (
178
+ id_photo_filename,
179
+ bytes(customer_id_photo),
180
+ id_photo_content_type,
181
+ ),
182
+ },
183
+ hash_payload=payload,
184
+ hash_fields=CUSTOMER_HASH_FIELDS,
185
+ )
186
+ return CustomerResponse.model_validate(response.model_dump())
187
+
188
+ async def register_customer_account_photo(
189
+ self,
190
+ *,
191
+ reference_number: str,
192
+ customer_phone_number: str,
193
+ customer_account_photo: bytes,
194
+ photo_filename: str = "account-photo.jpg",
195
+ photo_content_type: str = "image/jpeg",
196
+ ) -> CustomerResponse:
197
+ """Upload a customer's account photograph.
198
+
199
+ Operation: Business API - Register a customer account photo.
200
+
201
+ Sent as ``multipart/form-data``: a ``customer`` JSON part plus a
202
+ ``customerAccountPhoto`` image part.
203
+
204
+ Args:
205
+ reference_number: Your unique reference for this request.
206
+ customer_phone_number: The customer's phone number.
207
+ customer_account_photo: The account photograph's bytes.
208
+ photo_filename: Filename for the photograph.
209
+ photo_content_type: Content type of the photograph.
210
+
211
+ Returns:
212
+ The parsed :class:`CustomerResponse`.
213
+ """
214
+ payload: Dict[str, Any] = {
215
+ "referenceNumber": reference_number,
216
+ "customerPhoneNumber": customer_phone_number,
217
+ }
218
+ response = await self._multipart_request(
219
+ "POST",
220
+ "/registerCustomerAccountPhoto",
221
+ {
222
+ "customer": payload,
223
+ "customerAccountPhoto": (
224
+ photo_filename,
225
+ bytes(customer_account_photo),
226
+ photo_content_type,
227
+ ),
228
+ },
229
+ hash_payload=payload,
230
+ hash_fields=CUSTOMER_ACCOUNT_PHOTO_HASH_FIELDS,
231
+ )
232
+ return CustomerResponse.model_validate(response.model_dump())
233
+
234
+ async def register_customer_identification(
235
+ self,
236
+ *,
237
+ reference_number: str,
238
+ customer_phone_number: str,
239
+ customer_id_type: str,
240
+ customer_id_number: str,
241
+ customer_id_expiration_date: str,
242
+ customer_id_photo: bytes,
243
+ photo_filename: str = "id-photo.jpg",
244
+ photo_content_type: str = "image/jpeg",
245
+ ) -> CustomerResponse:
246
+ """Upload a customer's identification.
247
+
248
+ Operation: Business API - Register a customer identification.
249
+
250
+ Sent as ``multipart/form-data``: a ``customer`` JSON part plus a
251
+ ``customerIdPhoto`` image part.
252
+
253
+ Args:
254
+ reference_number: Your unique reference for this request.
255
+ customer_phone_number: The customer's phone number.
256
+ customer_id_type: The identification type, e.g. ``"BVN"``.
257
+ customer_id_number: The identification number.
258
+ customer_id_expiration_date: When the identification expires.
259
+ customer_id_photo: The identification photograph's bytes.
260
+ photo_filename: Filename for the photograph.
261
+ photo_content_type: Content type of the photograph.
262
+
263
+ Returns:
264
+ The parsed :class:`CustomerResponse`.
265
+ """
266
+ payload: Dict[str, Any] = {
267
+ "referenceNumber": reference_number,
268
+ "customerPhoneNumber": customer_phone_number,
269
+ "customerIdType": customer_id_type,
270
+ "customerIdNumber": customer_id_number,
271
+ "customerIdExpirationDate": customer_id_expiration_date,
272
+ }
273
+ response = await self._multipart_request(
274
+ "POST",
275
+ "/registerCustomerIdentification",
276
+ {
277
+ "customer": payload,
278
+ "customerIdPhoto": (
279
+ photo_filename,
280
+ bytes(customer_id_photo),
281
+ photo_content_type,
282
+ ),
283
+ },
284
+ hash_payload=payload,
285
+ hash_fields=CUSTOMER_IDENTIFICATION_HASH_FIELDS,
286
+ )
287
+ return CustomerResponse.model_validate(response.model_dump())