Update Mandate

Qué hace

Actualiza los campos admitidos de una suscripción existente. La API toma los identificadores del mandato desde el body.

Cuándo usarlo

Usa esta operación para cambiar el nombre, detalle, fecha de término, monto y moneda, día de cobro o las URLs de webhook de una suscripción.

Endpoint

PUT /mandate/update/id/{mandateExternalId}/internalId/{mandateId}

Autenticación

Requiere x-api-key y Authorization: Bearer <JWT>, salvo endpoints publicos de autenticacion o contratos de webhook receptor del cliente.

Campos principales

Body / Parámetros

Envía los identificadores del cliente y del mandato y los campos que deseas modificar. Incluye siempre mandate.charges, aunque sea un objeto vacío.

Para cambios de nombre, detalle o URLs de webhook, puedes enviar charges: {} y omitir paymentPeriod. Para los cambios de cobro mensual que incluyen paymentPeriod, envía payPeriodIdentifier=MENSUAL como contexto de validación. Ese dato conserva la recurrencia de la suscripción y no permite cambiarla.

El monto mandate.charges.paymentPeriod.amount y la moneda currencyId se envían juntos. El monto debe ser mayor que cero. Las opciones documentadas de paymentPeriod y el ejemplo de cobro corresponden al contrato mensual.

Ejemplo de cambio de nombre

{
  "customer": {
    "userId": "CLIENTE-001"
  },
  "mandate": {
    "id": "SUBSCRIPTION-10000",
    "internalId": 10000,
    "type": "SUBSCRIPTION",
    "name": "Suscripción actualizada",
    "charges": {}
  }
}

Reglas de negocio

• La suscripción debe pertenecer al comercio autenticado.
• La identificación efectiva utiliza mandate.id y mandate.internalId del body.
• Cambiar payDay configura las cuotas que se creen después. Una cuota ya creada mantiene su vencimiento, aunque esté pendiente y venza en una fecha futura.
• Al cambiar el monto, el procesamiento selecciona cuotas en estado PENDIENTE. Esta selección puede incluir cuotas vencidas. Comprueba ese alcance antes de solicitar el cambio.
• Para una cuota pendiente que vence el día 30, cambiar el monto el día 20, el mismo día 30 o el día 31 puede modificar su importe mientras siga PENDIENTE.
• Las URLs activationWebhook y paymentWebhook se aplican según los eventos habilitados para el comercio.
• Utiliza un correlationId para identificar la solicitud.

Respuesta exitosa

HTTP 200 con message=SUBSCRIPTION_UPDATE_OK. El payload exterior contiene la respuesta del procesamiento, incluidos statusCode, message, name y otro payload. Los datos de negocio se encuentran en payload.payload.businessPartner, customer, mandate e installments, conforme a su presencia en el resultado.