Developer Docs

Español

English

Español

English

Apariencia

ZertiPay: Funcionalidades ​

Pagos Open Banking PSD2, crea un flujo, obtén una URL por operación y entrégala al pagador.

ZertiPay es el producto de Zertiban para cobros mediante Open Banking PSD2. Permite crear flujos de pago con una o varias operaciones y obtener una URL por operación para su entrega al pagador.

Zertiban se encarga de toda la experiencia de pago, desde la selección de banco hasta la autorización SCA, mientras que tu sistema recibe notificaciones en tiempo real mediante webhooks cuando la operación se completa.

Para los conceptos comunes de flujos y operaciones, estructura, estados y transiciones, consulta Flujos y operaciones.

Funcionalidades de ZertiPay ​

FuncionalidadDescripción
Pago Open Banking PSD2Transferencia SEPA iniciada desde el banco del pagador, sin tarjeta ni pasarela tradicional
Múltiples operaciones por flujoUn único POST/flow/v1/flows puede crear varias operaciones con URLs independientes
Múltiples destinatariosCada operación puede asociarse a un destinatario con nombre, email y teléfono
Página de pago alojadaZertiban proporciona la UI de pago completamente gestionada y personalizable
SCA bancariaEl pagador autoriza directamente en su banca online habitual
Webhooks en tiempo realEventos OPERATION_OPENED, OPERATION_COMPLETED, OPERATION_REJECTED, OPERATION_EXPIRED
Reconciliación por externalIdIdentificadores de negocio viajan en todo el flujo y aparecen en todos los webhooks

ZertiPay: flujo de cobro completo ​

1. Backend: Obtención del token (OAuth2) ​

Antes de cualquier operación, el backend obtiene un access_token mediante OAuth2 Client Credentials.

POST /idp/oauth2/token
  • El token tiene una vida corta (~300s)
  • Debe cachearse y renovarse antes de su expiración
  • Se usa en todas las llamadas a API

2. Backend: Creación del flujo de cobro ​

El backend crea un flujo enviando un multipart/form-data con un payload JSON.

POST /flow/v1/flows

Zertiban devuelve de forma síncrona:

  • flowUuid
  • operations[].url

Guarda siempre el uuid de cada operación

El sistema debe almacenar operations[].uuid, ya que es el identificador interno utilizado para:

  • consultas de estado,
  • cancelaciones,
  • historial de eventos,
  • reconciliación técnica con el sistema de webhooks.

3. Backend / Frontend: Entrega de la URL al pagador ​

La URL de operations[].url redirige al pagador a la página de pago alojada por Zertiban. El sistema del cliente es responsable de su entrega mediante:

  • Email
  • Notificación push
  • UI propia

Al abrir la URL, la operación transiciona a OPENED.

CREATED → OPENED

4. Banco: Autorización (SCA) ​

El pagador:

  • selecciona su banco en la página de Zertiban,
  • es redirigido a su banca online,
  • autoriza el pago mediante SCA.

No requiere apps adicionales ni hardware.

5. Zertiban: Webhook de confirmación ​

Cuando el banco confirma la operación, Zertiban actualiza el estado a COMPLETED y envía un webhook a tu endpoint.

OPENED → COMPLETED

POST https://tuapp.com/webhooks/zertiban
json
{
  "eventType": "OPERATION_COMPLETED",
  "resource": {
    "externalId": "OP-2026-001",
    "status": "COMPLETED"
  }
}

6. Backend: Reconciliación ​

El backend utiliza resource.externalId para:

  • localizar la operación,
  • actualizar el estado del cobro,
  • conciliar con el sistema interno (ERP, facturación, etc.).

Comportamiento del sistema ​

  • La creación del flujo es síncrona
  • Las URLs de pago se devuelven en la respuesta del API
  • El operations[].uuid debe almacenarse siempre para trazabilidad completa
  • No existen callbacks en la creación del flujo
  • Los webhooks se utilizan para los cambios de estado

Responsabilidad del cliente ​

Zertiban no envía comunicaciones al pagador. El cliente es responsable de:

  • distribuir la URL de pago,
  • gestionar la experiencia de notificación,
  • persistir identificadores (externalId y operationUuid) para conciliación,
  • integrar el estado en su sistema.

Siguientes pasos ​