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

• mandateCode: codigo visible del mandato/deuda.
• externalMandateId: identificador externo del mandato informado por la empresa.
• 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.
• mandateStatus: estado del mandato. Valores: active: activo. paid: pagado. deleted: eliminado. rescheduled: repactado. postponed: postergado. annulled: anulado. pendingCancellation: pendiente de anulacion. inactive: inactivo. rejected: rechazado. finalized: finalizado. bankConfirmation: confirmacion bancaria.
• mandatePaymentMethod: medio de pago principal del mandato, usando clave en ingles.
• paymentMethodId: ID numerico del medio de pago principal del mandato.
• paymentMethodName: nombre del medio de pago principal del mandato.
• mandateAmountMin / mandateAmountMax: rango de monto del mandato/deuda.

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.
• installmentPaymentMethod: medio de pago usado por la cuota, usando clave en ingles.
• installmentPaymentMethodId: ID numerico del medio de pago usado por la cuota.
• installmentPaymentMethodName: nombre del medio de pago usado por la cuota.
• 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: moneda. Valores: PESOS: pesos chilenos. UF: unidad de fomento. USD: dolares estadounidenses.

Medios de pago soportados

• check / 1: Cheque.
• bankDeposit / 2: Deposito bancario.
• creditCard / 3: Tarjeta de credito.
• debitCard / 4: Tarjeta de debito.
• directDebit / 5: Debito directo.
• bankAccount / 6: Cuenta bancaria.
• checkingAccount / 7: Cuenta corriente.
• transfer / 10: Transferencia.
• noAutomaticPayment / 11: Sin pago automatico.
• prepaidCard / 12: Tarjeta prepago.
• tef / 13: TEF.
• fintocSubscription / 14: Fintoc subscription.
• directEpac / 15: Direct EPAC.
• traditionalPat / 16: PAT tradicional.
• transdata / 17: Transdata.
• clickToPay / 18: Click to Pay.
• cash: Efectivo, cuando el comercio lo tenga habilitado.
• neatPagos: Neat Pagos, cuando el comercio lo tenga habilitado.
• bankButtons / 19: Botones Bancarios.

Reglas anti-consultas amplias

• 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

• 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&installmentPaymentMethod=creditCard

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

Buscar por identificador externo de mandato:
GET /receivables?page=1&pageSize=20&externalMandateId=ORDER-12345