Creation Subscription Mandate
Qué hace
Crea un mandato/deuda de tipo SUBSCRIPTION, con cobro recurrente mensual o personalizado.
Cuándo usarlo
Se utiliza para cobros recurrentes cuyas cuotas futuras deben generarse automáticamente según la periodicidad y las condiciones de la suscripción, sin tener que cargarlas una a una.
Endpoint
POST /mandate
Autenticación
Envía x-api-key y Authorization: Bearer <token> con las credenciales del ambiente de la solicitud. Obtén el token mediante el proceso de autenticación.
Headers requeridos
country,commerceychannel: contexto comercial autorizado para la solicitud.requestDateTime: fecha y hora de la solicitud.correlationId: identificador de la solicitud. Se recomienda usar un UUID para facilitar su seguimiento.processIdysalesExecutiveId: valores obligatorios en esta operación.
Consulta los parámetros de la operación para conocer las restricciones de cada header y utiliza los valores asignados a tu integración.
Campos principales
| Campo | Descripción |
|---|---|
customer.userId o customer.internalUserId | Identifica al cliente. Usa solo una variante segun el ejemplo. |
mandate.id | ID externo unico del comercio para el mandato/deuda. |
mandate.type | Tipo del producto: DYNAMIC, PERMANENT, SUBSCRIPTION u ONEPAY. |
mandate.name / mandate.detail | Texto visible o descriptivo del compromiso. |
mandate.charges | Configuracion de vigencia, monto, moneda y periodicidad segun el tipo. |
paymentMethods | Metodos habilitados para este mandato; si se omite, se usan los disponibles para el comercio. |
installments | Cuotas iniciales cuando el producto lo permite. |
metadata | Datos propios del comercio para conciliacion. |
urls.callback, urls.activationWebhook, urls.paymentWebhook | URLs de retorno/notificacion si tu flujo las usa. |
mandate.charges.paymentPeriod | Configura periodicidad mensual o personalizada. |
Variantes soportadas
- Recurrencia mensual con IDs externos.
- Recurrencia mensual con IDs internos.
- Recurrencia personalizada con IDs externos.
- Recurrencia personalizada con IDs internos.
Reglas de negocio
- Si envías
validateCreation: trueymandate.serviceId, desarrollo comprueba si eseserviceIdya existe. La prevalidación de producción no realiza esa comprobación. - El usuario debe estar asociado al comercio en este ambiente. Regístralo o asócialo antes mediante Create User.
- En suscripciones mensuales,
mandate.charges.cumulativeymandate.charges.paymentPeriod.proportionalPaymentson obligatorios. Ambos admitenfalse. - Usa
mandate.type=SUBSCRIPTION. - Para periodicidad personalizada, informa la frecuencia requerida por el schema.
- Mantén montos, moneda y fechas consistentes con el periodo de cobro.
Respuesta exitosa
Si creas el compromiso sin firma, la respuesta incluye statusCode, message y payload. Según el resultado del flujo, los datos se entregan en payload.customer, payload.mandate, payload.installments y payload.activation.
Guarda los identificadores del cliente, del mandato y de las cuotas que recibas para utilizarlos en consultas posteriores. Si la respuesta incluye un enlace de activación, lo encontrarás en payload.activation.url.
Ejemplo recomendado
El ejemplo configura el monto mensual en paymentPeriod y envía la primera cuota. La primera cuota y el monto periódico coinciden en 15000 PESOS; payDay es 5, proportionalPayment es false y cumulative es false.
Los datos son ficticios. Sustituye customer.internalUserId por el valor real devuelto por POST /user, usa un mandate.id nuevo y reemplaza las URLs por las de tu integración. El medio seleccionado debe estar habilitado para el comercio. Estos cuerpos se envían a POST /mandate con los headers de la operación. Los ejemplos no incluyen firma documental.
La URL de la respuesta es ilustrativa. En la integración, utiliza exactamente payload.activation.url devuelto por Forpay; no construyas el enlace a partir de su ejemplo.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||