API Reference

Creation OnePay Mandate

post
https://devapi.forpayservices.cl/white/label/mandate?3

Creation OnePay Mandate

Qué hace

Crea un mandato/deuda de tipo ONEPAY, pensado para un pago unico.

Cuándo usarlo

Usalo cuando el comercio necesita iniciar un cobro unico con autorizacion y seguimiento por mandato.

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

CampoUso para prueba
customer.userId o customer.internalUserIdIdentifica al cliente. Usa solo una variante segun el ejemplo.
mandate.idID externo unico del comercio para el mandato/deuda.
mandate.typeTipo del producto: DYNAMIC, PERMANENT, SUBSCRIPTION u ONEPAY.
mandate.name / mandate.detailTexto visible o descriptivo del compromiso.
mandate.chargesConfiguracion de vigencia, monto, moneda y periodicidad segun el tipo.
paymentMethodsMetodos habilitados para este mandato; si se omite, se usan los disponibles para el comercio.
installmentsCuotas iniciales cuando el producto lo permite.
metadataDatos propios del comercio para conciliacion.
urls.callback, urls.activationWebhook, urls.paymentWebhookURLs de retorno/notificacion si tu flujo las usa.
mandate.terminateWhenChargedPara OnePay normalmente indica cierre al completar el cobro.

Variantes soportadas

  • Cliente por customer.userId externo.
  • Cliente por customer.internalUserId interno Forpay.

Reglas de negocio

  • Usa mandate.type=ONEPAY.
  • El monto total debe ser consistente con los cargos/cuotas informados.
  • Este producto se finaliza cuando el cobro queda completado segun la configuracion.

Respuesta exitosa

Retorna el mandato OnePay creado y datos para confirmacion/busqueda posterior.

Ejemplo recomendado

Usa el ejemplo JSON precargado y reemplaza cliente, mandate.id, montos, moneda y URLs.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

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

Body de creación ONEPAY (pago único). Debe incluir customer, mandate, installmentsNumber e installments. Enviar customer.userId o customer.internalUserId, pero no ambos.

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

Estructura de mandato a crear

boolean

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

paymentMethods
array of strings

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

paymentMethods
Allowed:
number
required
≥ 1

Cantidad de cargos que tendrá el pago único. Se deben enviar installments en una cantidad exactamente igual al número ingresado

installments
array of objects
required

Detalle / desglose del pago único. Para ONEPAY, cada item representa un cargo del pago y debe enviarse con payNow=true.

installments*
metadata
object

Metadata general del pago único. Por ejemplo, f_paymentRefund=true indica que no se permite pago parcial y que se reversa en caso necesario.

signature
object

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

urls
object
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
string
enum
required

Identificador de país donde proviene la solicitud

Allowed:
string
required

Identificador único del comercio asociado definido por forpay

string
required

Tipo de plataforma usada por el comercio para integrarse con Forpay

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.

string
required

Identificador único para la trazabilidad de la solicitud

string
enum
required

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

Allowed:
string
required

Identificador del ejecutivo que realiza la venta

string
required

Clave x-api-key

Responses

Callbacks

Updated 18 days ago

Did this page help you?
Language
Credentials
LoadingLoading…
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 18 days ago

Did this page help you?