Coverage for packages/kapitalbank/src/integrify/kapitalbank/client.py: 100%
39 statements
« prev ^ index » next coverage.py v7.16.0, created at 2026-10-19 02:39 +0000
« prev ^ index » next coverage.py v7.16.0, created at 2026-10-19 02:39 +0000
1from collections.abc import Coroutine
2from typing import TYPE_CHECKING, Any, Generic, overload
3from typing import SupportsFloat as Numeric
5from integrify.api import APIClient, APIResponse, _Async, _Mode, _Sync
6from integrify.kapitalbank import env
7from integrify.kapitalbank.handlers import (
8 ClearingOrderPayloadHandler,
9 CreateOrderPayloadHandler,
10 DetailedOrderInformationPayloadHandler,
11 FullReverseOrderPayloadHandler,
12 LinkCardTokenPayloadHandler,
13 OrderInformationPayloadHandler,
14 OrderWithSavedCardPayloadHandler,
15 PartialReverseOrderPayloadHandler,
16 PayAndSaveCardPayloadHandler,
17 ProcessPaymentWithSavedCardPayloadHandler,
18 RefundOrderPayloadHandler,
19 SaveCardPayloadHandler,
20)
21from integrify.kapitalbank.schemas.response import (
22 BaseResponseSchema,
23 ClearingOrderResponseSchema,
24 CreateOrderResponseSchema,
25 DetailedOrderInformationResponseSchema,
26 FullReverseOrderResponseSchema,
27 LinkCardTokenResponseSchema,
28 OrderInformationResponseSchema,
29 PartialReverseOrderResponseSchema,
30 ProcessPaymentWithSavedCardResponseSchema,
31 RefundOrderResponseSchema,
32)
33from integrify.utils import UNSET as _UNSET
34from integrify.utils import Unset as Unsettable
36__all__ = ['KapitalClientClass']
39class KapitalClientClass(APIClient, Generic[_Mode]):
40 def __init__(
41 self,
42 name='Kapital',
43 base_url=env.API.BASE_URL,
44 default_handler=None,
45 sync=True,
46 dry=False,
47 ):
48 super().__init__(name, base_url, default_handler, sync, dry)
50 self.add_url('create_order', env.API.ORDER, verb='POST')
51 self.add_handler('create_order', CreateOrderPayloadHandler)
53 self.add_url('get_order_information', env.API.GET_ORDER, verb='GET')
54 self.add_handler('get_order_information', OrderInformationPayloadHandler)
56 self.add_url('get_detailed_order_info', env.API.GET_DETAILED_ORDER, verb='GET')
57 self.add_handler('get_detailed_order_info', DetailedOrderInformationPayloadHandler)
59 self.add_url('refund_order', env.API.ORDER_EXECUTION, verb='POST')
60 self.add_handler('refund_order', RefundOrderPayloadHandler)
62 self.add_url('save_card', env.API.ORDER, verb='POST')
63 self.add_handler('save_card', SaveCardPayloadHandler)
65 self.add_url('pay_and_save_card', env.API.ORDER, verb='POST')
66 self.add_handler('pay_and_save_card', PayAndSaveCardPayloadHandler)
68 self.add_url('full_reverse_order', env.API.ORDER_EXECUTION, verb='POST')
69 self.add_handler('full_reverse_order', FullReverseOrderPayloadHandler)
71 self.add_url('clearing_order', env.API.ORDER_EXECUTION, verb='POST')
72 self.add_handler('clearing_order', ClearingOrderPayloadHandler)
74 self.add_url('partial_reverse_order', env.API.ORDER_EXECUTION, verb='POST')
75 self.add_handler('partial_reverse_order', PartialReverseOrderPayloadHandler)
77 self.add_url('order_with_saved_card', env.API.ORDER, verb='POST')
78 self.add_handler(
79 'order_with_saved_card',
80 OrderWithSavedCardPayloadHandler,
81 )
83 self.add_url('link_card_token', env.API.ORDER_LINK_CARD_TOKEN, verb='POST')
84 self.add_handler('link_card_token', LinkCardTokenPayloadHandler)
86 self.add_url(
87 'process_payment_with_saved_card',
88 env.API.PROCESS_PAYMENT_WITH_SAVED_CARD,
89 verb='POST',
90 )
91 self.add_handler(
92 'process_payment_with_saved_card',
93 ProcessPaymentWithSavedCardPayloadHandler,
94 )
96 # All other endpoints were tested separately
97 def pay_with_saved_card( # pragma: no cover
98 self,
99 token: int,
100 amount: Numeric,
101 currency: str,
102 description: Unsettable[str] = _UNSET,
103 ) -> APIResponse[BaseResponseSchema[ProcessPaymentWithSavedCardResponseSchema]]:
104 """
105 Yadda saxlanmış kartdan ödəniş etmək üçün sorğu
107 **Endpoint** /api/order
109 Example:
110 ```python
111 from integrify.kapitalbank import KapitalRequest
113 KapitalRequest.pay_with_saved_card(123456, 1.0, "AZN", "Test payment")
114 ```
116 **Cavab formatı: [`BaseResponseSchema[ProcessPaymentWithSavedCardResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
118 Bu sorğunu göndərdikdə, cavab olaraq ödənişin təsdiq edilməsi haqda məlumat əldə edə bilərsiniz.
120 Args:
121 token: Kart tokeni.
122 amount: Ödəniş miqdarı. Numerik dəyər.
123 currency: Ödənişin məzənnəsi. Mümkün dəyərlər: `["AZN", "USD"]`.
124 description: Ödənişin təsviri. Maksimal uzunluq: 1000 simvol. Məcburi arqument deyil.
125 """ # noqa: E501
126 # Bu köməkçi metod nəticələri sinxron istifadə edir (`.body.data`), ona görə
127 # yalnız sync klient üçün mənalıdır. Alt-metodların overload-ları `self`-in
128 # `KapitalClientClass[_Sync]` olmasını tələb etdiyi üçün `self`-i sync kimi cast edirik.
129 sync_self: KapitalClientClass[_Sync] = self
131 order_response = sync_self.order_with_saved_card( # pylint: disable=assignment-from-no-return
132 amount=amount,
133 currency=currency,
134 description=description,
135 )
137 assert order_response.body and order_response.body.data
139 order_id = order_response.body.data.id
140 password = order_response.body.data.password
142 sync_self.link_card_token(
143 token=token,
144 order_id=order_id,
145 password=password,
146 )
148 return sync_self.process_payment_with_saved_card(
149 amount=amount,
150 order_id=order_id,
151 password=password,
152 )
154 if TYPE_CHECKING:
155 # pylint: disable=missing-function-docstring,unused-argument
157 @overload
158 def create_order(
159 self: 'KapitalClientClass[_Sync]',
160 amount: Numeric,
161 currency: str,
162 description: Unsettable[str] = _UNSET,
163 ) -> APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]:
164 """Ödəniş sorğusu
166 **Endpoint** /api/order
168 Example:
169 ```python
170 from integrify.kapitalbank import KapitalRequest
172 KapitalRequest.create_order(
173 amount=10.0,
174 currency="AZN",
175 description="Test payment",
176 )
177 ```
179 **Cavab formatı: [`BaseResponseSchema[CreateOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
181 Bu sorğunu göndərdikdə, cavab olaraq `redirect_url` gəlir. Müştəri həmin URLə daxil
182 olub, kart məlumatlarını daxil edib, uğurlu ödəniş etdikdən sonra, backend callback
183 APIsinə "{callback_url}/?ID={id}&STATUS={status}" formatında sorğusu göndərilir. Ödənişin
184 detallarını get_detailed_order_info() funksiyandan istifadə edərək əldə edə bilərsiz.
186 Args:
187 amount: Ödəniş miqdarı. Numerik dəyər.
188 currency: Ödənişin məzənnəsi. Mümkün dəyərlər: `["AZN", "USD"]`.
189 description: Ödənişin təsviri. Maksimal uzunluq: 1000 simvol. Məcburi arqument deyil.
190 """ # noqa: E501
192 @overload
193 def create_order(
194 self: 'KapitalClientClass[_Async]',
195 amount: Numeric,
196 currency: str,
197 description: Unsettable[str] = _UNSET,
198 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]]: ...
199 def create_order(self, *args: Any, **kwds: Any) -> Any: ...
201 @overload
202 def get_order_information(
203 self: 'KapitalClientClass[_Sync]', order_id: int
204 ) -> APIResponse[BaseResponseSchema[OrderInformationResponseSchema]]:
205 """Ödəniş haqda qısa məlumat əldə etmək üçün sorğu
207 **Endpoint** /api/order/{order_id}
209 Example:
210 ```python
211 from integrify.kapitalbank import KapitalRequest
213 KapitalRequest.get_order_information(order_id=123456)
214 ```
216 **Cavab formatı: [`BaseResponseSchema[OrderInformationResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
218 Bu sorğunu göndərdikdə, cavab olaraq ödəniş haqda qısa məlumat əldə edə bilərsiniz.
220 Args:
221 order_id: Ödənişin ID-si.
222 """ # noqa: E501
224 @overload
225 def get_order_information(
226 self: 'KapitalClientClass[_Async]', order_id: int
227 ) -> Coroutine[
228 Any, Any, APIResponse[BaseResponseSchema[OrderInformationResponseSchema]]
229 ]: ...
230 def get_order_information(self, *args: Any, **kwds: Any) -> Any: ...
232 @overload
233 def get_detailed_order_info(
234 self: 'KapitalClientClass[_Sync]', order_id: int
235 ) -> APIResponse[BaseResponseSchema[DetailedOrderInformationResponseSchema]]:
236 """Ödəniş haqda detallı məlumat əldə etmək üçün sorğu
238 **Endpoint** /api/order/{order_id}?&tranDetailLevel=2&tokenDetailLevel=2&orderDetailLevel=2
240 Example:
241 ```python
242 from integrify.kapitalbank import KapitalRequest
244 KapitalRequest.get_detailed_order_info(order_id=123456)
245 ```
247 **Cavab formatı: [`BaseResponseSchema[DetailedOrderInformationResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
249 Bu sorğunu göndərdikdə, cavab olaraq ödənişin detallı məlumat əldə edə bilərsiniz.
251 Args:
252 order_id: Ödənişin ID-si.
253 """ # noqa: E501
255 @overload
256 def get_detailed_order_info(
257 self: 'KapitalClientClass[_Async]', order_id: int
258 ) -> Coroutine[
259 Any, Any, APIResponse[BaseResponseSchema[DetailedOrderInformationResponseSchema]]
260 ]: ...
261 def get_detailed_order_info(self, *args: Any, **kwds: Any) -> Any: ...
263 @overload
264 def refund_order(
265 self: 'KapitalClientClass[_Sync]',
266 order_id: int,
267 amount: Numeric,
268 ) -> APIResponse[BaseResponseSchema[RefundOrderResponseSchema]]:
269 """Geri ödəniş sorğusu
271 **Endpoint** /api/order/{order_id}/exec-tran
273 Example:
274 ```python
275 from integrify.kapitalbank import KapitalRequest
277 KapitalRequest.refund_order(
278 order_id=123456,
279 amount=10.0,
280 )
281 ```
283 **Cavab formatı: [`BaseResponseSchema[RefundOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
285 Bu sorğu ilə əvvəlki ödənişi geri ödəmək üçün istifadə edə bilərsiniz.
286 Cavab olaraq ödənişin detallarını əldə edə bilərsiniz.
288 Args:
289 order_id: Ödənişin ID-si.
290 amount: Geri ödəniş miqdarı. Numerik dəyər.
291 """ # noqa: E501
293 @overload
294 def refund_order(
295 self: 'KapitalClientClass[_Async]',
296 order_id: int,
297 amount: Numeric,
298 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[RefundOrderResponseSchema]]]: ...
299 def refund_order(self, *args: Any, **kwds: Any) -> Any: ...
301 @overload
302 def save_card(
303 self: 'KapitalClientClass[_Sync]',
304 amount: Numeric,
305 currency: str,
306 description: Unsettable[str] = _UNSET,
307 ) -> APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]:
308 """Kartı saxlamaq üçün ödəniş sorğusu
310 **Endpoint** /api/order
312 Example:
313 ```python
314 from integrify.kapitalbank import KapitalRequest
316 KapitalRequest.save_card(
317 amount=1.0,
318 currency="AZN",
319 description="Test payment",
320 )
321 ```
323 **Cavab formatı: [`BaseResponseSchema[CreateOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
325 Bu sorğunu göndərdikdə, cavab olaraq `redirect_url` gəlir. Müştəri həmin URLə daxil
326 olub, kart məlumatlarını daxil edib, uğurlu ödəniş etdikdən sonra, backend callback
327 APIsinə "{callback_url}/?ID={id}&STATUS={status}" formatında sorğusu göndərilir. Ödənişin
328 detallarını get_detailed_order_info() funksiyandan istifadə edərək əldə edə bilərsiz.
329 Həmin detallarda storedTokens key-i altındaki tokenləri saxlayaraq, sonrakı ödənişlərdə bu tokenləri
330 istifadə edə bilərsiniz.
332 `response.body.data.stored_tokens[0].id` ilə tokeni əldə edə bilərsiniz.
333 """ # noqa: E501
335 @overload
336 def save_card(
337 self: 'KapitalClientClass[_Async]',
338 amount: Numeric,
339 currency: str,
340 description: Unsettable[str] = _UNSET,
341 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]]: ...
342 def save_card(self, *args: Any, **kwds: Any) -> Any: ...
344 @overload
345 def pay_and_save_card(
346 self: 'KapitalClientClass[_Sync]',
347 amount: Numeric,
348 currency: str,
349 description: Unsettable[str] = _UNSET,
350 ) -> APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]:
351 """Kartı saxlamaq və ödəniş etmək üçün ödəniş sorğusu
353 **Endpoint** /api/order
355 Example:
356 ```python
357 from integrify.kapitalbank import KapitalRequest
359 KapitalRequest.pay_and_save_card(
360 amount=1.0,
361 currency="AZN",
362 description="Test payment",
363 )
364 ```
366 **Cavab formatı: [`BaseResponseSchema[CreateOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
368 Bu sorğunu göndərdikdə, cavab olaraq `redirect_url` gəlir. Müştəri həmin URLə daxil
369 olub, kart məlumatlarını daxil edib, uğurlu ödəniş etdikdən sonra, backend callback
370 APIsinə "{callback_url}/?ID={id}&STATUS={status}" formatında sorğusu göndərilir. Ödənişin
371 detallarını get_detailed_order_info() funksiyandan istifadə edərək əldə edə bilərsiz.
372 Həmin detallarda storedTokens key-i altındaki tokenləri saxlayaraq, sonrakı ödənişlərdə bu tokenləri
373 istifadə edə bilərsiniz.
375 `response.body.data.stored_tokens[0].id` ilə tokeni əldə edə bilərsiniz.
376 """ # noqa: E501
378 @overload
379 def pay_and_save_card(
380 self: 'KapitalClientClass[_Async]',
381 amount: Numeric,
382 currency: str,
383 description: Unsettable[str] = _UNSET,
384 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]]: ...
385 def pay_and_save_card(self, *args: Any, **kwds: Any) -> Any: ...
387 @overload
388 def full_reverse_order(
389 self: 'KapitalClientClass[_Sync]',
390 order_id: int,
391 ) -> APIResponse[BaseResponseSchema[FullReverseOrderResponseSchema]]:
392 """Ödənişi ləğv etmək üçün sorğu
394 **Endpoint** /api/order/{order_id}/exec-tran
396 Example:
397 ```python
398 from integrify.kapitalbank import KapitalRequest
400 KapitalRequest.full_reverse_order(order_id=123456)
401 ```
403 **Cavab formatı: [`BaseResponseSchema[FullReverseOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
405 Bu sorğunu göndərdikdə, cavab olaraq ödənişin ləğv edilməsi haqda məlumat əldə edə bilərsiniz.
406 Bu funksiyani save_card() funksiyası ilə yaradılan ödənişlər üçün istifadə edə bilərsiniz.
407 Kartın token-i saxladıqdan sonra həmin ödənişi qaytarmaq üçün istifade etmək olar.
409 Args:
410 order_id: Ödənişin ID-si.
411 """ # noqa: E501
413 @overload
414 def full_reverse_order(
415 self: 'KapitalClientClass[_Async]',
416 order_id: int,
417 ) -> Coroutine[
418 Any, Any, APIResponse[BaseResponseSchema[FullReverseOrderResponseSchema]]
419 ]: ...
420 def full_reverse_order(self, *args: Any, **kwds: Any) -> Any: ...
422 @overload
423 def clearing_order(
424 self: 'KapitalClientClass[_Sync]',
425 order_id: int,
426 amount: Numeric,
427 ) -> APIResponse[BaseResponseSchema[ClearingOrderResponseSchema]]:
428 """Ödənişin təsdiq edilməsi üçün sorğu
430 **Endpoint** /api/order/{order_id}/exec-tran
432 Example:
433 ```python
434 from integrify.kapitalbank import KapitalRequest
436 KapitalRequest.clearing_order(order_id=123456)
437 ```
439 **Cavab formatı: [`BaseResponseSchema[ClearingOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
441 Bu sorğunu göndərdikdə, cavab olaraq ödənişin təsdiq edilməsi haqda məlumat əldə edə bilərsiniz.
442 Bu funksiyani save_card() funksiyası ilə yaradılan ödənişlər üçün istifadə edə bilərsiniz.
443 Preauthorization əməliyyatının ikinci mərhələsi üçün.
445 Args:
446 order_id: Ödənişin ID-si.
447 """ # noqa: E501
449 @overload
450 def clearing_order(
451 self: 'KapitalClientClass[_Async]',
452 order_id: int,
453 amount: Numeric,
454 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[ClearingOrderResponseSchema]]]: ...
455 def clearing_order(self, *args: Any, **kwds: Any) -> Any: ...
457 @overload
458 def partial_reverse_order(
459 self: 'KapitalClientClass[_Sync]',
460 order_id: int,
461 amount: Numeric,
462 ) -> APIResponse[BaseResponseSchema[PartialReverseOrderResponseSchema]]:
463 """Ödənişin hissəsini ləğv etmək üçün sorğu
465 **Endpoint** /api/order/{order_id}/exec-tran
467 Example:
468 ```python
469 from integrify.kapitalbank import KapitalRequest
471 KapitalRequest.partial_reverse_order(order_id=123456, amount=5.0)
472 ```
474 **Cavab formatı: [`BaseResponseSchema[PartialReverseOrderResponseSchema]`][integrify.kapitalbank.schemas.response.BaseResponseSchema]**
476 Bu sorğunu göndərdikdə, cavab olaraq ödənişin ləğv edilməsi haqda məlumat əldə edə bilərsiniz.
477 Bu funksiyani clearing_order() funksiyası ilə təsdiq edilmiş ödənişlər üçün istifadə edə bilərsiniz.
478 İlkin məbləğdən az olan vəsaitləri qaytarmaq üçün istifadə olunur. Bir dəfə istifadə etmək olar.
480 Args:
481 order_id: Ödənişin ID-si.
482 amount: Ləğv olunacaq miqdar. Numerik dəyər.
483 """ # noqa: E501
485 @overload
486 def partial_reverse_order(
487 self: 'KapitalClientClass[_Async]',
488 order_id: int,
489 amount: Numeric,
490 ) -> Coroutine[
491 Any, Any, APIResponse[BaseResponseSchema[PartialReverseOrderResponseSchema]]
492 ]: ...
493 def partial_reverse_order(self, *args: Any, **kwds: Any) -> Any: ...
495 @overload
496 def order_with_saved_card(
497 self: 'KapitalClientClass[_Sync]',
498 amount: Numeric,
499 currency: str,
500 description: Unsettable[str] = _UNSET,
501 ) -> APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]:
502 """
503 Bu funksiya sadece KapitalClientClass daxilinde istifade olunur!
505 **Endpoint** /api/order
507 Bu funksiya pay_with_saved_card() funksiyasında istifadə olunur.
508 Əsas məqsədi order_id və password dəyərlərini əldə etməkdir.
510 Args:
511 amount: Ödəniş miqdarı. Numerik dəyər.
512 currency: Ödənişin məzənnəsi. Mümkün dəyərlər: `["AZN", "USD"]`.
513 description: Ödənişin təsviri. Maksimal uzunluq: 1000 simvol. Məcburi arqument deyil.
514 """ # noqa: E501
516 @overload
517 def order_with_saved_card(
518 self: 'KapitalClientClass[_Async]',
519 amount: Numeric,
520 currency: str,
521 description: Unsettable[str] = _UNSET,
522 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[CreateOrderResponseSchema]]]: ...
523 def order_with_saved_card(self, *args: Any, **kwds: Any) -> Any: ...
525 @overload
526 def link_card_token(
527 self: 'KapitalClientClass[_Sync]',
528 token: int,
529 order_id: int,
530 password: str,
531 ) -> APIResponse[BaseResponseSchema[LinkCardTokenResponseSchema]]:
532 """
533 Bu funksiya sadece KapitalClientClass daxilinde istifade olunur!
535 **Endpoint** /api/order/{order_id}/set-src-token?password={password}
537 Bu funksiya pay_with_saved_card() funksiyasında istifadə olunur.
538 Əsas məqsədi token-i həmin order üçün set etməkdir.
540 Args:
541 token: Kart tokeni.
542 order_id: Ödənişin ID-si.
543 password: Ödənişin passwordu.
544 """ # noqa: E501
546 @overload
547 def link_card_token(
548 self: 'KapitalClientClass[_Async]',
549 token: int,
550 order_id: int,
551 password: str,
552 ) -> Coroutine[Any, Any, APIResponse[BaseResponseSchema[LinkCardTokenResponseSchema]]]: ...
553 def link_card_token(self, *args: Any, **kwds: Any) -> Any: ...
555 @overload
556 def process_payment_with_saved_card(
557 self: 'KapitalClientClass[_Sync]',
558 amount: Numeric,
559 order_id: int,
560 password: str,
561 ) -> APIResponse[BaseResponseSchema[ProcessPaymentWithSavedCardResponseSchema]]:
562 """
563 Bu funksiya sadece KapitalClientClass daxilinde istifade olunur!
565 **Endpoint** /api/order/{order_id}/exec-tran?password={password}
567 Bu funksiya pay_with_saved_card() funksiyasında istifadə olunur.
568 Əsas məqsədi ödənişi təsdiq etməkdir.
570 Args:
571 amount: Ödəniş miqdarı. Numerik dəyər.
572 order_id: Ödənişin ID-si.
573 password: Ödənişin password
574 """ # noqa: E501
576 @overload
577 def process_payment_with_saved_card(
578 self: 'KapitalClientClass[_Async]',
579 amount: Numeric,
580 order_id: int,
581 password: str,
582 ) -> Coroutine[
583 Any, Any, APIResponse[BaseResponseSchema[ProcessPaymentWithSavedCardResponseSchema]]
584 ]: ...
585 def process_payment_with_saved_card(self, *args: Any, **kwds: Any) -> Any: ...
588KapitalRequest: 'KapitalClientClass[_Sync]' = KapitalClientClass(sync=True)
589KapitalAsyncRequest: 'KapitalClientClass[_Async]' = KapitalClientClass(sync=False)