Integración de Pagos Personalizada

Este documento explica cómo Monetization permite el soporte de procesamiento de pagos para proveedores de pagos de terceros no compatibles de forma nativa o para casos en los que decida manejar la lógica de procesamiento de pagos fuera de Monetization a través de sus procesos de integración.
Categoría:

Temas en este documento:

Procesamiento de pagos de terceros en Monetization

El procesamiento de pagos de terceros se puede lograr a través de dos métodos: síncrono y asíncrono. El método síncrono requiere respuestas inmediatas de su componente de integración de pagos, mientras que el método asíncrono combina la extracción de facturas definitivas de Monetization y luego la importación de los pagos en un momento posterior.

Procesamiento de pagos asíncrono

Para el procesamiento de pagos asíncrono, usted exporta las facturas definitivas de Monetization y los pagos se procesan completamente fuera de Monetization. Cuando tenga los resultados del procesamiento de pagos, los importa a través de archivos CSV (valores separados por comas) o la API (interfaz de programación de aplicaciones) de Monetization.

Exportación de facturas definitivas

Puede exportar facturas definitivas de Monetization configurando un mapeador de exportación de facturas y programando un trabajo de exportación, que exportará los archivos a una ubicación SFTP (Protocolo de Transferencia de Archivos SSH), o suscribiéndose a una creación de factura definitiva vía Webhook, que activará una solicitud de factura a la dirección URL (localizador de recursos uniforme) proporcionada cada vez que se cree una nueva factura definitiva.

Trabajo de exportación – archivo CSV a SFTP

Para exportar facturas definitivas como archivos CSV, se debe configurar un mapeador de exportación de facturas (Invoice Export mapper) para mapear los parámetros de la factura a las columnas del archivo CSV. La interfaz de usuario de Monetization permite dicha configuración en Business configuration Export Invoice mappers.

Ejemplo de configuración del mapeador de exportación de facturas Figura 1: Ejemplo de configuración del mapeador de exportación de facturas

Las exportaciones de facturas se programan a través de Exporting Jobs (trabajos de exportación), que pueden ser tareas únicas o automatizadas para ejecutarse durante períodos específicos. El trabajo de exportación guardará el archivo CSV exportado en la ubicación SFTP respectiva storage/invoice/folder_name/file_name.csv.

Ejemplo de trabajo de exportación de facturas Figura 2: Ejemplo de trabajo de exportación de facturas

Notificación - método webhook

La exportación de facturas definitivas a través de webhooks le permite recibir las facturas inmediatamente después de su creación. Esto se logra configurando una regla de notificación de factura (Invoice Notification Rule), que enviará cada factura creada como una solicitud de cuerpo JSON (Notación de Objetos de JavaScript) a la dirección URL proporcionada, junto con cualquier opción de encabezado preconfigurada.

Ejemplo de configuración de webhook de creación de facturas Figura 3: Ejemplo de configuración de webhook de creación de facturas

Importación de pagos

Puede importar transacciones de pago a Monetization configurando un mapeador de importación de pagos y cargando los archivos CSV de pago en la ubicación de entrada SFTP o utilizando la API REST (Transferencia de Estado Representacional) de Monetization.

Importación de archivos CSV vía SFTP

Para que Monetization importe transacciones de pago a través de archivos CSV, debe haber un mapeador de importación de pagos (Payment Import Mapper) configurado. La configuración es posible a través de la interfaz de usuario de Monetization en Business configuration Import Payment mappers.

El mapeador de pagos permite el mapeo de las columnas CSV a los parámetros de la transacción de pago y la definición de un prefijo de archivo, que debe estar presente en los archivos cargados.

Los archivos se cargan en el servidor SFTP en la carpeta edl/input y se moverán a las carpetas edl/processed, edl/successful, edl/error y edl/rejected según los resultados del procesamiento.

Ejemplo de configuración del mapeador de importación de pagos Figura 4: Ejemplo de configuración del mapeador de importación de pagos

Importación a través de llamada a la API

Para importar una transacción de pago a través de la API de Monetization, envíe una solicitud JSON que contenga los detalles de la transacción a la API REST de Monetization.

Autenticación

La API de Monetization utiliza autenticación de tipo Bearer Token:

  1. Ejecute la solicitud de autenticación (Authentication) con el nombre de usuario, la contraseña y el código de sitio específico.
  2. Obtenga el token de la respuesta.
  3. Establezca el encabezado Authorization como Bearer <token> en las próximas solicitudes.
  4. El token expira después de 5 minutos.
URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "su_nombre_de_usuario_de_monetization",
    "password": "password",
    "site_code": "su_codigo_de_sitio_de_monetization - subdominio"
}
Solicitud de importación de pago
URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Procesamiento de pagos síncrono

El procesamiento de pagos síncrono requiere una comunicación síncrona entre Monetization y su componente de integración de pagos. Este método de procesamiento permite autorizaciones de tarjetas de crédito/débito y pagos inmediatos.

Usted configura Monetization para especificar a dónde deben enviarse las solicitudes relacionadas con el procesamiento de pagos, y Monetization tiene respuestas predefinidas que espera recibir. Este método de procesamiento permite el almacenamiento de referencias de métodos de pago en los clientes y admite procesos automatizados de cobro de pagos.

Para Monetization, el proceso de integración es prácticamente el mismo que una integración nativa con un proveedor existente (Stripe, Braintree, etc.). Sin embargo, la comunicación se ejecuta a través de un componente desarrollado por usted, que actúa como una pasarela hacia su proveedor de pagos local.

Operaciones esenciales para admitir el procesamiento de pagos síncrono:

  • Setup Intent (Intención de configuración)
  • Authorize (Autorizar)
  • Capture (Capturar)
  • Charge (Cargar)

