Esta página concentra todos los identificadores (IDs) utilizados en los webhooks y la API de Forpay para clasificar medios de pago, estados de cuotas y estados de compromisos.
1. Medios de pago: entrada, activación y pago
Los IDs de creación y los IDs de respuesta cumplen funciones diferentes. paymentMethods selecciona los medios disponibles para el cliente. Los webhooks y consultas informan el medio asociado al mandato o utilizado por un pago mediante los campos de cada operación. El ID de entrada no se devuelve necesariamente en la respuesta.
1.1. Entrada: seleccionar medios al crear un mandato
paymentMethods es un array opcional. Cada elemento puede ser un nombre público (string) o su ID de entrada (integer); se permiten listas mixtas. Si se omite, se utilizan los medios disponibles para el comercio. Cada tipo de mandato admite un subconjunto del catálogo y el comercio debe tener habilitado el medio elegido: consulta las opciones de la operación de creación correspondiente.
| Nombre público | ID de entrada | Uso |
|---|---|---|
ONECLICK | 1001 | Inscripción de tarjeta para pagos automáticos. |
WEBPAY_PLUS | 1002 | Pago con tarjeta. |
FORPAC | 1003 | Inscripción PAC con Clave Única. |
DIRECT_DEBIT | 1004 | Inscripción de cuenta para débito directo. |
GETNET_CLICK | 1005 | Inscripción de tarjeta para pagos automáticos. |
GETNET_TOKENIZACION | 1006 | Tokenización de tarjeta; no está habilitada en la creación de mandatos documentada. |
WEB_CHECKOUT | 1007 | Pago con tarjeta mediante checkout. |
EFT | 1008 | Pago por transferencia electrónica. |
BANK_BUTTONS | 1009 | Pago mediante botones bancarios. |
PAC_SUBSCRIPTION | 1010 | Inscripción PAC. |
FORPAC_SUBSCRIPTION | 1011 | Inscripción PAC para ForPAC. |
PHYSICAL_UNIVERSE | 1012 | Inscripción PAC física con confirmación bancaria. |
PHYSICAL_UNIVERSE_BANK_PORTAL | 1013 | Inscripción PAC desde portal bancario con confirmación bancaria. |
KLAP_APPLE_PAY | 1014 | Pago mediante Apple Pay. |
KLAP_GOOGLE_PAY | 1015 | Pago mediante Google Pay. |
KLAP_CLICK_TO_PAY | 1016 | Pago mediante Click to Pay. |
KLAP_CHECKOUT_FLEX | 1017 | Pago con tarjeta mediante Checkout Flex. |
1.2. Activación: identificar el medio asociado
En los webhooks de activación, el objeto paymentMethod describe el medio asociado al mandato. Los datos de tarjeta, cuenta y documento dependen del evento; no son requisitos simultáneos de todos los webhooks. Los campos de la tabla se leen cuando el evento incluye el objeto correspondiente.
| Campo | Tipo JSON | Descripción y condición |
|---|---|---|
paymentMethod.id | number | Clasificación del medio asociado. En activación de tarjetas: 3 crédito, 4 débito o 11 prepago; en la activación ForPAC: 6. No identifica el selector de creación. |
paymentMethod.description | string | Descripción enviada por ese evento. Puede diferir del nombre público de entrada. |
paymentMethod.card.last4digits | string | Últimos cuatro dígitos, en eventos de tarjeta. |
paymentMethod.card.brand.id / .name | number / string | Identificador y nombre de la marca, cuando se incluyen datos de tarjeta. |
paymentMethod.account.type.id / .name | number / string | Identificador y nombre del tipo de cuenta, en eventos bancarios. |
paymentMethod.account.number | number en los eventos ForPAC y PAC con credenciales bancarias documentados | Número de la cuenta asociada. El tipo se interpreta según el contrato del evento; no se extrapola a otros webhooks. |
paymentMethod.account.bank | object | Datos del banco cuando el evento los incluye. En ForPAC: code, name y centralBankCode son string. |
paymentMethod.account.document | object | Datos del documento de inscripción cuando corresponden al evento. No está presente en todas las modalidades PAC. |
subscription.internalId / .externalId | number / string | Identificador de la inscripción en Forpay y referencia de esa inscripción en el procesador. No son IDs de medio de pago. |
El webhook de PAC con credenciales bancarias utiliza IDs operativos 13 o 14 según el evento. Esto no establece una equivalencia uno a uno con los selectores PAC_SUBSCRIPTION o FORPAC_SUBSCRIPTION. Para el contenido y las condiciones de cada variante, consulta tarjetas, ForPAC con Clave Única y credenciales bancarias.
1.3. Pago y consultas: identificar el medio utilizado
La ubicación del dato cambia entre un webhook y una respuesta de consulta. Los nombres de los campos no se intercambian. Las rutas de consulta siguientes incluyen el envoltorio de la respuesta HTTP.
Webhook de pago
- Campo:
payment.method.id/.description - Tipo JSON:
number/string
Clasificación y descripción del medio utilizado, cuando el evento incluye payment.method. Ejemplos: 5 débito directo, 6 ForPAC, 12 transferencia electrónica y 19 botones bancarios.
Webhook de pago con tarjeta
- Campo:
payment.method.card.last4digits/.brand.name - Tipo JSON:
string/string
Últimos cuatro dígitos y marca de la tarjeta, cuando el evento incluye datos de tarjeta.
Webhook de pago bancario
- Campo:
payment.method.account.number - Tipo JSON:
stringen Débito Directo y EFT;numberen ForPAC
Cuenta utilizada por el pago. El tipo y los demás datos bancarios dependen del contrato del evento.
Consulta de mandato
- Campo:
payload.payload.mandate.paymentMethod.id/.name - Tipo JSON:
integer/string
Medio asociado al mandato, cuando está disponible.
OnePay Confirm
- Campo:
payload.payload.installments[].payment.method.id/.description - Tipo JSON:
number/string
Clasificación y descripción del medio informado para cada cuota. payment puede estar ausente cuando no hay información de pago asociada.
Search: medio del mandato
- Campo:
payload.data[].mandate.paymentMethod.id/.name - Tipo JSON:
integeronull/stringonull
Clasificación del medio del mandato.
Search: medio de la cuota
- Campo:
payload.data[].installments[].paymentMethod.id/.name - Tipo JSON:
integeronull/stringonull
Clasificación del medio de esa cuota.
Filtros de Search
- Campo:
paymentMethodId/installmentPaymentMethodId - Tipo JSON:
integer
Filtran por el ID operativo del medio del mandato o de la cuota, respectivamente. Utiliza el catálogo de la operación Search.
El objeto payment no implica por sí solo un pago exitoso: revisa el estado de la cuota y los campos incluidos en el evento o respuesta. Los textos name y description, y los datos adicionales de metadata, conservan el contenido generado por cada operación; elegir un nombre público al crear no los renombra.
Ejemplo EFT: para seleccionar transferencia electrónica al crear un mandato que admita esta opción, envía "paymentMethods": ["EFT"] o "paymentMethods": [1008]. En el webhook de pago EFT, el medio se informa como "payment": { "method": { "id": 12, "description": "EFT" } }. Para buscar cuotas de ese medio usa installmentPaymentMethodId=12, junto con los demás parámetros requeridos de Search. 1008 es el selector de entrada y 12 es la clasificación operativa; no son intercambiables.
Los IDs operativos se interpretan dentro de cada operación. No existe una correspondencia única para todo el catálogo de entrada: varios productos pueden devolver el mismo tipo de tarjeta o cuenta. La respuesta del evento u operación correspondiente es la que identifica el medio utilizado.
2. Estados de Cuotas (installment.state.id)
installment.state.id)Indica la situación actual de una cuota específica dentro del ciclo de cobro.
| ID | Estado | Descripción |
|---|---|---|
| 1 | PENDIENTE | Cuota generada, a la espera de su fecha de cobro |
| 2 | PAGADA | Cobro realizado con éxito. Genera authorizationCode |
| 6 | ANULADA | La cuota fue invalidada antes de ser procesada |
| 8 | INACTIVA | Cuota en estado inactivo reconocido por Search |
| 9 | EN PROCESO DE COBRO | La transacción fue enviada al procesador de pagos |
| 10 | REPACTADA | La deuda fue movida a un nuevo compromiso o estructura |
| 11 | FINALIZADA | Proceso de cobro concluido |
| 12 | REVERSADA | El pago fue devuelto al cliente |
| 15 | EN VALIDACIÓN | Esperando confirmación externa de éxito |
| 17 | ELIMINADA | Excluida en Search salvo filtro explícito installmentStatus=17 |
| 18 | PAUSADA | Cuota en estado pausado reconocido por Search |
| -99 | RECHAZADA | Cobro fallido por el procesador de pagos |
Cuando el objeto
paymentesté presente, concatenapayment.id,payment.authorizationCode,payment.amountypayment.dateTimedespués de los campos base. Esto también aplica a una notificación REVERSADA (12) que incluyapayment. Cuando el objeto esté ausente, utiliza solo los campos base. Elimina todos los caracteres de espacio en blanco del texto concatenado antes de calcular el HMAC. Ver Verificación HMAC.
3. Estados de Compromisos (product.state.id)
product.state.id)Indica la situación global del mandato o suscripción del cliente.
| ID | Estado | Descripción |
|---|---|---|
| 1 | ACTIVA / AUTOMATIZADA | El compromiso está activado con un medio de pago automático. |
| 2 | PAGADA | Todas las cuotas del compromiso han sido completadas, aplica en suscripciones y planes de pago. |
| 3 | ELIMINADA | El compromiso fue borrado del sistema. |
| 4 | REPACTADA | Las condiciones originales fueron modificadas, aplica solo para planes de pago no modificados por API. |
| 5 | POSTERGADA | El compormiso de pago está pausado temporalmente. |
| 6 | ANULADA | El compromiso fue anulado definitivamente. |
| 7 | PENDIENTE DE ANULACIÓN | Solicitud de baja en solicitada por el cliente. |
| 8 | INACTIVA / NO AUTOMATIZADA | El compromiso ha sido creado pero no tiene un medio de pago automático. |
| 9 | RECHAZADA | El compromiso de pago fue rechazado por el cliente. |
| 10 | FINALIZADA | El compromiso fue finalizado anticipadamente. |
| 11 | EN CONFIRMACIÓN BANCO | Esperando validación del mandato PAC por parte de la institución bancaria. |
Nota: Para los eventos habilitados, el webhook de activación informa cuando el mandato pasa al estado
1(ACTIVA). El estado11puede recibirse en activaciones PAC mientras el banco confirma el mandato PAC.
4. Tipos de Cuenta (paymentMethod.account.type.id)
paymentMethod.account.type.id)Identifica el tipo de cuenta bancaria del cliente.
| ID | Tipo de Cuenta |
|---|---|
| 1 | Cuenta Corriente |
| 2 | Cuenta Vista |
| 3 | Cuenta de Ahorro |
5. Monedas: valores de entrada e identificadores de respuesta
El catálogo contempla cinco divisas. En los campos de entrada currencyId se utiliza el literal de texto de la tabla, no el ID numérico de respuesta. Los campos currency.id de las respuestas identifican la divisa mediante un número.
| Moneda | Literal de entrada (string) | ID de respuesta (number) | Símbolo |
|---|---|---|---|
| Peso chileno | PESOS | 1 | CLP / $ |
| Unidad de Fomento | UF | 2 | UF |
| Dólar estadounidense | DOLAR | 3 | USD / US$ |
| Unidad Tributaria Mensual | UTM | 4 | UTM |
| Euro | EURO | 5 | EUR / € |
La disponibilidad depende de la operación, del campo y del medio de pago utilizado. Que una solicitud admita una divisa no significa que todos los medios habilitados permitan cobrar directamente en ella. Utiliza el subconjunto admitido por el campo y considera la conversión aplicable al medio de pago.
| Operación y campo de entrada | Divisas admitidas en ese campo |
|---|---|
Creación Dynamic: mandate.charges.values.currencyId e installments[].currencyId | PESOS, UF, DOLAR, UTM, EURO |
Creación Permanent y OnePay: mandate.charges.totalAmounts[].currencyId | PESOS, UF, DOLAR, UTM, EURO |
Creación Permanent y OnePay: installments[].currencyId | PESOS, UF, DOLAR, UTM |
Creación Subscription mensual: mandate.charges.paymentPeriod.currencyId | PESOS, UF, DOLAR, UTM, EURO |
Creación Subscription de periodicidad alternativa: mandate.charges.paymentPeriod.currencyId | PESOS, UF, DOLAR, UTM |
Creación Subscription: installments[].currencyId | PESOS, UF, DOLAR, UTM, EURO |
Creación de cuotas (POST /installments): installments[].currencyId | PESOS, UF, DOLAR, UTM, EURO |
Update de suscripción, contrato mensual documentado: mandate.charges.paymentPeriod.currencyId | PESOS, UF, DOLAR, UTM, EURO; se envía junto con amount. |
Por ejemplo, "currencyId": "DOLAR" identifica una divisa en una solicitud que la admita; una respuesta puede representarla como "currency": { "id": 3, "name": "DOLAR" }. Para pesos chilenos, el literal de entrada es PESOS; CLP es el símbolo mostrado en este catálogo.
Cuando el pago incluya payment.convert, sus campos describen la conversión aplicada: currency identifica la divisa base, amount informa el factor o valor de conversión y date su fecha. Distingue el monto denominado en la divisa de la cuota del monto efectivamente cobrado. Revisa el contrato del webhook o consulta para interpretar ambos importes y la disponibilidad de los datos de conversión.
El estado -99 expresa el rechazo de un intento de cobro en el webhook. Una consulta posterior puede mostrar la cuota en PENDIENTE. Para consultar cuotas en Search utiliza los estados persistidos admitidos por esa operación.