resource.event, y el campo data del evento lleva el recurso afectado.
Para conocer el envoltorio que acompaña a cada evento, revisa el objeto Event. Para construir un endpoint que reciba eventos, sigue la guía de webhooks, que cubre la validación de firmas y el esquema de reintentos.
Usa la columna Producto para elegir los eventos del producto que estás integrando. Algunos eventos corresponden a más de un producto.
Qué eventos usar según tu producto
Qué eventos usar según tu producto
Business Accounts vs. PaymentsPara transferencias de Business Accounts, suscríbete a
transfer.inbound.* o transfer.outbound.*. Los eventos checkout_session.*, payment_intent.* y payout.* corresponden a Payments. Un Payout liquida los fondos recaudados mediante Payments a tu cuenta bancaria; no representa una transferencia saliente de Business Accounts.Eventos compartidos de Direct Debit y PaymentsLos eventos subscription_intent.* y charge.* corresponden a Direct Debit. Payments también emite estos eventos al inscribir cuentas bancarias y procesar cobros mediante Pago Automático de Cuentas (PAC) en Chile. Estos eventos no corresponden a pagos con tarjeta.Si integras suscripciones de Payments, sigue la guía de pagos recurrentes para conocer los eventos de checkout, métodos de pago e invoices que debes manejar.Eventos de pago de una invoice
Una invoice llega apaid de dos formas, y los eventos son distintos. Cuando Fintoc cobra la invoice, recibes invoice.payment_succeeded y después invoice.paid. Cuando marcas la invoice como pagada porque tu cliente te pagó fuera de Fintoc, recibes solo invoice.paid.
Lee external_payment en el payload para distinguir los dos casos. El valor es false cuando la plata pasó por Fintoc y true cuando no.
Anticipos de invoice
Fintoc envíainvoice.upcoming antes de cada ciclo de facturación para que puedas avisarle a tu cliente antes de cobrarle. Contacta a Fintoc para definir con cuántos días de anticipación lo recibes.
El payload anticipa una invoice que todavía no existe, así que dos campos se comportan distinto que en el resto de los eventos invoice.*:
- La invoice no trae
id, porque Fintoc todavía no la creó. - El
resource_iddel evento lleva la suscripción, no la invoice.
Payload de onboarding de una Entity
Los eventosentity.onboarding.approved y entity.onboarding.rejected llevan el objeto Onboarding completo, así que puedes leer los datos revisados de cada paso en data, los documents subidos y los legal_representatives y shareholders declarados sin volver a llamar a la API. El payload omite submittable, porque un onboarding ya revisado no se puede volver a enviar.
Por compatibilidad hacia atrás, el payload también mantiene dos campos que el objeto Onboarding no tiene:
object_name: Siempreonboarding_process.entity: Un resumen de laEntitycon suid,holder_id,holder_nameynationality.
type para distinguir los dos tipos de onboarding. Las llaves dentro de data y los slots de documents dependen de type y del país de la Entity.
Account holder
Un onboardingaccount_holder aprobado permite que la Entity tenga objetos Account en Fintoc. El ejemplo muestra un onboarding account_holder mexicano aprobado:
Onboarding para ver todos los campos de data, legal_representatives, shareholders y documents.
Settlement recipient
Un onboardingsettlement_recipient permite que la Entity reciba pagos divididos. data.company_information.settlement_account contiene la cuenta bancaria donde Fintoc le paga su parte a la Entity. Un onboarding settlement_recipient chileno no abre slots de documentos, así que documents y los documents de cada representante legal vienen vacíos. El ejemplo muestra un onboarding settlement_recipient chileno aprobado de una empresa:
Entity que hace el onboarding como persona natural, Fintoc ignora legal_representatives, transactional_profile y shareholders. El payload trae los arreglos legal_representatives y shareholders vacíos, y data contiene solo company_information.
Reintentar tras un rechazo
Lo que puedes hacer después deentity.onboarding.rejected depende del type del onboarding:
account_holder: No puedes reintentar con la API. UnaEntitytiene un solo onboardingaccount_holderpor modo, así que crear otro devuelve409 Conflictcon el códigoconflicted_request, incluso después de un rechazo. Contacta al soporte de Fintoc para revisar el caso. Fintoc puede volver a revisar un onboarding rechazado y aprobarlo. En ese caso recibesentity.onboarding.approvedcon el mismoidde onboarding, así que tu handler debe aceptar una aprobación que llega después de un rechazo.settlement_recipient: Crea un nuevo onboarding para la mismaEntitycon los datos corregidos. Un onboardingrejectedoapprovedno bloquea uno nuevo. Mientras otro onboardingsettlement_recipientde laEntitysiga enpending,in_progressosubmitted, crear uno nuevo devuelve409 Conflict.