diff --git a/README.md b/README.md index 527497f..6e4baf7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # django-payments-chile +**django-payments-chile** es una librería diseñada para facilitar la integración de pagos en aplicaciones Django a través de múltiples proveedores en Chile. Este proyecto ofrece una API simple y flexible para procesar pagos de manera segura, permitiendo a los desarrolladores concentrarse en construir sus aplicaciones sin complicarse con la lógica de integración de cada proveedor. + ![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) @@ -10,8 +12,6 @@ ![PyPI - Implementation](https://img.shields.io/pypi/implementation/django-payments-chile) ![PyPI - License](https://img.shields.io/pypi/l/django-payments-chile) -**django-payments-chile** es una librería diseñada para facilitar la integración de pagos en aplicaciones Django a través de múltiples proveedores en Chile. Este proyecto ofrece una API simple y flexible para procesar pagos de manera segura, permitiendo a los desarrolladores concentrarse en construir sus aplicaciones sin complicarse con la lógica de integración de cada proveedor. - ## Proveedores de pago soportados - **Flow**: Plataforma chilena para pagos en línea que admite múltiples métodos de pago. @@ -35,65 +35,33 @@ Para instalar la librería, utiliza pip: ```bash -pip install django-payments-chile +pip install django-payments-chile[todos] ``` +- **flow**: Instala extras para Flow. +- **khipu**: Instala extras para Khipu. +- **todos**: Instala todos los extras. + ### Configuración de Proveedores Agrega las credenciales de los proveedores de pago en tu archivo de configuración: ```python -PAYMENTS_PROVIDERS = { - 'FLOW': { +PAYMENT_VARIANTS = { + 'flow': ('django_payments_chile.FlowProvider', { 'api_key': 'tu_api_key_flow', 'secret': 'tu_secret_flow', - }, - 'KHIPU': { - 'receiver_id': 'tu_receiver_id', - 'secret': 'tu_secret_khipu', - }, - 'WEBPAY': { + }), + 'webpay': ('django_payments_chile.WebpayProvider', { 'commerce_code': 'tu_commerce_code_webpay', 'api_key': 'tu_api_key_webpay', - }, - ... + }), } ``` ## Uso -Para crear y procesar un pago con **django-payments-chile**, simplemente importa el gateway y realiza la transacción: - -```python -from payments_chile import PaymentGateway - -gateway = PaymentGateway(provider='webpay') -response = gateway.create_payment(amount=10000, order_id='123456', return_url='https://tu-sitio.com/return/') -``` - -Luego, puedes verificar el estado del pago: - -```python -if gateway.verify_payment(response): - # Pago exitoso -else: - # Pago fallido -``` - -## Proveedores adicionales - -Puedes agregar más proveedores de pago mediante la extensión del gateway o contribuyendo con tus propias integraciones. Cada proveedor tiene una interfaz consistente para facilitar su uso y configuración. - -## Contribuciones - -Contribuciones son bienvenidas. Por favor, abre un [issue](https://github.com/mariofix/django-payments-chile/issues) o envía un pull request. - -Pasos para contribuir: - -1. Haz un fork del repositorio. -2. Crea una rama nueva para tu funcionalidad (`git checkout -b feature-nueva-funcionalidad`). -3. Realiza los cambios y asegúrate de probarlos. -4. Envía un pull request con una descripción clara de tu contribución. +AGREGAR INSTALACION Y PASOS DE CONFIGURACION DE DJANGO-PAYMETNTS ## Licencia diff --git a/docs/index.md b/docs/index.md index a959c25..a1c3484 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,12 +22,14 @@ ### Instalación -Asegúrate de tener `django-payments` instalado, luego instala `django-payments-chile`: - ```bash -pip install django-payments django-payments-chile +pip install django-payments-chile[chile] ``` +- **flow**: Instala extras para Flow. +- **khipu**: Instala extras para Khipu. +- **todos**: Instala todos los extras. + ### Configuración En tu archivo `settings.py`, configura los proveedores de pago que vas a utilizar: @@ -46,16 +48,6 @@ PAYMENT_VARIANTS = { } ``` -Asegúrate de haber agregado `payments` a `INSTALLED_APPS`: - -```python -INSTALLED_APPS = [ - ..., - 'payments', - 'payments_chile', -] -``` - ### Creación de un nuevo pago Con django-payments ya configurado, puedes crear un nuevo pago utilizando los métodos nativos de la librería: @@ -66,7 +58,7 @@ from payments import get_payment_model Payment = get_payment_model() payment = Payment.objects.create( - variant='flow', # o 'webpay', 'khipu', etc. + variant='flow', # o 'webpay', 'khipu', debe coincidir con el indice en PAYMENT_VARIANTS description="Pago por Orden #123", total=10000, currency='CLP', diff --git a/docs/uso.md b/docs/uso.md index 51ceda4..89bee55 100644 --- a/docs/uso.md +++ b/docs/uso.md @@ -1,80 +1,138 @@ -# Como Usar +# ¿Qué es django-payments-chile? -## Instalación +`django-payments-chile` es una extensión de Django que te permite procesar pagos en Chile fácilmente. Funciona con `django-payments`, que es una biblioteca más general para manejar pagos en Django. -Para utilizar el módulo `django-payments-flow`, puedes realizar la instalación mediante el uso de pip o poetry. +## Paso 1: Preparar tu entorno -=== "usando pip" - ```shell - pip install django-payments-flow - ``` -=== "usando poetry" - ```shell - poetry add django-payments-flow - ``` +Antes de empezar, asegúrate de tener: -## Configuración +1. Python instalado en tu computadora. +2. Django instalado y un proyecto Django creado. -La configuración del módulo django-payments-flow se realiza como una variante -de Django Payments. Debes agregar la siguiente configuración en tu archivo de -configuración de Django: +Si no tienes Django, puedes instalarlo con: + +```bash +pip install django +``` + +Y crear un nuevo proyecto Django con: + +```bash +django-admin startproject miproyecto +cd miproyecto +``` + +## Paso 2: Instalar las bibliotecas necesarias + +Ahora, vamos a instalar `django-payments` y `django-payments-chile`: + +```bash +pip install django-payments django-payments-chile +``` + +## Paso 3: Configurar tu proyecto Django + +### 3.1 Modificar settings.py + +Abre el archivo `settings.py` en tu proyecto Django y agrega estas líneas: ```python +INSTALLED_APPS = [ + # ... tus otras apps ... + "payments", +] + +# Configuración para payments +PAYMENT_HOST = 'tudominio.cl' # Cambia esto por tu dominio real +PAYMENT_USES_SSL = True # Usa False si no tienes HTTPS +PAYMENT_MODEL = 'pagos.modelos.Pago' + +# Configuración para django-payments-chile (ejemplo con Flow) PAYMENT_VARIANTS = { - "flow": ("django_payments_flow.FlowProvider", { - "api_key": "flow_key", - "api_secret": "flow_secret", + "flow": ("django_payments_chile.FlowProvider", { + "api_key": "tu_api_key_de_flow", + "api_secret": "tu_api_secret_de_flow", }) } ``` -Por defecto las llamadas se realizan al ambiente de produccion de Flow, si -quieres realizar llamadas al ambiente sandbox debes agregar -`"endpoint": "sandbox"` a la configuracion +Nota: Reemplaza 'tudominio.cl', 'tu_api_key_de_flow' y 'tu_api_secret_de_flow' con tus datos reales. + +### 3.2 Modificar urls.py + +Abre el archivo `urls.py` principal de tu proyecto y agrega esta línea: ```python -PAYMENT_VARIANTS = { - "flow": ("django_payments_flow.FlowProvider", { - "api_key": "flow_key", - "api_secret": "flow_secret", - "api_endpoint": "sandbox" - }) -} +from django.urls import include, path + +urlpatterns = [ + # ... tus otras URLs ... + path('payments/', include('payments.urls')), +] ``` -### Variables de configuración +## Paso 4: Crear un modelo de pago -* `api_endpoint`: Valor de ambiente de Flow, puede ser "live o "sandbox" (Valor por - defecto: live) -* `api_key`: Este valor corresponde a la cuenta entregada por Flow para -identificar al receptor de los pagos. -* `api_secret`: Este valor corresponde a la contraseña entregada por Khipu para -autenticar la comunicación con su plataforma. -* `api_medio`: Este valor indica si quieres utilizar algun medio de pago especifico -segun lo indicado en -[FlowAPI](https://www.flow.cl/docs/api.html#section/Introduccion/Realizar-pruebas-en-nuestro-ambiente-Sandbox) -(Valor por defecto: 9) +Crea un nuevo archivo llamado `modelos.py` en una app de tu proyecto (por ejemplo, en una app llamada 'pagos') y agrega este código: -## Datos Extra +```python +from django.conf import settings +from payments.models import BasePayment -El módulo `django-payments-flow` permite enviar datos extra en cada pago. Para -hacerlo, debes utilizar un objeto JSON dentro de la propiedad "attrs" del -modelo de Pagos. +class Pago(BasePayment): + def get_failure_url(self) -> str: + return f"https://{settings.PAYMENT_HOST}/payments/{self.pk}/failure" + + def get_success_url(self) -> str: + return f"https://{settings.PAYMENT_HOST}/payments/{self.pk}/success" +``` -Por ejemplo, si deseas enviar un limite de 5 minutos para cada compra, puedes -utilizar el siguiente código: +No olvides crear la app 'pagos' si no existe: + +```bash +python manage.py startapp pagos +``` + +Y agrégala a INSTALLED_APPS en settings.py: ```python -datos_extra: dict = { - "timeout": 300, -} -payment.attrs.datos_extra = datos_extra -payment.save() +INSTALLED_APPS = [ + # ... otras apps ... + "pagos", +] ``` -Puedes proporcionar un diccionario unidimensional con los valores extra que -deseas enviar en cada pago. +## Paso 5: Usar django-payments-chile en tu vista + +Ahora puedes usar django-payments-chile en tus vistas. Aquí tienes un ejemplo: + +```python +from django.shortcuts import redirect +from payments import get_payment_model + +def crear_pago(request): + Payment = get_payment_model() + payment = Payment.objects.create( + variant='flow', # Esto debe coincidir con lo que pusiste en PAYMENT_VARIANTS + description="Pago por Orden #123", + total=10000, # Monto en centavos (100 pesos) + currency='CLP', + billing_first_name='Juan', + billing_last_name='Pérez', + billing_email='juan.perez@example.com', + ) + return redirect(payment.get_process_url()) +``` + +## Paso 6: Crear las páginas de éxito y fracaso + +No olvides crear las páginas a las que se redirigirá después del pago (éxito o fracaso). Puedes hacerlo creando nuevas vistas y templates. + +## Consejos finales + +1. Siempre prueba en un entorno de desarrollo antes de ir a producción. +2. Mantén seguros tus datos de API (keys, secrets). No los subas a repositorios públicos. +3. Lee la documentación oficial de django-payments y django-payments-chile para más detalles. +4. ¡No dudes en pedir ayuda en foros de Django si te atascas! -Cabe destacar que los valores `apiKey`, `commerceOrder`, `subject`, `amount`, -`email`, `urlConfirmation`, `urlReturn`, `s` no pueden ser utilizados como -datos extra y serán ignorados al momento de crear el pago. +Recuerda que cada paso puede requerir más configuración dependiendo de tu proyecto específico. diff --git a/mkdocs.yml b/mkdocs.yml index 57dde19..b876701 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,11 @@ site_name: Django Payments Chile repo_url: https://github.com/mariofix/django-payments-chile -repo_name: django-payments-chile +repo_name: mariofix/django-payments-chile +site_url: https://mariofix.github.io/django-payments-chile +site_description: Documentacion para Django Payments +site_author: mariofix +copyright: "MIT License" +edit_uri: "" theme: name: material diff --git a/pyproject.toml b/pyproject.toml index 5feb109..5ac3d12 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,10 +26,10 @@ classifiers = [ [tool.poetry.dependencies] python = "^3.9" -django-payments = ">=2.0.0, <4.0" +django-payments = ">=2.0, <4.0" requests = "^2.32.3" -pyflowcl = { version = "^2024.9.28", optional = true } +pyflowcl = { version = "^2024.9", optional = true } pykhipu = { version = "^0.1.9", optional = true } transbank-sdk = { version = "^5.0.0", optional = true }