Capta y responde rechazos, datos no válidos, problemas de red, etc.
Stripe ofrece varios tipos de errores. Estos pueden reflejar eventos externos, como pagos fallidos e interrupciones de redes, o problemas de código, como llamadas API no válidas.
Investigar problemas anteriores y admitir otras técnicas
A veces
Captar excepciones
Si un problema inmediato evita que continúe una llamada API, la librería de Ruby para Stripe lanza una excepción. Captar y gestionar las excepciones es una práctica recomendada.
Para detectar una excepción, usa la palabra clave rescue de Ruby. Captura Stripe::StripeError o sus subclases para gestionar solo las excepciones específicas de Stripe. Cada subclase representa un tipo diferente de excepción. Cuando detectes una excepción, puedes usar su clase para elegir una respuesta.
defexample_function(params)beginStripe::PaymentIntent.create(params)rescueStripe::CardError=> e
puts "A payment error occurred: #{e.error.message}"rescueStripe::InvalidRequestError=> e
puts "An invalid request occurred."rescueStripe::StripeError=> e
puts "Another problem occurred, maybe unrelated to Stripe."else
puts "No error."endend
Después de configurar la gestión de excepciones, pruébala con varios datos, incluidas las tarjetas de prueba, para simular diferentes resultados de pago.
Stripe te notifica sobre muchos tipos de problemas utilizando webhooks. Esto incluye problemas que no se producen inmediatamente después de una llamada a la API. Por ejemplo:
Pierdes una disputa.
Un pago recurrente falla después de haberse cobrado correctamente durante meses.
Tu front-end confirma un pago, pero se desconecta antes de saber que el pago falló. (El back-end sigue recibiendo notificaciones del webhook, aunque no haya sido el que realizó la llamada API).
No necesitas manejar todos los tipos de eventos de webhook. De hecho, algunas integraciones no manejan ninguna.
En tu controlador de webhook, comienza con los pasos básicos desde el creador de webhooks: obtén un objeto Event y usa el tipo de evento para descubrir qué sucedió. Luego, si el tipo de evento indica que ocurrió un error, debes seguir estos pasos adicionales:
require'stripe'require'sinatra'
post '/webhook'do
payload = request.body.read
data =JSON.parse(payload, symbolize_names:true)# Get the event object
event =Stripe::Event.construct_from(data)# Use the event type to find out what happenedcase event.type
when'payment_intent.payment_failed'# Get the object affected
payment_intent = event.data.object
# Use stored information to get an error object
e = payment_intent.last_payment_error
# Use its type to choose a responsecase e.type
when'card_error'
puts "A payment error occurred: #{e.message}"when'invalid_request'
puts "An invalid request occurred."else
puts "Another problem occurred, maybe unrelated to Stripe."endend
content_type 'application/json'{
status:'success'}.to_json
end
Para probar cómo responde tu integración a los eventos de webhook, puedes activar eventos de webhook localmente. Después de completar los pasos de configuración en ese enlace, activa un pago fallido para ver el mensaje de error resultante.
Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.
Obtener información almacenada sobre errores
Muchos objetos almacenan información sobre errores. Eso significa que si algo ya salió mal, puedes recuperar el objeto y examinarlo para obtener más información. En muchos casos, la información almacenada tiene la forma de un objeto de error, y puedes usar su tipo para elegir una respuesta.
Por ejemplo:
Recupera un Payment Intent específico.
Verifica si se produjo un error de pago determinando si last_payment_error está vacío.
De ser así, registra el error. Incluye el tipo de error y el objeto afectado.
Para probar código que usa información almacenada sobre errores, a menudo necesitarás simular transacciones fallidas. Por lo general, puedes hacerlo usando tarjetas de prueba o números bancarios de prueba. Por ejemplo:
Simula un pago rechazado para crear Charges, PaymentIntents y SetupIntents fallidos, entre otros.
En la librería Ruby de Stripe, los objetos Error son parte de stripe.error.StripeError y sus subclases. Utiliza la documentación de cada clase para ver consejos sobre cómo responder.
Este error puede ocurrir cuando la integración funciona correctamente. Refleja una acción del emisor, y esa acción puede ser legítima. Usa el código de rechazo para determinar qué pasos debes seguir. Consulta la documentación sobre códigos de rechazo para ver las respuestas apropiadas para cada código.
This error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code.
Errores de solicitudes no válidas
Type
Stripe::InvalidRequestError
Problema
You made an API call with the wrong parameters, in the wrong state, or in an invalid way.
Soluciones
In most cases, the problem is with the request itself. Either its parameters are invalid or it can’t be carried out in your integration’s current state.
For convenience, you can follow the link at for documentation about the error code.
If the error involves a specific parameter, use to determine which one.
Errores de conexión
Type
Stripe::APIConnectionError
Problema
There was a network problem between your server and Stripe.
Solutions
Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that if failed.
To find out if it succeeded, you can:
Retrieve the relevant object from Stripe and check its status.
Listen for webhook notification that the operation succeeded or failed.
To make it easier to recover from connection errors, you can:
Al crear o actualizar un objeto, usa una clave de idempotencia. Luego, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto o realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que recibas un claro éxito o error. Para obtener consejos avanzados sobre esta estrategia, consulta Gestión de errores de bajo nivel.
Habilita los reintentos automáticos. Luego, Stripe genera las claves de idempotencia y, cuando es seguro hacerlo, repite las solicitudes por ti.
Este error puede ocultar otros. Es posible que aparezca otro error después de que se resuelva el problema de conexión. Revisa que no haya errores en todas estas soluciones, al igual que lo harías en la solicitud original.
Errores de API
Type
Stripe::APIError
Problem
Something went wrong on Stripe’s end. (These are rare.)
Soluciones
Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló.
Rely on webhooks for information about the outcome. Whenever possible, Stripe fires webhooks for any new objects we create as we solve a problem.
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
Errores de límite de frecuencia
Tipo
Stripe::RateLimitError
Problem
Hiciste demasiadas llamadas API en muy poco tiempo.
Soluciones
Si una sola llamada API activa este error, espera y vuelve a intentarlo.
Para gestionar el límite de velocidad de forma automática, reintenta la llamada API después de cierto tiempo. Aumenta exponencialmente ese período si el error persiste. Consulta la documentación sobre límite de frecuencia para leer más consejos.
Si anticipas que tendrás un gran incremento del tráfico y quieres solicitar un aumento del límite de frecuencia, ponte en contacto con soporte por adelantado.
This error can occur when your integration is working correctly. If you use webhook signature verification and a third party attempts to send you a fake or malicious webhook, then verification fails and this error is the result. Catch it and respond with a 400 Bad Request status code.
Si recibes este error y consideras que no debería ocurrir (por ejemplo, al usar webhooks que sabes que se originaron en Stripe), consulta la documentación sobre cómo verificar las firmas de webhooks. En particular, debes asegurarte de estar usando el secreto del punto de conexión correcto. Ten en cuenta que es diferente de la clave de API.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
Stripe Shell funciona mejor en una computadora de escritorio.