Generar Link de Pago

Descripción

Genera un link de pago único o de suscripción (débito automático).

URL

POST /api/saleitems/add

Autenticación

Header Api-Token con token UUID proporcionado por MetrePay.

Petición

Headers

Header	Valor
`Api-Token`	Token UUID del comercio
`Content-Type`	`application/json`

Cuerpo

Campo	Condición	Descripción
`label`	Requerido	Concepto del pago (producto/servicio). Para pagos recurrentes se recomienda usar conceptos genéricos (ej: "Cuota Social") en lugar de específicos (ej: "Cuota Social del mes de Enero").
`amount`	Requerido	Monto a pagar. En pagos recurrentes, corresponde al monto del primer pago (puede diferir de las cuotas posteriores para casos de matrículas o costos de suscripción).
`handleValue`	Requerido	Email o número de teléfono del cliente.
`handleLabel`	Requerido	Nombre del cliente.
`customIdentifier`	Opcional	Identificador personalizado del comercio para identificar al cliente (ej: número de cédula, número de socio, código de operación).
`customIdentifier2`	Opcional	Segundo identificador personalizado del comercio (ej: número de contrato, número de abono).
`singlePayment`	Requerido	`true`/`false`. Indica si el pago único está habilitado. Un pago único implica que el cliente realiza un solo pago sin generar recurrencia, por el monto indicado en `amount`.
`creditAndDebitCard`	Requerido	`true`/`false`. Indica si el pago con tarjetas de crédito o débito está habilitado. Debe ser `true` para pagos recurrentes, ya que las suscripciones funcionan exclusivamente con tarjetas.
`recurrentPayment`	Requerido	`true`/`false`. Indica si el pago recurrente está habilitado.
`recurrentPaymentType`	Opcional	`"STATIC"` (valor por defecto) o `"DYNAMIC"`. Se utiliza `"DYNAMIC"` para suscripciones de montos variables (por número de factura). Disponible exclusivamente para comercios con contrato SaaS.
`installmentAmount`	Requerido (recurrente STATIC)	Monto de la cuota desde la 2da cuota. Aplica solo cuando `recurrentPayment` es `true` y `recurrentPaymentType` es `"STATIC"`.
`totalPeriods`	Requerido (recurrente STATIC)	Cantidad total de cuotas del pago recurrente, incluyendo la primera. Aplica solo cuando `recurrentPayment` es `true` y `recurrentPaymentType` es `"STATIC"`.
`dayOfMonth`	Requerido (recurrente STATIC)	Día del mes para aplicar los débitos desde la 2da cuota. Valores entre 1 y 28. Aplica solo cuando `recurrentPayment` es `true` y `recurrentPaymentType` es `"STATIC"`.
`monthForSecondInstallment`	Requerido (recurrente STATIC)	Mes en que se establece la fecha de la segunda cuota. `0` = mismo mes de creación, `1` = mes siguiente, `2` = mes subsiguiente, etc. Aplica solo cuando `recurrentPayment` es `true` y `recurrentPaymentType` es `"STATIC"`.
`payWaitHours`	Opcional	Cantidad de horas de vigencia del link de pago. `0` = vigencia ilimitada.
`redirectUrl`	Opcional	URL a la que será redirigido el usuario luego de realizar el pago. Requiere configuración previa de URL de callback por parte de MetrePay.
`noLoginRequired`	Opcional	`true`/`false`. Si se envía `true`, solo se acepta si la empresa tiene habilitada esta opción. Si no se envía, equivale a `false`.
`documentNumber`	Opcional	Número de documento en formato string. Requerido cuando `noLoginRequired` es `true`.
`paymentMethods`	Opcional	Array de strings que indica las procesadoras habilitadas para el link. Si no se envía, se habilitan todas las procesadoras disponibles. Valores posibles: `"PARAGUAY.BANCARD"`, `"PARAGUAY.BEPSA"`.

Ejemplo: Pago Único

{
  "label": "Cuota social del mes de Enero",
  "amount": 200000,
  "handleValue": "juanperez@metrepay.com",
  "handleLabel": "Juan Pérez",
  "customIdentifier2": "4000124",
  "singlePayment": true,
  "creditAndDebitCard": true
}

Ejemplo: Suscripción (Débito Automático)

{
  "label": "Cuota social",
  "amount": 200000,
  "handleValue": "juanperez@metrepay.com",
  "handleLabel": "Juan Pérez",
  "customIdentifier": "11",
  "customIdentifier2": "22",
  "singlePayment": false,
  "creditAndDebitCard": true,
  "recurrentPayment": true,
  "installmentAmount": 180000,
  "totalPeriods": 24,
  "dayOfMonth": 28,
  "monthForSecondInstallment": 1,
  "payWaitHours": 96
}

Ejemplo: Montos Variables (DYNAMIC)

{
  "label": "Cuota social - Montos dinámicos",
  "amount": 100,
  "handleValue": "juanperez@metrepay.com",
  "handleLabel": "Juan Pérez - Montos dinámicos",
  "customIdentifier": "4000123-1",
  "customIdentifier2": "4000123-2",
  "singlePayment": false,
  "creditAndDebitCard": true,
  "recurrentPayment": true,
  "payWaitHours": 96,
  "recurrentPaymentType": "DYNAMIC"
}

Ejemplo: Link con Procesadora Específica

{
  "label": "Prueba 002",
  "amount": 20000,
  "handleValue": "juanperez@metrepay.com",
  "handleLabel": "Juan Pérez",
  "customIdentifier": "4000124",
  "singlePayment": true,
  "creditAndDebitCard": true,
  "noLoginRequired": true,
  "paymentMethods": ["PARAGUAY.BANCARD"]
}

Respuesta

Respuesta Exitosa

Campo	Descripción
`id`	Número del ticket MP.
`currency`	Tipo de moneda.
`ammount`	Monto del pago.
`statusId`	Código del estado del pago (ver Definiciones Base).
`slug`	Prefijo del link de pago (embebido en la URL).
`publicPayUrl`	Link de pago a compartir con el cliente.

{
  "id": 7,
  "currency": "PYG",
  "ammount": "4000000.00",
  "statusId": 90,
  "slug": "p5e56fc8b9d793",
  "publicPayUrl": "https://test.metrepay.com/pay/prueba/item/p5e56fc8b9d793"
}

Respuestas de Error

Código HTTP	Descripción
400	Petición inválida (campos requeridos faltantes o formato incorrecto).
401	Token de autenticación inválido o ausente.
422	Error de validación (ej: `noLoginRequired` no habilitado para el comercio, valores inválidos en `paymentMethods`).

Notas

Para el campo monthForSecondInstallment: si se establece 28 como día de débito y la suscripción se crea el 2 de enero, el valor 0 implica que la 2da cuota se cobra el 28 de enero; el valor 1, el 28 de febrero; el valor 2, el 28 de marzo. Las cuotas siguientes se agendan consecutivamente.
El campo paymentMethods está disponible exclusivamente vía API. Los links generados desde la interfaz web se crean con todas las procesadoras habilitadas.
Si paymentMethods incluye valores no válidos, se omiten y el link se genera normalmente. Solo se retorna error en caso de error de formato del array.
El panel de "Mis Tarjetas Catastradas" se muestra siempre completo, independientemente del valor de paymentMethods.
El valor "DYNAMIC" en recurrentPaymentType está disponible exclusivamente para comercios con contrato SaaS. Para otros tipos de contrato, la petición será rechazada con error de validación.