diff --git a/.gitignore b/.gitignore index 8207d2c..a76c574 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ __pycache__/ *.py[cod] *$py.class uv.lock +ejemplo.py # C extensions *.so diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index cca76e3..e4f9c5e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,23 +1,7 @@ # Changelog -Cambios notables de Django Payments Chile - -Formato basado en [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -y este proyecto se adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - ## [Unreleased] -- Klap -- Kushki -- Pagofacil -- Transbank WebPayPlus -- Transbank OnePay - -## [2024.9.29] - -- Cambios en Documentacion -- Nuevos providers para: **Flow, Khipu, Payku** - -## [2024.9.23] +## [2024.12.1] - Commit Inicial diff --git a/docs/api.md b/docs/api.md index 020b6eb..0fdf0ff 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,63 +1,17 @@ -# API de django-payments-chile +# Documentación API -Este documento proporciona una visión general de los diferentes proveedores de pago disponibles en django-payments-chile. Cada proveedor tiene su propia implementación y configuración específica. +## Banks -Para obtener detalles sobre cada proveedor, consulte los siguientes enlaces: +::: khipu_tools._banks.Banks -- [FlowProvider](flow-provider.md) -- [KhipuProvider](khipu-provider.md) -- [KlapProvider](klap-provider.md) -- [KushkiProvider](kushki-provider.md) -- [OneclickProvider](oneclick-provider.md) -- [PagofacilProvider](pagofacil-provider.md) -- [PaykuProvider](payku-provider.md) -- [WebpayProvider](webpay-provider.md) +## BankItem -Cada enlace lo llevará a una documentación detallada sobre la implementación y uso de ese proveedor específico. +::: khipu_tools._banks.BankItem -## FlowProvider +## Predict -El FlowProvider es una implementación para integrar la pasarela de pagos Flow en django-payments-chile. +::: khipu_tools._predict.Predict -### Métodos principales +## Payments -- `__init__(self, **kwargs)`: Inicializa el proveedor con las configuraciones necesarias. -- `get_form(self, payment, data=None)`: Retorna el formulario para iniciar el proceso de pago. -- `process_data(self, payment, request)`: Procesa los datos recibidos de Flow después de un pago. - -#### Configuración - -Para utilizar FlowProvider, añada la siguiente configuración a `PAYMENT_VARIANTS` en su archivo `settings.py`: - -```python -PAYMENT_VARIANTS = { - "flow": ("django_payments_chile.FlowProvider", { - "api_key": "su_api_key", - "api_secret": "su_api_secret", - "api_endpoint": "sandbox", # Cambie a "live" para producción - "api_medio": 9, # 9 indica todos los medios de pago - }) -} -``` - -#### Uso - -Para crear un pago utilizando FlowProvider: - -```python -from django_payments import get_payment_model - -Payment = get_payment_model() -payment = Payment.objects.create( - variant='flow', # Debe coincidir con la clave en PAYMENT_VARIANTS - amount=1000, - currency='CLP', - description='Descripción del pago' -) -``` - -Consulte la [documentación de Flow](https://www.flow.cl/docs) para más detalles sobre la integración y opciones disponibles. - -## API - -::: django_payments_chile.FlowProvider +::: khipu_tools._payments.Payments diff --git a/docs/contributing.md b/docs/contributing.md index 5285dee..faf824c 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,6 @@ -# Guía de Colaboración para django-payments-chile +# Guía de Colaboración para khipu-tools -¡Gracias por tu interés en colaborar con django-payments-chile! Este documento te guiará a través del proceso de contribución al proyecto. +¡Gracias por tu interés en colaborar con khipu-tools! Este documento te guiará a través del proceso de contribución al proyecto. ## Formas de Colaborar @@ -27,15 +27,15 @@ Puedes clonar el repositorio de dos maneras: ### Usando Git ```shell -git clone https://github.com/mariofix/django-payments-chile.git -cd django-payments-chile +git clone https://github.com/mariofix/khipu-tools.git +cd khipu-tools ``` ### Usando GitHub CLI ```shell -gh repo clone mariofix/django-payments-chile -cd django-payments-chile +gh repo clone mariofix/khipu-tools +cd khipu-tools ``` ## Configuración del Entorno de Desarrollo @@ -96,4 +96,4 @@ Al contribuir a este proyecto, aceptas que tus contribuciones se licenciarán ba Si tienes preguntas o necesitas ayuda, no dudes en crear un issue en GitHub. -¡Gracias por tu contribución a django-payments-chile! +¡Gracias por tu contribución a khipu-tools! diff --git a/docs/index.md b/docs/index.md index 87f8098..b93d774 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,16 +2,16 @@ Khipu Tools es una librería en Python pensada para facilitar la integración con los servicios de Khipu. Este proyecto ofrece funcionalidades clave para manejar transacciones financieras, enfocándose en simplicidad, eficiencia y robustez. -![PyPI - Status](https://img.shields.io/pypi/status/django-payments-chile) -[![Downloads](https://pepy.tech/badge/django-payments-chile)](https://pepy.tech/project/django-payments-chile) -[![Codacy Badge](https://app.codacy.com/project/badge/Grade/fde07768d1714b0b93c6addd5e13bb7f)](https://app.codacy.com/gh/mariofix/django-payments-chile/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/fde07768d1714b0b93c6addd5e13bb7f)](https://app.codacy.com/gh/mariofix/django-payments-chile/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) -[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/mariofix/django-payments-chile/main.svg)](https://results.pre-commit.ci/latest/github/mariofix/django-payments-chile/main) -[![Tests & Coverage](https://github.com/mariofix/django-payments-chile/actions/workflows/tests_coverage.yml/badge.svg?branch=main)](https://github.com/mariofix/django-payments-chile/actions/workflows/tests_coverage.yml) -![PyPI](https://img.shields.io/pypi/v/django-payments-chile) -![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-payments-chile) -![PyPI - Implementation](https://img.shields.io/pypi/implementation/django-payments-chile) -![PyPI - License](https://img.shields.io/pypi/l/django-payments-chile) +![PyPI - Status](https://img.shields.io/pypi/status/khipu-tools) +[![Downloads](https://pepy.tech/badge/khipu-tools)](https://pepy.tech/project/khipu-tools) +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/fde07768d1714b0b93c6addd5e13bb7f)](https://app.codacy.com/gh/mariofix/khipu-tools/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) +[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/fde07768d1714b0b93c6addd5e13bb7f)](https://app.codacy.com/gh/mariofix/khipu-tools/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/mariofix/khipu-tools/main.svg)](https://results.pre-commit.ci/latest/github/mariofix/khipu-tools/main) +[![Tests & Coverage](https://github.com/mariofix/khipu-tools/actions/workflows/tests_coverage.yml/badge.svg?branch=main)](https://github.com/mariofix/khipu-tools/actions/workflows/tests_coverage.yml) +![PyPI](https://img.shields.io/pypi/v/khipu-tools) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/khipu-tools) +![PyPI - Implementation](https://img.shields.io/pypi/implementation/khipu-tools) +![PyPI - License](https://img.shields.io/pypi/l/khipu-tools) ## Características Destacadas diff --git a/docs/pagos-automaticos.md b/docs/pagos-automaticos.md new file mode 100644 index 0000000..83b7f4c --- /dev/null +++ b/docs/pagos-automaticos.md @@ -0,0 +1,50 @@ +# Pagos Automáticos + +Es muy sencillo habilitar el proceso de Pago Automático a tus clientes, sólo necesitas utilizar la API de Suscripción para solicitar un nuevo ID de Suscripción, para asociarlo al servicio que vas a cobrar a tu cliente de forma recurrente. Cuando el cliente finalice el proceso de firma en su banco, recibirá una notificación en la URL de devolución de llamada que proporcionó al solicitar el ID de suscripción. + +Tras una confirmación positiva, puede empezar a utilizar la API de cobro para enviar sus solicitudes de pago automático. La parte restante del proceso es asíncrona y se le notificará cuando finalice el proceso de conciliación. + +## Crear Subscripción + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.AutomaticPayments.create( + name="Service XYZ Id 11.222.333-0", + email="personal.email@gmail.com", + max_amount=1000, + currency="CLP", + notify_url="https://my-domain.biz/subscription-notify-api", + return_url="https://my-domain.biz/subscription-result", + cancel_url="https://my-domain.biz/subscription-cancel" +) +``` + +```json +{ + "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec", + "redirect_url": "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec" +} +``` + +## Obtener información de una subscripción + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.AutomaticPayments.get(payment_id="13a0f1aa-5e47-4894-aa8b-282dd19593ec") +``` + +Respuesta + +```json +{ + "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec", + "status": "SIGNED", + "developer": false, + "customer_bank_code": "8", + "service_reference": "My Merchant name" +} +``` diff --git a/docs/pagos-instantaneos.md b/docs/pagos-instantaneos.md new file mode 100644 index 0000000..1280fd6 --- /dev/null +++ b/docs/pagos-instantaneos.md @@ -0,0 +1,194 @@ +# Pagos Instantáneos + +La API de Khipu para crear y recibir pagos permite a cobradores (individuos u organizaciones), que tengan una cuenta de cobro activa en Khipu, generar cobros. + +El proceso de creación, pago y validación es el siguiente: + +* El cobrador genera un cobro usando la API y despliega un botón para la compra. +* El pagador pincha el botón de pago en el sitio web, o un enlace de pago en un correo electrónico u otro medio y paga utilizando Khipu. +* El pagador es redireccionado a la página de retorno definida por el cobrador donde se debe indicar que el pago está en verificación (o a la página de fracaso en el caso que no se haya podido hacer el pago). +* Unos momentos después Khipu verifica la transacción y notifica al pagador por correo electrónico. Además, se notifica al comercio por correo electrónico y/o por la invocación de un web service. +* El cobrador valida la notificación de pago y entrega el bien transado al pagador (o descarta la notificación si es inválida) + +## Obtener Bancos + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Banks.get() +``` + +Este método obtiene el listado de bancos asociado a la cuenta. + +```json +{ + "banks": [ + { + "bank_id": "Bawdf", + "logo_url": "https://s3.amazonaws.com/static.khipu.com/logos/bancos/chile/demobank-icon.png", + "message": "Este es un banco de pruebas. Las transacciones no son reales.", + "min_amount": "200.0000", + "name": "DemoBank", + "parent": "", + "type": "Persona" + } + ] +} +``` + +## Crear Pago + +Crea un pago en Khipu y obtiene las URLs para redirección al usuario para que complete el pago. + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Payments.create(amount=10000, currency="CLP", subject="Pago de prueba") +``` + +El listado completo de variables se encuentra descrita en la [api de khipu](https://docs.khipu.com/openapi/es/v1/instant-payment/openapi/operation/postPayment/) + +Respuesta + +```json +{ + "payment_id": "gqzdy6chjne9", + "payment_url": "https://khipu.com/payment/info/gqzdy6chjne9", + "simplified_transfer_url": "https://app.khipu.com/payment/simplified/gqzdy6chjne9", + "transfer_url": "https://khipu.com/payment/manual/gqzdy6chjne9", + "app_url": "khipu:///pos/gqzdy6chjne9", + "ready_for_terminal": false +} +``` + +## Obtener información de un Pago + +Información completa del pago. Datos con los que fue creado y el estado actual del pago. + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Payments.get(payment_id="gqzdy6chjne9") +``` + +Respuesta + +```json +{ + "payment_id": "gqzdy6chjne9", + "payment_url": "https://khipu.com/payment/info/gqzdy6chjne9", + "simplified_transfer_url": "https://app.khipu.com/payment/simplified/gqzdy6chjne9", + "transfer_url": "https://khipu.com/payment/manual/gqzdy6chjne9", + "app_url": "khipu:///pos/gqzdy6chjne9", + "ready_for_terminal": false, + "notification_token": "9dec8aa176c5223026919b3b5579a4776923e646ff3be686b9e6b62ec042e91f", + "receiver_id": 985101, + "conciliation_date": "2017-03-01T13:00:00.000Z", + "subject": "Test", + "amount": 1000, + "currency": "CLP", + "status": "done", + "status_detail": "normal", + "body": "Test", + "picture_url": "https://micomercio.com/picture_url", + "receipt_url": "https://micomercio.com/order/receipt_url", + "return_url": "https://micomercio.com/order/return_url", + "cancel_url": "https://micomercio.com/order/cancel_url", + "notify_url": "https://micomercio.com/webhook/notify_url", + "notify_api_version": "3.0", + "expires_date": "2023-12-31T15:45:00-04:00", + "attachment_urls": [ + "https://micomercio.com/attachment1.pdf" + ], + "bank": "Banco de Chile (Edwards Citi)", + "bank_id": "dfFbF", + "payer_name": "Nombre Pagador", + "payer_email": "pagador@email.com", + "personal_identifier": "11.000.111-9", + "bank_account_number": "001120490689", + "out_of_date_conciliation": true, + "transaction_id": "zwo3wqz6uulcvajt", + "custom": "...", + "responsible_user_email": "responsible@email.com", + "send_reminders": true, + "send_email": true, + "payment_method": "simplified_transfer", + "funds_source": "debit", + "discount": 0, + "third_party_authorization_details": "string" +} +``` + +## Eliminar Pago + +Borrar un pago. Solo se pueden borrar pagos que estén pendientes de pagar. Esta operación no puede deshacerse. + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Payments.delete(payment_id="gqzdy6chjne9") +``` + +Respuesta + +```json +{ + "message": "Message" +} +``` + +## Predecir Pago + +Predicción acerca del resultado de un pago, si podrá o no funcionar. Información adicional como máximo posible de transferir a un nuevo destinatario. + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Predict.get( + payer_email="pagador@email.com", + amount="5000000", + currency="CLP", + bank_id="Bawdf", +) +``` + +Respuesta + +```json +{ + "result": "ok", + "max_amount": 5000000, + "cool_down_date": "2024-06-21T11:23:09.123Z", + "new_destinatary_max_amount": 100000 +} +``` + +## Medios de Pago + +Obtiene el listado de medios de pago disponible para una cuenta de cobrador. + +```py +import khipu_tools + +khipu_tools.api_key = "khipu-apiv3-key +khipu_tools.Payments.methods(cuenta_cobro="12345") +``` + +Respuesta + +```json +{ + "paymentMethods": [ + { + "id": "simplified_transfer", + "name": "simplified_transfer", + "logo_url": "https://s3.amazonaws.com/static.khipu.com/buttons/2015/150x50-transparent.png" + } + ] +} +``` diff --git a/khipu_tools/__init__.py b/khipu_tools/__init__.py index 93ed814..b77b6b4 100644 --- a/khipu_tools/__init__.py +++ b/khipu_tools/__init__.py @@ -1,10 +1,3 @@ -from khipu_tools._predict import Predict as Predict -from khipu_tools._banks import Banks as Banks -from khipu_tools._http_client import ( - new_default_http_client as new_default_http_client, -) -from khipu_tools._khipu_client import KhipuClient as KhipuClient -from khipu_tools._api_resource import APIResource as APIResource from typing import Optional from typing_extensions import Literal @@ -51,3 +44,17 @@ def set_app_info( # Infrastructure types +from khipu_tools._khipu_client import KhipuClient as KhipuClient +from khipu_tools._api_resource import APIResource as APIResource + + +from khipu_tools._http_client import ( + new_default_http_client as new_default_http_client, +) + + +from khipu_tools._banks import Banks as Banks + +from khipu_tools._payments import Payments as Payments + +from khipu_tools._predict import Predict as Predict diff --git a/khipu_tools/_banks.py b/khipu_tools/_banks.py index 09b0d9f..e258d04 100644 --- a/khipu_tools/_banks.py +++ b/khipu_tools/_banks.py @@ -9,13 +9,24 @@ class BankItem: + """ + Informacion de banco + """ + bank_id: str + """Identificador del banco.""" name: str + """Nombre del banco.""" message: str + """Mensaje con particularidades del banco.""" min_amount: int + """Monto mínimo que acepta el banco en un pago""" type: Literal["Persona", "Empresa"] + """Tipo de banco.""" parent: str + """Identificador del banco padre (si un banco tiene banca personas y empresas, el primero será el padre del segundo).""" logo_url: str + """URL del logo del banco.""" class Banks(APIResource[T]): @@ -23,6 +34,7 @@ class Banks(APIResource[T]): OBJECT_PREFIX: ClassVar[Literal["v3"]] = "v3" banks: list[BankItem] + """Listado con Bancos registrados""" @classmethod def get(cls) -> KhipuObject["Banks"]: diff --git a/khipu_tools/_payments.py b/khipu_tools/_payments.py new file mode 100644 index 0000000..c17238a --- /dev/null +++ b/khipu_tools/_payments.py @@ -0,0 +1,222 @@ +from decimal import Decimal +from typing import ClassVar, Optional, TypeVar + +from typing_extensions import Literal, Unpack + +from khipu_tools._api_resource import APIResource +from khipu_tools._khipu_object import KhipuObject +from khipu_tools._request_options import RequestOptions + +T = TypeVar("T", bound=KhipuObject) + + +class Payments(APIResource[T]): + OBJECT_NAME: ClassVar[Literal["Payment"]] = "payments" + OBJECT_PREFIX: ClassVar[Literal["v3"]] = "v3" + + class PaymentParams(RequestOptions): + """ + Parametros de creacion de pago + """ + + amount: str + """ El monto del cobro. Sin separador de miles y usando '.' como separador de decimales. Hasta 4 lugares decimales, dependiendo de la moneda. """ + currency: Literal["CLP", "CLF", "ARS", "PEN", "MXN", "USD", "EUR", "BOB", "COP"] + """El código de moneda en formato ISO-4217.""" + subject: str + """Motivo.""" + transaction_id: Optional[str] + """Identificador propio de la transacción. Ej: número de factura u orden de compra.""" + custom: Optional[str] + """Parámetro para enviar información personalizada de la transacción. Ej: documento XML con el detalle del carro de compra.""" + body: Optional[str] + """Descripción del cobro.""" + bank_id: Optional[str] + """Identificador del banco para usar en el pago.""" + return_url: Optional[str] + """La dirección URL a donde enviar al cliente mientras el pago está siendo verificado.""" + cancel_url: Optional[str] + """La dirección URL a donde enviar al cliente si decide no hacer hacer la transacción.""" + picture_url: Optional[str] + """Una dirección URL de una foto de tu producto o servicio.""" + notify_url: Optional[str] + """La dirección del web-service que utilizará khipu para notificar cuando el pago esté conciliado.""" + contract_url: Optional[str] + """La dirección URL del archivo PDF con el contrato a firmar mediante este pago. El cobrador debe estar habilitado para este servicio y el campo fixed_payer_personal_identifier es obligatorio.""" + notify_api_version: Literal["3.0"] + """Versión de la API de notificaciones para recibir avisos por web-service. Solo está soportada la version 3.0. para versiones anteriores pyeden usar la libreria pykhipu""" + expires_date: Optional[str] + """Fecha máxima para ejecutar el pago (en formato ISO-8601). El cliente podrá realizar varios intentos de pago hasta dicha fecha. Cada intento tiene un plazo individual de 3 horas para su ejecución.""" + send_email: Optional[bool] + """Si es True, se enviará una solicitud de cobro al correo especificado en payer_email.""" + payer_name: Optional[str] + """Nombre del pagador. Es obligatorio cuando send_email es true.""" + payer_email: Optional[str] + """Correo del pagador. Es obligatorio cuando send_email es true.""" + send_reminders: Optional[bool] + """Si es true, se enviarán recordatorios de cobro.""" + responsible_user_email: Optional[str] + """Correo electrónico del responsable de este cobro, debe corresponder a un usuario Khipu con permisos para cobrar usando esta cuenta de cobro.""" + fixed_payer_personal_identifier: Optional[str] + """Identificador personal. Si se especifica, solo podrá ser pagado usando ese identificador.""" + integrator_fee: Optional[str] + """Comisión para el integrador. Sólo es válido si la cuenta de cobro tiene una cuenta de integrador asociada.""" + collect_account_uuid: Optional[str] + """Para cuentas de cobro con más cuenta propia. Permite elegir la cuenta donde debe ocurrir la transferencia.""" + confirm_timeout_date: Optional[str] + """Fecha de rendición del cobro. Es también la fecha final para poder reembolsar el cobro. Formato ISO-8601.""" + mandatory_payment_method: Optional[str] + """El cobro sólo se podrá pagar utilizando el medio de pago especificado. Los posibles valores para este campo se encuentran en el campo id de la respuesta del endpoint /api/3.0/merchants/paymentMethods.""" + psp_client_merchant_name: Optional[str] + """Nombre del comercio final para quien un proveedor de servicios de pago procesa un pago. Requerido para transacciones de clientes PSP; no aplicable para otros.""" + + class PaymentCreateResponse(KhipuObject): + payment_id: str + """Identificador único del pago, es una cadena alfanumérica de 12 caracteres. Como este identificador es único, se puede usar, por ejemplo, para evitar procesar una notificación repetida. (Khipu espera un código 200 al notificar un pago, si esto no ocurre se reintenta hasta por dos días).""" + payment_url: str + """URL principal del pago, si el usuario no ha elegido previamente un método de pago se le muestran las opciones.""" + simplified_transfer_url: str + """URL de pago simplificado.""" + transfer_url: str + """URL de pago normal.""" + app_url: str + """URL para invocar el pago desde un dispositivo móvil usando la APP de Khipu.""" + ready_for_terminal: bool + """Es true si el pago ya cuenta con todos los datos necesarios para abrir directamente la aplicación de pagos Khipu.""" + + class PaymentInfo(RequestOptions): + payment_id: str + """Identificador del pago""" + + payment_id: str + """Identificador único del pago, es una cadena alfanumérica de 12 caracteres. Como este identificador es único, se puede usar, por ejemplo, para evitar procesar una notificación repetida. (Khipu espera un código 200 al notificar un pago, si esto no ocurre se reintenta hasta por dos días).""" + payment_url: str + """URL principal del pago, si el usuario no ha elegido previamente un método de pago se le muestran las opciones.""" + simplified_transfer_url: str + """URL de pago simplificado.""" + transfer_url: str + """URL de pago normal.""" + app_url: str + """URL para invocar el pago desde un dispositivo móvil usando la APP de Khipu.""" + ready_for_terminal: bool + """Es true si el pago ya cuenta con todos los datos necesarios para abrir directamente la aplicación de pagos Khipu.""" + notification_token: str + """Cadena de caracteres alfanuméricos que identifican unicamente al pago, es el identificador que el servidor de Khipu enviará al servidor del comercio cuando notifique que un pago está conciliado.""" + receiver_id: int + """Identificador único de una cuenta de cobro.""" + conciliation_date: str + """Fecha y hora de conciliación del pago. Formato ISO-8601.""" + subject: str + """Motivo del pago.""" + amount: Decimal + """El monto del cobro.""" + currency: str + """El código de moneda en formato ISO-4217.""" + status: Literal["pending", "verifying", "done"] + """Estado del pago, puede ser pending (el pagador aún no comienza a pagar), verifying (se está verificando el pago) o done, cuando el pago ya está confirmado.""" + status_detail: Literal[ + "pending", + "normal", + "marked-paid-by-receiver", + "rejected-by-payer", + "marked-as-abuse", + "reversed", + ] + """Detalle del estado del pago: pending (el pagador aún no comienza a pagar), normal (el pago fue verificado y fue cancelado por algún medio de pago estándar), marked-paid-by-receiver (el cobrador marcó el cobro como pagado por otro medio), rejected-by-payer (el pagador declaró que no pagará), marked-as-abuse (el pagador declaró que no pagará y que el cobro fue no solicitado), y reversed (el pago fue anulado por el comercio, el dinero fue devuelto al pagador).""" + body: str + """Detalle del cobro.""" + picture_url: str + """URL con imagen del cobro.""" + receipt_url: str + """URL del comprobante de pago.""" + return_url: str + """URL donde se redirige al pagador luego que termina el pago.""" + cancel_url: str + """URL donde se redirige al pagador luego de que desiste hacer el pago.""" + notify_url: str + """URL del webservice donde se notificará el pago.""" + notify_api_version: Literal["3,0"] + """Versión de la API de notificación.""" + expires_date: str + """Fecha máxima para ejecutar el pago (en formato ISO-8601). El cliente podrá realizar varios intentos de pago hasta dicha fecha. Cada intento tiene un plazo individual de 3 horas para su ejecución.""" + attachment_urls: list[str] + """Arreglo de URLs de archivos adjuntos al pago.""" + bank: str + """Nombre del banco seleccionado por el pagador.""" + bank_id: str + """Identificador del banco seleccionado por el pagador.""" + payer_name: str + """Nombre del pagador.""" + payer_email: str + """Correo electrónico del pagador.""" + personal_identifier: str + """Identificador personal del pagador.""" + bank_account_number: str + """Número de cuenta bancaria del pagador.""" + out_of_date_conciliation: bool + """Es true si la conciliación del pago fue hecha luego de la fecha de expiración.""" + transaction_id: str + """Identificador del pago asignado por el cobrador.""" + custom: str + """Campo genérico que asigna el cobrador al momento de hacer el pago.""" + responsible_user_email: str + """Correo electrónico de la persona responsable del pago.""" + send_reminders: bool + """Es true cuando este es un cobro por correo electrónico y Khipu enviará recordatorios.""" + send_email: bool + """Es true cuando Khipu enviará el cobro por correo electrónico.""" + payment_method: Literal["regular_transfer", "simplified_transfer", "not_available"] + """Método de pago usado por el pagador, puede ser regular_transfer (transferencia normal) o simplified_transfer (transferencia simplificada).""" + funds_source: Literal["debit", "prepaid", "credit", "not-available", ""] + """Origen de fondos usado por el pagador, puede ser debit para pago con débito, prepaid para pago con prepago, credit para pago con crédito, o vacío en el caso de que se haya pagado mediante transferencia bancaria.""" + discount: int + """Monto a descontar del valor pagado.""" + third_party_authorization_details: str + """Ignorar este campo.""" + + @classmethod + def create( + cls, **params: Unpack["Payments.PaymentParams"] + ) -> KhipuObject["Payments.PaymentCreateResponse"]: + """ + Crea un pago en Khipu y obtiene las URLs para redirección al usuario para que complete el pago. + """ + result = cls._static_request( + "post", + cls.class_url(), + params=params, + ) + if not isinstance(result, KhipuObject): + raise TypeError( + "Expected KhipuObject object from API, got %s" % (type(result).__name__) + ) + + return result + + @classmethod + def get(cls, **params: Unpack["Payments.PaymentInfo"]) -> KhipuObject["Payments"]: + """ + Información completa del pago. Datos con los que fue creado y el estado actual del pago. + """ + result = cls._static_request( + "get", + f"{cls.class_url()}/{params['payment_id']}", + ) + if not isinstance(result, KhipuObject): + raise TypeError( + "Expected KhipuObject object from API, got %s" % (type(result).__name__) + ) + + return result + + @classmethod + def delete(cls, **params: Unpack["Payments.PaymentInfo"]) -> bool: + """ + Borrar un pago. Solo se pueden borrar pagos que estén pendientes de pagar. Esta operación no puede deshacerse. + """ + result = cls._static_request( + "delete", + f"{cls.class_url()}/{params['payment_id']}", + ) + + return result diff --git a/khipu_tools/_predict.py b/khipu_tools/_predict.py index ffce1d2..0986783 100644 --- a/khipu_tools/_predict.py +++ b/khipu_tools/_predict.py @@ -15,14 +15,28 @@ class Predict(APIResource[T]): class PredictParams(RequestOptions): payer_email: str + """Correo electrónico del pagador""" bank_id: str + """Identificador del banco de origen""" amount: str + """Monto del pago""" currency: str - - result: str + """Moneda en formato ISO-4217""" + + result: Literal[ + "ok", + "new_destinatary_amount_exceeded", + "max_amount_exceeded", + "new_destinatary_cool_down", + "not_available_account", + ] + """El resultado de la predicción.""" max_amount: int + """El monto máximo posible para transferir.""" cool_down_date: str + """Fecha de término para la restricción de monto en formato ISO-8601""" new_destinatary_max_amount: str + """Monto máximo para transferir a un nuevo destinatario.""" @classmethod def get(cls, **params: Unpack["Predict.PredictParams"]) -> KhipuObject["Predict"]: @@ -37,7 +51,7 @@ def get(cls, **params: Unpack["Predict.PredictParams"]) -> KhipuObject["Predict" ) if not isinstance(result, KhipuObject): raise TypeError( - "Expected SripeObject object from API, got %s" % (type(result).__name__) + "Expected KhipuObject object from API, got %s" % (type(result).__name__) ) return result diff --git a/mkdocs.yml b/mkdocs.yml index 51dec67..21710a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,11 +35,11 @@ plugins: nav: - Inicio: index.md - # - Uso: uso.md - # - Integraciones: providers.md - # - Referencia: api.md - # - Colabora: contributing.md - # - Cambios: CHANGELOG.md + - Pagos Instantáneos: pagos-instantaneos.md + - Pagos Automáticos: pagos-automaticos.md + - API: api.md + - Colabora: contributing.md + - Cambios: CHANGELOG.md markdown_extensions: - abbr diff --git a/pyproject.toml b/pyproject.toml index f72c6bd..17d3864 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,11 +21,7 @@ classifiers = [ ] keywords = ["khipu", "pagos", "transferencias"] -dependencies = [ - "python-dateutil", - "python-slugify>=8.0.4", - "requests>=2.32.3", -] +dependencies = ["python-dateutil", "python-slugify>=8.0.4", "requests>=2.32.3"] [project.urls] Repository = "http://github.com/mariofix/khipu-tools" @@ -33,13 +29,11 @@ Homepage = "http://mariofix.github.io/khipu-tools" [build-system] -requires = ["setuptools", "wheel"] -build-backend = "setuptools.build_meta" +requires = ["hatchling"] +build-backend = "hatchling.build" -[tool.setuptools.packages.find] -include = ["khipu_tools"] +[project.optional-dependencies] -[dependency-groups] dev = [ "pylint", "mock",