Search mandates, installments and payments

Consulta informacion de mandatos/deudas, cuotas, pagos y dispersiones del comercio autenticado. Esta operacion esta disenada para reportería, conciliacion y soporte, con paginacion obligatoria y filtros que evitan consultas masivas sin limites.

Parametros disponibles

Paginacion obligatoria

• page: numero de pagina, parte en 1.
• pageSize: cantidad de registros por pagina. Maximo recomendado y permitido: 500.

Cliente / pagador

• customerRut: RUT del cliente. Puede enviarse con puntos, guion o solo digitos; Forpay lo normaliza internamente.
• customerEmail: correo del cliente. Se compara en minusculas.
• userId: identificador externo del usuario enviado por la empresa.
• internalUserId: identificador interno Forpay del usuario.

Creador

• creatorRut: RUT del usuario creador del mandato/deuda.
• creatorEmail: correo del usuario creador.

Mandato / deuda

• mandateId: identificador interno Forpay del mandato.
• mandateType: tipo de mandato. Valores: dynamic: mandato dinamico, equivalente a deuda/cuotas creadas por la empresa. permanent: mandato permanente, equivalente a deuda permanente. subscription: mandato recurrente por calendario o recurrencia. onepay: mandato de pago unico OnePay.
• paymentMethodId: ID numerico del medio de pago principal del mandato.

Cuotas / cargos

• externalInstallmentId: identificador externo de la cuota informado por la empresa.
• installmentId: identificador interno Forpay de la cuota.
• installmentStatus: estado de la cuota. Valores: pending: pendiente. paid: pagada. annulled: anulada. inactive: inactiva. collectionInProgress: cobro en proceso. rescheduled: repactada. finalized: finalizada. reversed: reversada. inValidation: en validacion. deleted: eliminada; no se muestra por defecto salvo que se filtre explicitamente. paused: pausada.
• installmentPaymentMethodId: ID numérico del medio usado por la cuota, según la tabla de medios operativos.
• installmentAmountMin / installmentAmountMax: rango de monto de cuota.

Fechas

• dueDateFrom / dueDateTo: rango de vencimiento de cuota, formato YYYY-MM-DD.
• paymentDateFrom / paymentDateTo: rango de fecha de pago, formato YYYY-MM-DD.
• createdAtFrom / createdAtTo: rango de creacion del mandato/deuda, formato YYYY-MM-DD.

Pago, autorizacion y dispersion

• paymentAuthorizationId: identificador de autorizacion/transaccion de pago.
• dispersionId: identificador de dispersion/payout cuando la cuota ya tiene informacion de abono.
• hasPayment: true para cuotas con pago registrado, false para cuotas sin pago registrado.
• hasPayout: true para cuotas con dispersion/payout asociado, false para cuotas sin dispersion asociada.
• cardBrand: marca de tarjeta cuando exista en la informacion de pago.
• currency: filtra por divisa registrada en el mandato o sus cuotas. Valores del catálogo: PESOS, UF, DOLAR, UTM y EURO. La búsqueda no determina qué monedas admite una operación de creación ni un medio de pago.

Medios de pago soportados

Usa los filtros numéricos paymentMethodId e installmentPaymentMethodId.

Reglas anti-consultas amplias

• Un nombre no reconocido en un filtro nominal admitido, como installmentStatus=paidd, puede omitirse sin error. En listas, pueden aplicarse solo los valores reconocidos. Revisa los valores enviados y conserva los filtros de acotación requeridos.
• page y pageSize son siempre obligatorios.
• No existe modo "traer todo". Para proteger la base de datos, se debe usar un rango de fechas o un identificador especifico.
• Los filtros booleanos amplios, como hasPayment o hasPayout, deben combinarse con fechas, cliente, mandato, cuota o dispersion.
• Si se busca installmentStatus=deleted, la API incluye cuotas eliminadas. Si no se solicita explicitamente, las cuotas eliminadas quedan fuera de la respuesta por defecto.
• Todos los filtros se aplican contra la empresa autenticada; la empresa no puede consultar datos de otro comercio enviando IDs en query string.

Respuesta

La paginación se aplica antes de agrupar las cuotas por mandato. Una misma deuda puede aparecer en varias páginas con cuotas adicionales. returnedCount cuenta los mandatos agrupados de la página y hasMore indica si debes continuar. Consolida los resultados por sus IDs y consulta el detalle cuando necesites los atributos completos de una operación.

La respuesta estándar presenta valores fijos en mandate.charges.cumulative (true), mandate.needPayNow (false), mandate.terminateWhenCharged (false), mandate.isMall (false), mandate.serviceId (null) y customer.personalInformation.dateOfBirth (cadena vacía). Estos valores no consultan los atributos reales y no deben utilizarse para sincronizar esas configuraciones. El detalle de mandato permite consultar los atributos que entregue su variante.

• data: arreglo de mandatos/deudas con informacion del cliente, metadata de pago y cuotas anidadas.
• pagination: datos de paginacion: page, pageSize, returnedCount y hasMore.

Ejemplos recomendados

Buscar cuotas por vencimiento:
GET /receivables?page=1&pageSize=100&dueDateFrom=2026-01-01&dueDateTo=2026-01-31

Buscar por cliente y tipo de mandato:
GET /receivables?page=1&pageSize=50&customerRut=19.414.071-1&mandateType=dynamic

Buscar pagos realizados por fecha y medio de pago:
GET /receivables?page=1&pageSize=100&paymentDateFrom=2026-01-01&paymentDateTo=2026-01-31&installmentStatus=paid&installmentPaymentMethodId=3

Buscar cuotas con dispersion asociada:
GET /receivables?page=1&pageSize=100&hasPayout=true&paymentDateFrom=2026-01-01&paymentDateTo=2026-01-31

Buscar cuotas con transferencia electrónica:
GET /receivables?page=1&pageSize=100&dueDateFrom=2026-01-01&dueDateTo=2026-01-31&installmentPaymentMethodId=12