Ir a contenido
Crea una cuenta
o
Inicia sesión
Logotipo de Stripe Docs
/
Pregúntale a la IA
Crear una cuenta
Iniciar sesión
Empieza ahora
Pagos
Ingresos
Plataformas y marketplaces
Gestión del dinero
Recursos para desarrolladores
Resumen
Empieza a usar Connect
Fundamentos de la integración
    Hacer llamadas a la API para cuentas conectadas
    Recomendaciones de integración
    Prestar atención a las actualizaciones
    Pruebas
    Resumen de la API Accounts v2
Ejemplos de integraciones
Gestión de cuentas
Haz el onboarding de las cuentas
Configura los Dashboards de la cuenta
Trabaja con tipos de cuentas conectadas
Procesamiento de pagos
Aceptar pagos
Transfiere a cuentas
Administración de la plataforma
Gestiona tu plataforma Connect
Formularios fiscales para tu plataforma Connect
InicioPlataformas y marketplacesIntegration fundamentals

Webhooks de Connect

Aprende a usar webhooks con Connect para recibir notificaciones de la actividad de Stripe.

Stripe utiliza webhooks para notificar a tu aplicación cuando hay algún evento en tu cuenta. Todas las integraciones de Connect deben establecer un punto de conexión de webhooks para escuchar los eventos de Connect.

Webhooks de Connect

Una plataforma Connect utiliza dos tipos de webhooks:

  • Los webhooks Account son para actividades en tu propia cuenta (por ejemplo, la mayoría de las solicitudes hechas con tus claves API cuando no te autenticas como otra cuenta de Stripe). Esto incluye todo tipo de cargos, excepto los efectuados directamente en una cuenta conectada.
  • Los webhooks Connect son para actividades en cualquier cuenta conectada. Enviamos todos los eventos de la cuenta conectada (incluidas las actualizaciones de la cuenta y los cargos Direct) a los webhooks de Connect.

Al crear un webhook de Connect, debes configurarlo para recibir eventos de webhooks de Connect. Cuando lo crees en el Dashboard, selecciona Eventos en cuentas conectadas para Recibe notificaciones de. Cuando lo crees con una API, establece el parámetro connect en verdadero.

Configuración de webhook en el Dashboard de Stripe

En el caso de los webhooks Connect, las URL de webhooks de desarrollo solo reciben webhooks de prueba, pero las URL de webhooks de producción reciben webhooks activos y de prueba. Esto se debe a que puedes realizar transacciones en vivo y de prueba en una aplicación de producción. Te recomendamos que verifiques el valor livemode cuando recibas un webhook de evento para determinar si los usuarios deben realizar alguna acción.

Cada evento de una cuenta conectada contiene una propiedad account de nivel superior que identifica a la cuenta conectada. Debido a que la cuenta conectada es titular del objeto que activó el evento, debes realizar solicitudes API para ese objeto como cuenta conectada.

{ "id":
"{{EVENT_ID}}"
, "livemode": true, "object": "event", "type": "customer.created", "account":
"{{CONNECTED_ACCOUNT_ID}}"
, "pending_webhooks": 2, "created": 1349654313, "data": {...} }

En la siguiente tabla se describen algunos de los eventos más comunes e importantes relacionados con las cuentas conectadas:

Eventotipo data.objectDescripción
account.application.deauthorizedapplicationOcurre cuando una cuenta conectada se desconecta de tu plataforma. Puedes usarlo para activar la limpieza en tu servidor. Disponible para cuentas conectadas con acceso al Dashboard de Stripe, que incluye cuentas Standard.
account.external_account.updatedAUna cuenta externa, como card o bank_accountTiene lugar cuando se actualiza una cuenta bancaria o tarjeta de débito asociada a una cuenta conectada, lo que puede influir en las transferencias a cuentas bancarias. Disponible para las cuentas conectadas que tu plataforma controla, que incluye cuentas Custom y Express, y cuentas Standard con controles de plataforma habilitados.
account.updatedaccountTe permite monitorear los cambios en los requisitos de la cuenta conectada y los cambios de estado. Disponible para todas las cuentas conectadas.
balance.availablebalanceOcurre cuando se actualiza tu saldo de Stripe. Por ejemplo, cuando los fondos que agregaste desde tu cuenta bancaria estén disponibles para transferir a tu cuenta conectada.
payment_intent.succeededpayment_intentTiene lugar cuando un intento de pago se convierte en un cargo efectuado correctamente. Disponible para todos los pagos, incluidos los cargos a un destino y Direct.
payout.failedpayoutTiene lugar cuando falla una transferencia. Cuando una transferencia falla, se deshabilita la cuenta externa involucrada y no se pueden procesar transferencias automáticas ni manuales hasta que no se actualiza la cuenta externa.
person.updatedpersonOcurre cuando se actualiza una Person asociada con Account. Si usas la API Persons para gestionar los requisitos, recibe notificaciones de este evento para monitorear los cambios en los requisitos y los cambios de estado para particulares. Disponible para las cuentas conectadas que tu plataforma controla, que incluye cuentas Custom y Express, y cuentas Standard con controles de plataforma habilitados.
server.rb
Ruby
# Using Sinatra. require 'sinatra' require 'stripe' set :port, 4242 # Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
# If you're testing your webhook locally with the Stripe CLI, you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil # Verify webhook signature and extract the event. # See https://stripe.com/docs/webhooks#verify-events for more information. begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload. status 400 return rescue Stripe::SignatureVerificationError => e # Invalid Signature. status 400 return end if event['type'] == 'account.application.deauthorized' application = event['data']['object'] connected_account_id = event['account'] handle_deauthorization(connected_account_id, application) end status 200 end def handle_deauthorization(connected_account_id, application) # Clean up account state. puts 'Connected account ID: ' + connected_account_id puts application.to_s end

Probar webhooks a nivel local

Puedes probar webhooks a nivel local con la CLI de Stripe.

  1. Si todavía no lo hiciste, instala la CLI de Stripe en tu equipo.

  2. Inicia sesión en tu cuenta de Stripe y configura la CLI ejecutando stripe login en la línea de comandos.

  3. Le permite a tu host local recibir un evento simulado en tu cuenta conectada ejecutando stripe listen --forward-to localhost:{PORT}/webhook en una ventana de terminal y stripe trigger {{EVENT_NAME}} en otra.

Nota

Para webhooks de Connect, usa –forward-connect-to con stripe listen y –stripe-account con stripe trigger

Consulta también

  • Documentación de webhooks
  • Referencia sobre el objeto Event
¿Te fue útil esta página?
SíNo
¿Necesitas ayuda? Ponte en contacto con soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Contacto.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc