# Administración de errores 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. ## Analizar datos de errores Cuando Stripe devuelve un error a tu solicitud de API, recibes detalles sobre el error que te ayudarán a entender cómo aplicar las sugerencias de gestión en esta guía. Estos detalles también te ayudan a proporcionar información importante al soporte de Stripe, si es necesario. | Propiedad | Descripción | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | El código de error. | | `doc_url` | Un enlace a la documentación de Stripe para el código de error específico. | | `message` | Una descripción del motivo del error. | | `param` | El parámetro de la solicitud que causó el error. | | `request_log_url` | Un enlace al Dashboard de Stripe donde puedes ver registros detallados sobre la solicitud original y el error. | | ID de la solicitud | Identificador único de la solicitud original que produjo un error. El encabezado de respuesta de error incluye este valor (cadena que comienza con `req`), pero puedes especificar una impresión en tu solicitud, como se muestra en los ejemplos de código de esta guía. | | `type` | Una referencia a la categoría de error a la que pertenece este error. | 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](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce como excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato evita que continúe una llamada API, la biblioteca 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](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce como excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que una llamada a la API continúe, la biblioteca de Stripe Python genera una excepción. Es una buena práctica detectar y gestionar las excepciones. Para detectar una excepción, usa la sintaxis `try`/`except` de Python. Atrapa `stripe.StripeError` o sus subclases para gestionar solo excepciones específicas de Stripe. Cada subclase representa un tipo diferente de excepción. Cuando captas una excepción, puedes [usar su clase para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce como excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que una llamada a la API continúe, la biblioteca de Stripe PHP genera una excepción. Es una buena práctica detectar y gestionar las excepciones. Para detectar una excepción, usa la sintaxis `try`/`catch` de PHP. Stripe ofrece varias clases de excepciones que puedes capturar. Cada una representa un tipo diferente de error. Cuando detectas una excepción, puedes [usar su clase para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce como excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que continúe una llamada a la API, la biblioteca Java de Stripe genera una excepción. Es una buena práctica detectar y gestionar las excepciones. Para detectar una excepción, usa la sintaxis `try`/`catch` de Java. Capta `StripeException` 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](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce como excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que continúe una llamada API, la biblioteca Node.js de Stripe puede realizar una excepción. Capturar y gestionar las excepciones es una práctica recomendada. Para habilitarlas y captarlas, haz lo siguiente: - Si realizas una llamada API en una función, a la definición de la función antepón la palabra clave `async`. - Precede la llamada API misma con la palabra clave `await`. - Envuelve la llamada API en un bloque `try`/`catch` Cuando captas una excepción, puedes [usar el atributo Type para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Usar valores de errores](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Usar valores de errores Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce a valores de errores. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Las llamadas a la API en la biblioteca Stripe Go devuelven tanto un valor de resultado como un valor de error. Usa varias asignaciones para capturar ambas. Si el valor de error no es `nil`, significa que un problema inmediato impidió que la llamada a la API continuara. Si el valor de error está relacionado con Stripe, puedes convertirlo en un objeto `stripe.Error`, que tiene campos que describen el problema. [Usa el campo Tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). En algunos casos, puedes forzar la propiedad `Err` a un tipo de error más específico con información adicional. | Técnica | Finalidad | Cuándo se necesita | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | [Captar excepciones](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada API cuando esta no puede continuar | Siempre | | [Supervisar webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre errores](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas anteriores y admitir otras técnicas | A veces | ## Captar excepciones Con esta biblioteca, no es necesario comprobar si hay respuestas HTTP que no sean 200. La biblioteca las traduce a excepciones. En el caso poco frecuente de que necesites datos HTTP, consulta [cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que continúe una llamada a la API, la biblioteca .NET de Stripe genera una excepción. Es una buena práctica detectar y gestionar las excepciones. Para capturar una excepción, use la sintaxis `try`/`catch` de .NET. Captura una `StripeException` y luego [usa su atributo Type para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); error_log("No error."); } catch(\Stripe\Exception\CardException $e) { error_log("A payment error occurred: {$e->getError()->message}. (request id: {$e->getRequestId()})"); } catch (\Stripe\Exception\InvalidRequestException $e) { error_log("An invalid request occurred. (request id: {$e->getRequestId()})"); // Add additional catch cases for other Stripe exception types as needed. // See all exception types at https://docs.stripe.com/api/errors/handling?lang=php } catch (\Stripe\Exception\ApiErrorException $e) { // All other Stripe API errors error_log("Status: " . $e->getHttpStatus() . ", Code: " . $e->getStripeCode() . ", Message: " . $e->getMessage() . ", Request ID: " . $e->getRequestId()); } catch (Exception $e) { error_log("Another problem occurred, maybe unrelated to Stripe."); } } ``` Después de configurar la gestión de excepciones, pruébala con varios datos, incluidas las [tarjetas de prueba](https://docs.stripe.com/testing.md), para simular diferentes resultados de pago. #### Error de activación - Solicitud no válida #### PHP ```php example_function([ // The required parameter currency is missing 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Esta es una tarjeta de prueba que siempre funciona correctamente cuando la usas en entornos de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` An invalid request occurred. ``` #### Error de activación - Error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedFraudulent', // Esta es una tarjeta de prueba que siempre produce un error de pago por cargo fraudulento. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` A payment error occurred: Your card was declined. ``` #### Error de activación - No hay error #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Esta es una tarjeta de prueba que siempre funciona correctamente cuando la usas en entornos de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` No error. ``` ## Supervisar webhooks Stripe te notifica sobre muchos tipos de problemas utilizando *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) 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](https://docs.stripe.com/webhooks/quickstart.md): 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 otros pasos: 1. Ve a [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Ve a [event[‘data’][‘object’]](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Ve a [event->data->object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtén el objeto afectado usando un `EventDataObjectDeserializer` y convierte el resultado al tipo de error adecuado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Ve a [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtén el objeto afectado convirtiendo los datos mediante el proceso de unmarshalling desde `event.Data.Raw`. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Para obtener el objeto afectado, convierte [stripeEvent.Data.Object](https://docs.stripe.com/api/events/object.md#event_object-data-object) al tipo adecuado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto Error. 1. [Usa el tipo de error para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); $payload = @file_get_contents('php://input'); $event = null; // Get the event object try { $event = \Stripe\Event::constructFrom( json_decode($payload, true) ); } catch(\UnexpectedValueException $e) { echo '⚠️ Webhook error while parsing basic request.'; http_response_code(400); exit(); } // Use the event type to find out what happened if ($event->type == 'payment_intent.payment_failed') { // Get the object affected $paymentIntent = $event->data->object; // Use stored information to get an error object $e = $paymentIntent->last_payment_error; // Use its type to choose a response switch ($e->type) { case \Stripe\Exception\CardException: error_log("A payment error occurred: {$e->getError()->message}"); break; case \Stripe\Exception\InvalidRequestException: error_log("An invalid request occurred."); if (isset($e->getError()->param)) { error_log("The parameter {$e->getError()->param} is invalid or missing."); } break; default: error_log("Another problem occurred, maybe unrelated to Stripe."); } } http_response_code(200); ``` Para probar cómo responde tu integración a los eventos de webhook, puedes [activar eventos de webhook de manera local](https://docs.stripe.com/webhooks.md#test-webhook). Después de completar los pasos de configuración en ese enlace, activa un pago fallido para ver el mensaje de error resultante. ```bash stripe trigger payment_intent.payment_failed ``` ```bash 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](https://docs.stripe.com/error-handling.md#error-types). Por ejemplo: 1. Recupera un Payment Intent específico. 1. Para verificar si se produjo un error de pago, determina si [last_payment_error](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error) está vacío. 1. De ser así, registra el error. Incluye el tipo de error y el objeto afectado. #### PHP ```php >'); $payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%}); $e = $payment_intent->last_payment_error; if (isset($e)) { error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error."); } ``` Estos son algunos objetos comunes que almacenan información sobre errores. | Objeto | Atributo | Valores | | ---------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Payment Intent](https://docs.stripe.com/api/payment_intents.md) | `last_payment_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Intent](https://docs.stripe.com/api/setup_intents.md) | `last_setup_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Factura](https://docs.stripe.com/api/invoices.md) | `last_finalization_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Attempt](https://docs.stripe.com/api/setup_attempts.md) | `setup_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Payout](https://docs.stripe.com/api/payouts.md) | `failure_code` | [Un código de error de pago](https://docs.stripe.com/api/payouts/failures.md) | | [Refund](https://docs.stripe.com/api/refunds.md) | `failure_reason` | [Un código de error de reembolso](https://docs.stripe.com/api/refunds/object.md#refund_object-failure_reason) | Para probar el código que usa información almacenada sobre errores, a menudo tendrás que simular transacciones fallidas. Por lo general, para hacerlo, usa [tarjetas de prueba](https://docs.stripe.com/testing.md) o números bancarios de prueba. Por ejemplo: - [Simula un pago rechazado](https://docs.stripe.com/testing.md#declined-payments) para crear errores de Charges, PaymentIntents y SetupIntents, entre otros. - [Simula un error de pago](https://docs.stripe.com/connect/testing.md#account-numbers). - [Simula un error de reembolso](https://docs.stripe.com/testing.md#refunds). ## Tipos de errores y respuestas En la biblioteca 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. | Nombre | Clase | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [Stripe::CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [Stripe::InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [Stripe::APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [Stripe::APIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [Stripe::AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [Stripe::IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [Stripe::PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [Stripe::RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [Stripe::SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [Stripe::CardError](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | ```ruby charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | `e.error.code == "card_declined"` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `Stripe::CardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `Stripe::InvalidRequestError` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `Stripe::APIConnectionError` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `Stripe::APIError` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `Stripe::AuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `Stripe::IdempotencyError` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `Stripe::PermissionError` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `Stripe::RateLimitError` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `Stripe::SignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. | En la biblioteca Python de Stripe, los objetos Error pertenecen a `stripe.StripeError` y sus subclases. Usa la documentación de cada clase para obtener consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [stripe.CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [stripe.InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [stripe.APIConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [stripe.APIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [stripe.AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [stripe.IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [stripe.PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [stripe.RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [stripe.SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [stripe. CardError](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | ```python charge = stripe.Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | `e.code == "card_declined"` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `stripe.CardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `stripe.InvalidRequestError` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace `e.doc_url` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `e.param` para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `stripe.APIConnectionError` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `stripe.APIError` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `stripe.AuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `stripe.IdempotencyError` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `stripe.PermissionError` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `stripe.RateLimitError` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `stripe.SignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. | En la biblioteca de Stripe PHP, cada tipo de error pertenece a su propia clase. Usa la documentación de cada clase para obtener consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [Stripe\Exception\InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [Stripe\Exception\ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [Stripe\Exception\ApiErrorException](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [Stripe\Exception\AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [Stripe\Exception\IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [Stripe\Exception\PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [Stripe\Exception\RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [Stripe\Exception\SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | ```php $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); $charge->outcome->type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | `$e->getError()->code == "card_declined"` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `Stripe\Exception\InvalidRequestException` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace `e->getError()->doc_url` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `e->getError()->param` para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `Stripe\Exception\ApiConnectionException` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `Stripe\Exception\APIException` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `Stripe\Exception\AuthenticationException` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `Stripe\Exception\IdempotencyException` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `Stripe\Exception\PermissionException` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `Stripe\Exception\RateLimitException` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `Stripe\Exception\SignatureVerificationException` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. | En la biblioteca de Stripe Java, cada tipo de error pertenece a su propia clase. Usa la documentación de cada clase para obtener consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [APIException](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [CardException](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `CardException` | | **Códigos** | ```java Charge charge = Charge.retrieve(ex.getStripeError() .getPaymentIntent() .getLatestCharge()); charge.getOutcome().getType() == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `CardException` | | **Códigos** | `e.getCode() == "card_declined"` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `CardException` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `InvalidRequestException` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace `e.getDocUrl()` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `e.getParam()` para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `APIConnectionException` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `APIException` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `AuthenticationException` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `IdempotencyException` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `PermissionException` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `RateLimitException` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `SignatureVerificationException` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. | En la biblioteca Stripe Node.js, cada objeto de error tiene un atributo `type`. Usa la documentación de cada tipo para obtener consejos sobre cómo responder. | Nombre | Tipo | Descripción | | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [StripeCardError](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [StripeInvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [StripeConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [StripeAPIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [StripeAuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [StripeIdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [StripePermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [StripeRateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [StripeSignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [StripeCardError](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `StripeCardError` | | **Códigos** | ```javascript const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge) charge.outcome.type === 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.payment_intent.charges.data[0].outcome.type === 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `StripeCardError` | | **Códigos** | `e.code === 'card_declined'` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `StripeCardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `StripeInvalidRequestError` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace `e.doc_url` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `e.param` para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `StripeAPIConnectionError` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `StripeAPIError` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `StripeAuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `StripeIdempotencyError` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `StripePermissionError` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `StripeRateLimitError` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `StripeSignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. | En la biblioteca Stripe Go, cada objeto de error tiene un atributo `Type`. Usa la documentación de cada tipo para obtener consejos sobre cómo responder. | Nombre | Tipo | Descripción | | ------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Error de pago | [stripe.ErrorTypeCard](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [stripe.ErrorTypeInvalidRequest](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API de una forma que no es válida en este momento. El motivo puede haber sido alguno de estos: - [Error de límite de frecuencia](https://docs.stripe.com/error-handling.md#rate-limiting) - [Error de autenticación](https://docs.stripe.com/error-handling.md#authentication-errors) - [Estado o parámetro no válido](https://docs.stripe.com/error-handling.md#invalid-parameters-or-state) | | Error de API | [stripe.ErrorTypeAPI](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de idempotencia | [stripe.ErrorTypeIdempotency](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | ## Errores de tarjetas Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [stripe. ErrorTypeCard](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Bloqueado por presunto fraude | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | ```go charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Rechazado por el emisor | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | `cardErr.Error.Code == stripe.ErrorCodeCardDeclined` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas Los errores de solicitudes no válidas pueden ocurrir por varios motivos. El más común es que la solicitud API tenga parámetros no válidos o que no esté permitida en el estado actual de tu integración. Usa el código de error (`stripeErr.Code`) y consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para encontrar una solución. Algunos códigos de errores exigen una respuesta especial: - `rate_limit` y `lock_timeout` reflejan [errores de límite de frecuencia](https://docs.stripe.com/error-handling.md#rate-limit-errors) - `secret_key_required` refleja un [error de autenticación](https://docs.stripe.com/error-handling.md#authentication-errors) - Otros códigos de error reflejan [estados o parámetros no válidos](https://docs.stripe.com/error-handling.md#other-invalid-request-errors) ### Errores de límite de frecuencia | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ### Errores de autenticación | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ### Estado o parámetro inválido | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace `stripeErr.DocURL` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `stripeErr.Param` para determinar de cuál se trata. | ## Errores de API | | | | | **Tipo** | `stripe.ErrorTypeAPI` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de idempotencia | | | | | **Tipo** | `stripe.ErrorTypeIdempotency` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | En la biblioteca .NET de Stripe, cada objeto de error tiene un atributo `type`. Usa la documentación de cada tipo para obtener consejos sobre cómo responder. | Nombre | Tipo | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [card_error](https://docs.stripe.com/error-handling.md#payment-errors) | Se produjo un error durante un pago, debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [invalid_request_error](https://docs.stripe.com/error-handling.md#invalid-request-errors) | Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida. | | Error de conexión | [api_connection_error](https://docs.stripe.com/error-handling.md#connection-errors) | Hubo un problema de red entre tu servidor y Stripe. | | Error de API | [api_error](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [authentication_error](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [idempotency_error](https://docs.stripe.com/error-handling.md#idempotency-errors) | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | Error de permiso | [permission_error](https://docs.stripe.com/error-handling.md#permission-errors) | La clave API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [rate_limit_error](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [signature_verification_error](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | ## Errores de pago Todo lo dispuesto en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo [card_error](https://docs.stripe.com/error-handling.md#card-error). Pero, de hecho, pueden representar un problema con cualquier pago, independientemente del método de pago. 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: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el [PaymentIntent involucrado](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último objeto Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones: - [Cómo simular pagos bloqueados por riesgo de fraude](https://docs.stripe.com/testing.md#fraud-prevention) - [Cómo simular pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error de activación - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error de activación - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error de activación - Tarjeta vencida #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla por vencimiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error de activación - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `card_error` | | **Códigos** | ```dotnet var chargeService = new ChargeService(); var options = new ChargeGetOptions(); var charge = chargeService.Get(e.StripeError.PaymentIntent.LatestChargeId, options); charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.StripeError.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), bloqueó el pago | | **Soluciones** | Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago. Para bloquear menos pagos legítimos, intenta lo siguiente: - [Optimiza tu integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Para elementos de formularios optimizados prediseñados, usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md). Los clientes de *Radar para Equipos de Fraude* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) tienen estas opciones adicionales: - Para eximir un pago en particular, agrégalo a tu lista de permitidos. (Radar for Fraud Teams) - Para modificar la tolerancia al riesgo, ajusta la [configuración de riesgo](https://docs.stripe.com/radar/risk-settings.md). (Radar para equipos de fraude) - Para modificar los criterios de bloqueo de pagos, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar para equipos de fraude) Puedes probar los ajustes de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `card_error` | | **Códigos** | `e.StripeError.Code == "card_declined"` | | **Problema** | El emisor de la tarjeta rechazó el pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de pago rechazado](https://docs.stripe.com/declines/codes.md) para ver las respuestas adecuadas para cada código. También puedes - [Sigue las recomendaciones para reducir los rechazos de los emisores](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para los elementos de formulario prediseñados que implementan esas recomendaciones. Prueba cómo tu integración gestiona los rechazos con [tarjetas de prueba que simulan pagos correctos y pagos rechazados](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `card_error` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la [documentación sobre códigos de error](https://docs.stripe.com/error-codes.md) para ver las respuestas adecuadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `invalid_request_error` | | **Problema** | Hiciste una llamada 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. - Consulta la [documentación sobre códigos de errores](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes seguir el enlace para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa para determinar de cuál se trata. | ## Errores de conexión | | | | | **Tipo** | `api_connection_error` | | **Problema** | Hubo un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó. Para saber si se realizó correctamente, puedes - Recupera el objeto relevante desde Stripe y comprueba su estado. - Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló. Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). 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 una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta [Gestión de errores de bajo nivel](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). Luego, Stripe generará las claves de idempotencia y, cuando sea seguro hacerlo, repetirá 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 | | | | | **Tipo** | `api_error` | | **Problema** | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | **Soluciones** | Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. Recurre a los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema. Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta [esta página con información detallada sobre errores de servidores](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `authentication_error` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Usa la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [rotado o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `idempotency_error` | | **Problema** | Utilizaste una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para algo inesperado, como repetir una solicitud con parámetros distintos. | | **Soluciones** | - Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas. - Usa claves de idempotencia que no superen los 255 caracteres. | ## Errores de permisos | | | | | **Tipo** | `permission_error` | | **Problema** | La clave API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tiene acceso. - No realices acciones en el Dashboard si iniciaste sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tiene permiso para ella. | ## Errores de límite de frecuencia | | | | | **Tipo** | `rate_limit_error` | | **Problema** | 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ímites de frecuencia](https://docs.stripe.com/rate-limits.md) para obtener 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `signature_verification_error` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) del *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no se pudo verificar que un evento de webhook sea auténtico. | | **Soluciones** | Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado `400 Bad Request`. 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](https://docs.stripe.com/webhooks.md#verify-events). Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API. |