Administración de errores
Captura y responde a pagos rechazados, datos no válidos, problemas de red y mucho más.
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 a la API no válidas.
Para gestionar errores, usa todas o algunas de las técnicas de la tabla que figura a continuación. Sea cual sea la técnica que uses, puedes seguir con nuestras respuestas recomendadas para cada tipo de error.
Técnica | Finalidad | En caso necesario |
---|---|---|
Usar valores de errores | Recuperar una llamada a la API cuando esta no puede continuar | Siempre |
Controlar los webhooks | Reaccionar a las notificaciones de Stripe | A veces |
Obtener información almacenada sobre fallos | Investigar problemas pasados y aceptar otras técnicas | A veces |
Usar valores de errores
Las llamadas a la API en la biblioteca de Go de Stripe devuelven tanto un valor de resultado como un valor de error. Usa varias asignaciones para capturar ambos. Si el valor de error no es nil
, significa que un problema inmediato ha evitado que la llamada a la API continuara.
Si el valor de error está relacionado con Stripe, puedes convertirlo a un objeto stripe.
, que tiene campos para describir el problema. Usa el campo de tipo para elegir una respuesta. En algunos casos, puedes forzar la propiedad Err
a un tipo de error más específico con información adicional.
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.
Controlar los webhooks
Stripe te notifica sobre varios tipos de problemas mediante los webhooks. Entre ellos, se incluyen los problemas que no ocurren 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 ha fallado. (El back-end sigue recibiendo notificaciones del webhook, aunque no haya sido el que hizo la llamada a la API).
No necesitas manejar todos los tipos de eventos de webhook. De hecho, algunas integraciones no manejan ninguno.
En tu controlador de webhook, comienza siguiendo los pasos básicos desde el creador de webhooks: obtén un objeto de evento y usa el tipo de evento para descubrir qué ha suciedido. Luego, si el tipo de evento indica que se ha producido un error, debes seguir estos pasos adicionales:
- Obtén el objeto afectado convirtiendo los datos mediante el proceso de unmarshalling desde
event.
.Data. Raw - Usa información almacenada en el objeto afectado para obtener contexto, incluido un objeto de error.
- Use su tipo para elegir una respuesta.
Para probar cómo responde tu integración a los eventos de webhook, puedes activar eventos de webhook de forma local. Después de completar los pasos de configuración en ese enlace, efectúa un pago fallido para ver el mensaje de error resultante.
stripe trigger payment_intent.payment_failed
A payment error occurred: Your card was declined.
Obtén información almacenada sobre errores
Muchos objetos almacenan información sobre errores. Esto significa que, si ya ha habido un problema, puedes recuperar el objeto y revisarlo para obtener más información. En muchos casos, la información almacenada se presenta en forma de un objeto de error, por lo que puedes usar el tipo de error para elegir una respuesta.
Por ejemplo:
- Recupera un Payment Intent específico.
- Comprueba si se ha producido un error en el pago determinando si last_payment_error está vacío.
- Si lo hizo, registra el error, incluido su tipo y el objeto afectado.
Aquí hay objetos comunes que almacenan información sobre fallos.
Objeto | Atributo | Valores |
---|---|---|
Payment Intent | last_ | Un objeto de error |
Setup Intent | last_ | Un objeto de error |
Factura | last_ | Un objeto de error |
Intento de configuración | setup_ | Un objeto de error |
Transferencia | failure_ | Un código de error de transferencia |
Reembolsar | failure_ | Un código de reembolso fallido |
Para probar código que usa información almacenada sobre errores, a menudo tendrás que simular transacciones fallidas. Por lo general, puedes hacerlo usando tarjetas de prueba o números bancarios de prueba. Por ejemplo:
- Simular un pago rechazado, para crear Cargos, PaymentIntents, SetupIntents, etc. fallidos.
- Simula una transferencia fallida.
- Simula un reembolso fallido.
Tipos de errores y respuestas
En la biblioteca de Go de Stripe, cada objeto de error tiene un atributo Type
. Utiliza la documentación de cada tipo para ver consejos sobre cómo responder.
Nombre | Tipo | Descripción |
---|---|---|
Error de pago | Se ha producido un error durante un pago debido a alguno de estos motivos: | |
Errores de solicitud no válida | Has hecho una llamada a la API de una forma que no es válida en este momento. El motivo puede haber sido alguno de los siguientes: | |
Error de API | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | |
Error de idempotencia | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Errores de tarjetas
Los errores de pago, a veces llamados «errores de tarjeta» por motivos históricos, cubren una amplia variedad de problemas comunes. Están divididos en tres categorías:
To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Users on API version 2022-08-01 or older:
(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)
Puedes activar algunos tipos habituales de error de pago con tarjetas de prueba. Consulta las opciones en estas listas:
El código de prueba que figura a continuación muestra algunas posibilidades.
Bloqueado por presunto fraude
Tipo |
|
Códigos |
|
Códigos |
|
Problema | El sistema de prevención de fraude de Stripe, Radar, ha bloqueado el pago |
Soluciones | Este error se puede producir cuando tu integración esté funcionando correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente:
Los clientes de Radar for Fraud Teams tienen estas opciones adicionales:
You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation. |
Rechazado por el emisor
Tipo |
|
Códigos |
|
Problema | El emisor de la tarjeta ha rechazado el pago. |
Soluciones | This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action may be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code. También puedes:
Test how your integration handles declines with test cards that simulate successful and declined payments. |
Otros errores de pago
Tipo |
|
Problema | Se produjo otro error de pago. |
Soluciones | 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
Los errores de solicitud no válida cubren varias situaciones. La más común es aquella en la que la petición a la API tiene parámetros no válidos o no está permitida con el estado actual de tu integración. Utiliza el código de error (stripeErr.
) y consulta la documentación de código de error para encontrar una solución. Algunos códigos de error requieren una respuesta especial:
rate_
ylimit lock_
reflejan errores de límite de velocidadtimeout secret_
refleja un error de autenticaciónkey_ required - Otros códigos de error reflejan parámetros o estados no válidos
Errores de límite de velocidad
Tipo |
|
Códigos | stripeErr. |
Problema | Has hecho demasiadas llamadas a la API en muy poco tiempo. |
Soluciones |
|
Errores de autenticación
Tipo |
|
Códigos | stripeErr. |
Problema | Stripe no puede autenticarte con la información proporcionada. |
Soluciones |
|
Estado o parámetro inválido
Tipo |
|
Códigos | stripeErr. |
Problema | Has hecho una llamada a la API con parámetros erróneos, en el estado equivocado o de forma no válida. |
Soluciones | En la mayoría de los casos, el problema es de la solicitud misma. Puede ser que los parámetros no sean válidos o que la solicitud no pueda realizarse en el estado actual de tu integración.
|
Errores de API
Tipo |
|
Problema | Se ha producido un error del lado de Stripe. (Esto no suele ocurrir). |
Soluciones | Trata el resultado de la llamada a la API como indeterminado. Es decir, no des por sentado que se ha llevado a cabo correctamente ni que ha fallado. Recurre a los webhooks para obtener información sobre el resultado. Cuando es posible, Stripe activa webhooks para todos los objetos nuevos que se crean mientras se resuelve un problema. To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors. |
Errores de idempotencia
Tipo |
|
Problema | You used an idempotency key for something unexpected, like replaying a request but passing different parameters. |
Soluciones |
|