Cobro reutilizable por email

POST /moto/api/v1/reusable_mail_order

Este endpoint permite generar enlaces de pago reutilizables que pueden enviarse por email a uno o varios destinatarios. El enlace generado puede ser utilizado múltiples veces para realizar cobros, facilitando la gestión de pagos recurrentes o de uso frecuente.

Nota: Este endpoint está orientado a escenarios donde se requiere un mismo enlace de pago para varios cobros, como matrículas, cuotas periódicas, reservas, etc. Además, el importe es variable.

Petición

Payload (object)

• operation_type (string, requerido): Valor fijo sell.

• operation_properties (object, requerido):

  • backend (string, requerido): Valor fijo pwall.
  • expiration (integer, opcional): Tiempo de validez del enlace en segundos. Ejemplo: 86400 (1 día).
  • ko_redirect (boolean, opcional): Si se debe redirigir en caso de error.
  • url_callback (string, requerido): URL para recibir notificaciones de eventos asociados al enlace.
  • url_ko (string, opcional): URL a la que redirigir en caso de error.
  • url_result (string, opcional): URL a la que redirigir tras el pago exitoso.
  • payment_details_template (object, requerido):
    • title (string, requerido): Título de la página de pago.
    • description (string, opcional): Descripción visible para el usuario.
    • logo_url (string, opcional): URL del logo a mostrar en la página de pago.

• notification_templates (array, requerido): Plantillas de notificación para email y/o SMS.

  • type (string, requerido): Valor fijo data_request.
  • transport (string, requerido): Valor mail o sms.
  • data (object, requerido):
    • body (string, requerido si transport es mail): Cuerpo del email.
    • subject (string, requerido si transport es mail): Asunto del email.
    • text (string, requerido si transport es sms): Texto del SMS.

• message_recipients (array, requerido): Lista de destinatarios.

  • full_name (string, requerido): Nombre del destinatario.
  • email (string, requerido): Email del destinatario.
  • notify_on_creation (boolean, opcional): Si se debe enviar la notificación al crear el enlace.
  • phone_number (string, opcional): Teléfono del destinatario.
  • order (string, requerido): Identificador de la operación.
  • currency (string, requerido): Moneda (ISO 4217).
  • datetime (string, requerido): Fecha y hora de la operación.
  • client (string, requerido): Nombre del comercio.
  • preferred_transport (string, opcional): Canal preferido (mail o sms).
  • reconciliation (string, opcional): Identificador de conciliación para el destinatario.

Importante: El enlace generado será el mismo para todos los destinatarios y podrá ser reutilizado mientras esté vigente.

Respuesta

La respuesta incluye el enlace reutilizable generado y el identificador de la operación.

Payload de respuesta (object)

• order_uuid_map (object): Mapa con el identificador de la operación y el enlace generado.
• real_uuid_map (object): Mapa con el identificador de la operación y el UUID real.
• errors (object): Detalles de errores si los hubiera.

Ejemplo de petición

{
  "key": "{{key}}",
  "nonce": "{{nonce}}",
  "mode": "sha256",
  "resource": "{{resource}}",
  "payload": {
    "operation_type": "sell",
    "operation_properties": {
      "backend": "pwall",
      "expiration": 86400,
      "ko_redirect": true,
      "url_callback": "https://endqq52hn9wkxzt.m.pipedream.net",
      "url_ko": "https://endqq52hn9wkxzt.m.pipedream.net/ko",
      "url_result": "https://endqq52hn9wkxzt.m.pipedream.net/ok",
      "payment_details_template": {
        "title": "Building Center",
        "description": "",
        "logo_url": "https://png.pngtree.com/png-vector/20210829/ourmid/pngtree-logo-killer-png-image_3834843.jpg"
      }
    },
    "notification_templates": [
      {
        "type": "data_request",
        "transport": "mail",
        "data": {
          "body": "body",
          "subject": "Plantilla de pago"
        }
      },
      {
        "type": "data_request",
        "transport": "sms",
        "data": {
          "text": "test"
        }
      }
    ],
    "message_recipients": [
      {
        "full_name": "John Doe",
        "email": "email@example.com",
        "notify_on_creation": false,
        "phone_number": "",
        "order": "T1",
        "currency": "EUR",
        "datetime": "27/09/2021 09:12",
        "client": "Sipay",
        "preferred_transport": "mail",
        "reconciliation": "recon001"
        aqui poner metadata con ejemplo
      }
    ]
  }
}

Ejemplo de respuesta

{
  "type": "app.status",
  "code": "0",
  "detail": "Success",
  "payload": {
    "order_uuid_map": {
      "T1": "https://sandbox.sipay.es/s/mvcdwa"
    },
    "real_uuid_map": {
      "T1": "bc231d1a-3adf-11f0-b308-0242ac130ae9"
    },
    "errors": {}
  },
  "request_id": "68358a69d979984738979aad",
  "uuid": "68358a69d979984738979aad"
}

---

Consideraciones y buenas prácticas

• El enlace generado es reutilizable y puede ser compartido con diferentes usuarios.
• El campo expiration define la vigencia del enlace. Una vez expirado, no podrá ser utilizado para nuevos cobros.
• El endpoint soporta personalización de mensajes y plantillas para email.
• El identificador de operación (order) debe ser único por destinatario para facilitar la trazabilidad.
• El campo metadata permite añadir hasta 10 claves pareja valor para información adicional personalizada por destinatario.
• Ante cualquier error, se devolverá información detallada en el campo errors de la respuesta.

---