Creation Subscription Mandate

post

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

Creation Subscription Mandate

Qué hace

Crea un mandato/deuda de tipo SUBSCRIPTION, con cobro recurrente mensual o personalizado.

Cuándo usarlo

Usalo cuando el comercio vende una suscripcion o servicio que debe cobrarse segun una periodicidad acordada.

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.
`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

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

Retorna la suscripcion/mandato creado con IDs necesarios para busqueda, actualizacion y cancelacion.

Ejemplo recomendado

Parte del ejemplo JSON precargado y ajusta paymentPeriod, monto, moneda, cliente 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 suscripción - cobro periódico

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

length ≥ 1

Listado de cuotas de la suscripción. La primera cuota debe tener installmentDueDate futura y coherente con startDate de chargesy el período.

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