Configuración del proveedor de pagos de terceros

Para configurar una integración de proveedor de pagos de terceros, configure un perfil de pasarela de pago de terceros (third-party payment gateway profile) y proporcione la URL donde Monetization debe enviar las solicitudes.

Esto se puede lograr a través de la interfaz de usuario en System configuration Payment gateways, o creando un perfil de pasarela de pago a través de la API REST de Monetization.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL de su pasarela de pago"
    }
}

Operaciones del cliente

Las operaciones del cliente solo se aplican en los casos en que el proveedor de pagos de terceros admite la gestión de clientes. Si el proveedor de pagos no admite la gestión de clientes, entonces los ids de los clientes pueden reemplazarse por cualquier valor (por ejemplo, la marca de tiempo Unix de la solicitud).

Crear cliente (sin tarjeta)

Crea un cliente como un objeto en el servicio del proveedor de pagos.

Solicitud enviada por Monetization:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Respuesta esperada:

Estado HTTP: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Actualizar cliente

Actualiza un objeto de cliente en el servicio del proveedor de pagos.

Solicitud enviada por Monetization:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Respuesta esperada:

Estado HTTP: 204 No Content

Sin cuerpo de respuesta

Leer cliente

Lee un objeto de cliente del servicio del proveedor de pagos.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Respuesta esperada:

Estado HTTP: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Eliminar cliente

Elimina un objeto de cliente del servicio del proveedor de pagos.

Solicitud enviada por Monetization:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Respuesta esperada:

Estado HTTP: 204 No Content

Sin cuerpo de respuesta

Operaciones de tarjeta

Las operaciones de tarjeta se refieren a la configuración o eliminación de tarjetas de crédito y débito.

Configuración (solicitud de configuración de tarjeta)

Activa un proceso donde un cliente puede proporcionar los detalles de su tarjeta de crédito, los cuales son tokenizados y almacenados en Monetization. Tras una solicitud para agregar una nueva tarjeta de crédito, Monetization enviará una solicitud de configuración a su componente de integración.

Su componente de integración debe manejar cualquier lógica relacionada con los servicios del proveedor de pagos y devolver una URL de redirección a Monetization como respuesta. El cliente será redirigido a la URL proporcionada, donde el formulario alojado de su proveedor de pagos recopilará y tokenizará los detalles de la tarjeta del cliente.

Configuración de tarjeta de crédito Figura 5: Configuración de tarjeta de crédito

Solicitud enviada por Monetization:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Respuesta esperada:

Estado HTTP: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Eliminar tarjeta

Envía una solicitud a su componente de integración para manejar la lógica de eliminación de la referencia de la tarjeta de crédito a través de los servicios del proveedor de pagos, luego elimina la referencia de Monetization tras el éxito.

Solicitud enviada por Monetization:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Respuesta esperada:

Estado HTTP: 204 No Content

Sin cuerpo de respuesta

Operaciones de transacción

Las operaciones de transacción se refieren a acciones transaccionales ejecutadas sobre tokens de métodos de pago almacenados (tarjeta de crédito/débito). Estas acciones incluyen:

Autorización

La autorización (authorization) se utiliza para autorizar (bloquear) fondos en el método de pago de un cliente. Las autorizaciones se pueden capturar o anular más tarde. La siguiente solicitud se envía a su componente de integración, que debe manejar la lógica del servicio del proveedor de pagos y devolver una respuesta.

Solicitud enviada por Monetization:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Respuesta esperada:

Estado HTTP: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Mensaje del proveedor si se proporciona",
    "code": "Código del proveedor si se proporciona"
}

Captura

La captura (capture) se refiere al cobro de fondos autorizados de una solicitud de autorización previa. El monto a cobrar puede ser igual o inferior al monto autorizado.

Cualquier fondo autorizado no cobrado será liberado de nuevo al cliente por el servicio del proveedor de pagos. La siguiente solicitud se envía a su componente de integración, que debe manejar la lógica del servicio del proveedor de pagos y devolver una respuesta.

Solicitud enviada por Monetization:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Respuesta esperada:

Estado HTTP: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Mensaje del proveedor si se proporciona",
    "code": "Código del proveedor si se proporciona"
}

Cargo

El cargo (charge) autoriza y captura fondos como una única transacción inmediata. La siguiente solicitud se envía a su componente de integración, que debe manejar la lógica del servicio del proveedor de pagos y devolver una respuesta.

Solicitud enviada por Monetization:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Respuesta esperada:

Estado HTTP: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Mensaje del proveedor si se proporciona",
    "code": "Código del proveedor si se proporciona"
}

Anulación

La operación de anulación (void) anula una transacción de autorización, liberando los fondos autorizados. La siguiente solicitud se envía a su componente de integración, que debe manejar la lógica del servicio del proveedor de pagos y devolver una respuesta.

Solicitud enviada por Monetization:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Respuesta esperada:

Estado HTTP: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Mensaje del proveedor si se proporciona",
    "code": "Código del proveedor si se proporciona"
}

Reembolso

El reembolso (refund) devuelve fondos al cliente y hace referencia a una transacción de cargo o captura previa. La siguiente solicitud se envía a su componente de integración, que debe manejar la lógica del servicio del proveedor de pagos y devolver una respuesta.

Solicitud enviada por Monetization:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Respuesta esperada:

Estado HTTP: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Mensaje del proveedor si se proporciona",
    "code": "Código del proveedor si se proporciona"
}

Manejo de errores

En caso de que una operación no sea exitosa en su componente de integración, devuelva cualquier estado fuera del rango 200-300 y el mensaje de error en el cuerpo de la respuesta.

Anterior
Dispositivos