Creation Permanent Mandate

post

https://devapi.forpayservices.cl/white/label/mandate?1

Creation Permanent Mandate

Qué hace

Crea un mandato/deuda de tipo PERMANENT, orientado a compromisos con vigencia y regla de cobro permanente.

Cuándo usarlo

Usalo para compromisos recurrentes o permanentes donde el comercio necesita mantener una autorizacion activa bajo una regla definida.

Endpoint

POST /mandate

Autenticación

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

Headers requeridos

country, commerce, channel: contexto comercial autorizado.
requestDateTime: fecha/hora ISO 8601.
correlationId: UUID unico para trazabilidad.
processId y salesExecutiveId: contexto funcional/comercial cuando aplique.

Campos principales para probar en OpenAPI

Campo	Uso para prueba
`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.userId externo.
Cliente por customer.internalUserId interno Forpay.

Reglas de negocio

Usa mandate.type=PERMANENT.
mandate.charges debe incluir configuracion coherente de periodo, monto y vigencia.
terminateWhenCharged normalmente debe ser false para este producto.

Respuesta exitosa

Retorna IDs internos/externos del mandato y datos necesarios para seguimiento posterior.

Ejemplo recomendado

Usa el ejemplo JSON precargado y reemplaza cliente, mandate.id, fechas de vigencia, montos y URLs.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Body Params de creación de mandato según el tipo seleccionado.

Body de creación de mandato permanente

customer

object

required

Enviar solo uno de estos campos: internalUserId (Forpay) o userId (Comercio). Si envías ambos o ninguno, la solicitud será rechazada

mandate

object

required

purchaseDetail

boolean

Indicador que determina si se muestra la ventana de Detalle de Compra. (Opcional)

paymentMethods

array of strings

Métodos de pago disponibles al compromiso de pago. Si no se envía, se mostrarán todos los métodos disponibles del comercio. (Opcional)

paymentMethods

Allowed:

installmentsNumber

number

required

Cantidad de cuotas a crear. Se deben enviar installments en una cantidad exactamente igual al número ingresado

installments

array of objects

required

Listado de cuotas ingresadas a cobrar con el mandato

installments*

metadata

object

Identificadores clave de nuestros clientes

signature

object

Bloque opcional de firma. Si no se envía, no se crea flujo de firma asociado al mandato. (Opcional)

urls

object

validateCreation

boolean

Defaults to false

(Opcional) Si se envía en true, antes de crear el recurso Forpay ejecuta validaciónes previas de consistencia y unicidad. Si alguna validación falla, la API responde con 400 y un array errors[] que contiene todos los códigos detectados, y la creación se aborta sin tocar la base de datos. Si se omite o se envía false, el flujo se ejecuta directamente (comportamiento histórico).

Headers

country

string

enum

required

Identificador de país donde proviene la solicitud

Allowed:

commerce

string

required

Identificador único del comercio asociado definido por forpay

channel

string

required

Tipo de plataforma usada por el comercio para integrarse con Forpay

requestDateTime

date-time

required

Defaults to 2026-07-09T14:35:12.500Z

Fecha y hora de la solicitud en formato ISO 8601. En esta documentación se muestra un ejemplo precargado; al consumir la API debe enviarse la fecha/hora real de la solicitud.

correlationId

string

required

Identificador único para la trazabilidad de la solicitud

processId

string

enum

required

Identificador único del proceso interno de Forpay que realiza la solicitud

Allowed:

salesExecutiveId

string

required

Identificador del ejecutivo que realiza la venta

x-api-key

string

required

Clave x-api-key

Responses

Callbacks

200api-mandate-create-OK

400api-mandate-create-Error(400)

401Autenticación del cliente fallida

403Autenticación del cliente fallida

404api-mandate-create-Error(404)

500Error interno al realizar la validación