Contenido
- Proceso general de integración
- Registro y configuración del módulo de pago
- Estados de los invoices
- Flujos habituales de trabajo con sistemas de pago
- Creación del pago
- Confirmación del pago
- Cancelación del pago
- Reembolso
- Actualización de los datos del invoice
- Verificación de los datos del invoice
Proceso general de integración
El trabajo con la interfaz de programación de aplicaciones (API) se realiza de acuerdo con las reglas de trabajo con la API. Para la integración se utilizan los métodos de la sección Pagos de la API.
El proceso de integración incluye las siguientes etapas:
USER: solicitar al usuario una clave de API para acceder al sistema.API: registrar un nuevo módulo de pago de integración.USER: realizar los ajustes necesarios en la página de configuración de la integración del módulo de pago.USER: crear tipos de pago vinculados a las tiendas del módulo de pago creado.SYSTEM: durante el trabajo del usuario, el sistema inicia las solicitudes relacionadas con los pagos.API: enviar al sistema de gestión de relaciones con clientes (CRM) información actualizada sobre los pagos.
Las etapas marcadas como USER las realiza el usuario. Las etapas marcadas como API se ejecutan mediante solicitudes de la API desde el módulo de pago al CRM. La etapa marcada como SYSTEM corresponde a las solicitudes que el CRM envía al módulo de pago teniendo en cuenta la configuración indicada durante el registro.
Si una solicitud de la API dirigida al módulo de pago produce un error, el módulo debe devolver una respuesta con el siguiente formato:
{
"success": false,
"errorMsg": "Texto del error"
}El texto transmitido en errorMsg se muestra al usuario. Si el módulo de pago devuelve una respuesta no válida, la información se registra en el Registro de acciones con el tipo de entrada «Pagos de integración».
Registro y configuración del módulo de pago
Para registrar y configurar el módulo de pago se utiliza el método POST /api/v5/integration-modules/{code}/edit. Si ya existe un módulo con el código code, el método actualiza su configuración; de lo contrario, crea un nuevo módulo de integración. Los parámetros actuales del módulo se pueden obtener mediante el método GET /api/v5/integration-modules/{code}.
Parámetros:
apiKey: clave de API del sistema.integrationModule: objeto en formato JSON (JavaScript Object Notation) que contiene la descripción del módulo de integración.integrationModule[integrations][payment]: configuración de la integración con el sistema de pago.
En integrationModule[integrations][payment][actions] se indican las rutas de los métodos callback del módulo de pago a los que accederá el CRM al ejecutar acciones con los pagos de integración:
create: creación del pago. Este método es obligatorio.approve: confirmación del pago.cancel: cancelación del pago.refund: reembolso.
En integrationModule[integrations][payment][currencies] se transmite la lista de códigos de las monedas compatibles de acuerdo con el estándar ISO 4217.
En integrationModule[integrations][payment][invoiceTypes] se transmite, como un array, la lista de tipos de invoice compatibles. Está disponible el siguiente tipo:
link: al crear un invoice de este tipo, debe generarse un enlace mediante el cual el cliente pueda realizar el pago.
En integrationModule[integrations][payment][shops] se transmite la lista de tiendas del cliente en el sistema de pago. Cada tienda debe contener el nombre name, el código único code y el estado de actividad active.
En la interfaz del CRM se puede vincular un tipo de pago de integración con una tienda concreta del sistema de pago. Por cada tienda nueva transmitida se crea automáticamente un tipo de pago nuevo. Si una tienda está inactiva, el sistema avisa al usuario cuando añade el método de pago a un pedido.
Importante
Si al actualizar el módulo de integración se omite una tienda de la lista
integrationModule[integrations][payment][shops], la tienda se elimina del CRM. Después no será posible seguir trabajando con los pagos y tipos de pago vinculados a ella.
Ejemplo de solicitud:
{
"code": "awesome-payment-module",
"clientId": "ea5d01ee-440b-4dbc-ba85-96307e96bdbf",
"baseUrl": "https://payment-module.com",
"accountUrl": "https://payment-module.com/profile/12",
"active": true,
"name": "Awesome Payment Module",
"actions": {
"activity": "activity"
},
"integrations": {
"payment": {
"actions": {
"create": "payment/create",
"approve": "payment/approve",
"cancel": "payment/cancel",
"refund": "payment/refund"
},
"currencies": ["RUB", "EUR"],
"invoiceTypes": ["link"],
"shops": [
{"code": "shop-1", "name": "Shop one", "active": true},
{"code": "shop-2", "name": "Shop two", "active": false}
]
}
}
}Estados de los invoices
El CRM dispone de los siguientes estados de invoice. Estos estados determinan la lógica de trabajo con los pagos y las acciones disponibles en la interfaz:
pending: estado inicial de espera del pago por parte del usuario. Permite cancelar el invoice y enviar un correo electrónico con el enlace de pago.waitingForCapture: estado de espera de la confirmación del pago. Debe establecerse cuando los fondos están retenidos, pero todavía no se han debitado. Permite confirmar o cancelar el débito en el CRM.succeeded: estado de pago completado correctamente. Debe establecerse después de debitar los fondos de la cuenta del cliente. Permite realizar un reembolso.canceled: estado de pago cancelado. Debe establecerse cuando se cancela el pago.refundSucceeded: estado de reembolso completado correctamente. Debe establecerse después de devolver los fondos al cliente.
Al cambiar el estado del invoice, si el nuevo estado tiene una correspondencia configurada en el sistema, el estado del pago también cambia al valor correspondiente.
Flujos habituales de trabajo con sistemas de pago
Retención con confirmación automática
El sistema de pago retiene los fondos del cliente y envía una notificación al módulo de pago. El módulo realiza la verificación de los datos del invoice y, según el resultado, confirma el débito o cancela el pago. Una vez finalizada la operación, el módulo actualiza los datos del invoice en el CRM.
CRM -> Módulo de pago: Crear invoice
Módulo de pago -> Sistema de pago: Crear pago
Sistema de pago -> Módulo de pago: Devolver los datos del pago
Módulo de pago -> CRM: Devolver los datos del pago
CRM -> Cliente: Enviar el enlace de pago
Cliente -> Sistema de pago: Introducir los datos para pagar
Sistema de pago -> Sistema de pago: Retener los fondos
Sistema de pago -> Módulo de pago: Notificar la retención
Módulo de pago -> CRM: Verificar los datos del invoice
CRM -> Módulo de pago: Devolver el resultado de la verificación
Módulo de pago -> Sistema de pago: Confirmar el débito o cancelar el pago
Sistema de pago -> Módulo de pago: Notificar el resultado
Módulo de pago -> CRM: Actualizar el invoice a succeeded si se completó el pagoRetención con confirmación manual
El sistema de pago retiene los fondos del cliente y envía una notificación al módulo de pago. El módulo verifica los datos del invoice y, según el resultado, cancela el pago o cambia el estado del invoice a waitingForCapture.
Cuando el mánager confirma o rechaza el pago, el CRM notifica al módulo mediante el callback correspondiente. El módulo debe debitar los fondos o cancelar el pago y liberar los fondos retenidos. Una vez finalizada la operación, el módulo actualiza los datos del invoice en el CRM.
CRM -> Módulo de pago: Crear invoice
Módulo de pago -> Sistema de pago: Crear pago
Sistema de pago -> Módulo de pago: Devolver los datos del pago
Módulo de pago -> CRM: Devolver los datos del pago
CRM -> Cliente: Enviar el enlace de pago
Cliente -> Sistema de pago: Introducir los datos para pagar
Sistema de pago -> Sistema de pago: Retener los fondos
Sistema de pago -> Módulo de pago: Notificar la retención
Módulo de pago -> CRM: Verificar los datos del invoice
CRM -> Módulo de pago: Devolver el resultado de la verificación
Módulo de pago -> CRM: Establecer waitingForCapture si la verificación es correcta
Mánager -> CRM: Confirmar o cancelar el débito
CRM -> Módulo de pago: Enviar el callback correspondiente
Módulo de pago -> Sistema de pago: Debitar o liberar los fondos
Sistema de pago -> Módulo de pago: Notificar el resultado
Módulo de pago -> CRM: Actualizar el estado del invoicePago sin retención
Este flujo es adecuado para sistemas de pago que permiten confirmar la disponibilidad para aceptar un pago antes de debitar los fondos. El sistema de pago solicita la confirmación al módulo, el módulo verifica los datos del invoice y devuelve el resultado. Si la verificación es correcta, el sistema de pago debita los fondos y notifica al módulo. Después, el módulo actualiza los datos del invoice en el CRM.
CRM -> Módulo de pago: Crear invoice
Módulo de pago -> Sistema de pago: Crear pago
Sistema de pago -> Módulo de pago: Devolver los datos del pago
Módulo de pago -> CRM: Devolver los datos del pago
CRM -> Cliente: Enviar el enlace de pago
Cliente -> Sistema de pago: Introducir los datos para pagar
Sistema de pago -> Módulo de pago: Solicitar confirmación para aceptar el pago
Módulo de pago -> CRM: Verificar los datos del invoice
CRM -> Módulo de pago: Devolver el resultado de la verificación
Módulo de pago -> Sistema de pago: Confirmar o rechazar el pago
Sistema de pago -> Sistema de pago: Debitar los fondos si se confirmó el pago
Sistema de pago -> Módulo de pago: Notificar el resultado
Módulo de pago -> CRM: Actualizar el invoice a succeeded si se completó el pagoCreación del pago
Al emitir un invoice para un pago de integración, el sistema inicia una solicitud POST al método indicado en integrationModule[integrations][payment][actions]["create"].
El módulo de pago debe crear un invoice de acuerdo con los parámetros recibidos y devolver el enlace de pago.
Confirmación del pago
Al confirmar un pago, el sistema inicia una solicitud POST al método indicado en integrationModule[integrations][payment][actions]["approve"].
La confirmación se ejecuta cuando el mánager pulsa el botón «Confirmar» en la lista de invoices. Esta acción solo está disponible para los invoices con el estado waitingForCapture.
El módulo de pago debe debitar los fondos retenidos de la cuenta del cliente y cambiar después el estado del invoice a succeeded.
Cancelación del pago
Al cancelar un invoice, el sistema inicia una solicitud POST al método indicado en integrationModule[integrations][payment][actions]["cancel"].
La cancelación se ejecuta cuando el mánager pulsa el botón «Cancelar» en la lista de invoices. Solo se pueden cancelar los invoices con los estados pending o waitingForCapture.
- Si el invoice tiene el estado
pending, el módulo de pago debe dejar de aceptar pagos para ese invoice. - Si el invoice tiene el estado
waitingForCapture, los fondos retenidos deben devolverse a la cuenta del cliente.
Después de la cancelación, el estado del invoice debe cambiar a canceled.
Reembolso
Al reembolsar fondos al cliente, el sistema inicia una solicitud POST al método indicado en integrationModule[integrations][payment][actions]["refund"].
El reembolso se ejecuta cuando el mánager pulsa el botón correspondiente en la lista de invoices. Esta acción solo está disponible para los invoices con el estado succeeded.
Después de completar el reembolso, el estado del invoice debe cambiar a refundSucceeded.
Actualización de los datos del invoice
Cuando cambian los parámetros del pago, el módulo de pago debe notificarlo al CRM mediante el método POST /api/v5/payment/update-invoice.
El CRM actualiza el invoice de acuerdo con los datos transmitidos. Si cambia el estado del invoice, el estado del pago también cambia según la correspondencia definida durante la configuración del módulo de pago.
Verificación de los datos del invoice
Después de emitir un invoice pueden cambiar la composición o el coste del pedido, por lo que el invoice emitido puede dejar de estar vigente. Antes de debitar los fondos, el módulo de pago debe verificar sus datos.
Para realizar la verificación se utiliza el método POST /api/v5/payment/check, al que se transmiten los parámetros de pago necesarios.
El sistema comprueba:
- la existencia del pedido;
- la existencia del pago;
- la correspondencia entre los parámetros transmitidos y los parámetros del invoice.
El resultado de la verificación se devuelve en la respuesta.