Creation Permanent Mandate
Qué hace
Crea un mandato de tipo PERMANENT para un compromiso con monto total y cuotas definidos al momento de su creación.
Cuándo usarlo
Se utiliza cuando el monto total y las cuotas están definidos desde el inicio, como en un plan de pago previamente acordado. El mandato se crea junto con esas cuotas y sus respectivos vencimientos.
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. |
Variantes soportadas
- Cliente por
customer.userIdexterno. - Cliente por
customer.internalUserIdinterno Forpay.
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.
- Dentro de
mandate.charges, envíastartDate,endDate,cumulative,wayToPayytotalAmounts. El bloquepaymentPeriodes opcional; si lo incluyes, debe cumplir el esquema de la operación. - Usa
mandate.type=PERMANENT. mandate.chargesdebe incluir configuracion coherente de periodo, monto y vigencia.terminateWhenChargednormalmente debe serfalsepara este producto.
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 monto de mandate.charges.totalAmounts coincide con la suma de las dos cuotas. installmentsNumber coincide con la cantidad enviada y cada cuota tiene un ID externo distinto.
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… | |||