Gestiona errores y resultados desconocidos

Q: ¿Puedo volver a intentarlo después de cancelled?

Sí. cancelled significa que el usuario canceló en la pantalla de Apple y no se produjo ningún pago. Inicia un pago nuevo cuando el cliente esté listo.

Q: ¿Por qué recibo notPrepared después de un fallo de prepare?

Cuando prepare lanza invalidToken o tokenExpired , el SDK no guarda ningún token. Obtén un token nuevo de tu servidor, envía solo el campo token y llama otra vez a prepare .

Todas las llamadas lanzan TapToPayError. La mayoría de los errores significan que no se produjo ningún pago. Un error, outcomeUnknown, significa que la tarjeta puede estar cobrada. Gestiónalo como se describe en Resultado desconocido.

Gestiona los errores en el código

do {
  let result = try await TapToPay.acceptPayment(
    amount: amountInCents, orderId: orderId, callbackUrl: webhookUrl)
  show(result)
} catch let error as TapToPayError {
  switch error {
  case .outcomeUnknown(let orderId):
    showPending(orderId) // No vuelvas a intentarlo.
  case .cancelled:
    break // No se produjo ningún pago.
  case .tokenExpired, .notPrepared, .invalidToken:
    await renewTokenAndPrepare()
  case .locationDenied:
    showLocationSettingsHint()
  case .setupIncomplete(let fix):
    log(fix) // La app no está configurada. Corrige la app como indica fix.
    hideTapToPay()
  case .passcodeRequired:
    showSetPasscodeHint() // Ajustes > Face ID y código. Luego vuelve a intentarlo.
  case .termsDeclined:
    showTermsRequired()
  case .osUpdateRequired:
    showUpdateIOSHint()
  case .paymentFailed(.readerSetupFailed(let reason)):
    log(reason) // No se produjo ningún pago. Envía reason al soporte de MONEI.
    showRetry()
  case .paymentFailed(let code):
    showFailure(code)
  default:
    showError(error)
  }
} catch {
  showError(error)
}

Un switch sin caso default necesita @unknown default. Consulta Sentencias switch.

Errores

Error	Lo lanza	Significado	Qué hacer
`notSupported`	Todas las llamadas	El dispositivo o la versión de iOS no es compatible con Tap to Pay en el iPhone.	Oculta Tap to Pay en el iPhone.
`setupIncomplete(fix:)`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	Desde el SDK 0.5.0. La app no está configurada para Tap to Pay en el iPhone: falta `NSLocationWhenInUseUsageDescription`, el entitlement o `PRODUCT_TEAM_IDENTIFIER`, o es incorrecto. No se produjo ningún pago. `fix` te dice qué debes cambiar. No lo analices.	Corrige la app como indica `fix` y publícala otra vez. La app no puede corregirlo mientras se ejecuta. Oculta Tap to Pay en el iPhone, o muestra que la app no está configurada.
`passcodeRequired`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	Desde el SDK 0.7.0. El iPhone no tiene código de acceso. No se inició la configuración del lector. No se produjo ningún pago. `prepare` guarda el token.	Pide al usuario que configure un código de acceso en Ajustes > Face ID y código (o Touch ID y código). En un iPhone que gestiona una solución de gestión de dispositivos (MDM), el administrador añade una política de código de acceso. El SDK lo comprueba otra vez en cada llamada: cuando el usuario configura un código, la siguiente llamada funciona sin un nuevo `prepare`.
`locationDenied`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	El usuario no permitió el acceso a la ubicación. Antes del SDK 0.5.0, también: `Info.plist` no tiene `NSLocationWhenInUseUsageDescription` (desde la 0.5.0 esto da `setupIncomplete`).	Pide al usuario que permita el acceso a la ubicación en Ajustes y vuelve a intentarlo.
`termsDeclined`	`acceptPayment`, `linkAccount`	El usuario no aceptó los términos de Apple, o la vinculación de la cuenta falló.	Indica al usuario que los términos son necesarios. El siguiente `linkAccount` o `acceptPayment` muestra otra vez los términos.
`invalidArgument`	`acceptPayment`	`amount` es 0 o menos, o `orderId` está vacío.	Corrige el valor.
`tokenExpired`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	El token caducó.	Obtén un token nuevo de tu servidor. Llama a `prepare`. Después, vuelve a intentarlo.
`invalidToken`	`prepare`	El SDK no puede leer el token.	Envía solo el campo `token`. Obtén un token nuevo y llama a `prepare`. Hasta entonces, las otras llamadas lanzan `notPrepared`.
`notPrepared`	`acceptPayment`, `isAccountLinked`, `linkAccount`	No hay ningún token válido guardado.	Llama primero a `prepare`.
`busy`	`acceptPayment`, `isAccountLinked`, `linkAccount`	Hay en curso un pago, una comprobación de los términos (`isAccountLinked`) o una vinculación (`linkAccount`).	Espera a que termine. No inicies un segundo pago mientras se ejecuta uno. Si se ejecuta una comprobación de los términos, espera a que termine y después llama a `acceptPayment`.
`cancelled`	`acceptPayment`	El usuario canceló en la pantalla de Apple. No se produjo ningún pago.	Inicia un pago nuevo cuando el cliente esté listo.
`sdkUpgradeRequired`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	MONEI bloqueó esta versión del SDK. Todas estas llamadas fallan con este error.	Actualiza a una versión más reciente del SDK y publica tu app.
`osUpdateRequired`	`prepare`, `acceptPayment`, `isAccountLinked`, `linkAccount`	Desde el SDK 0.4.0. Apple indica que esta versión de iOS no es compatible con Tap to Pay en el iPhone. No se produjo ningún pago.	Pide al usuario que actualice iOS a la última versión. Después, vuelve a intentarlo.
`outcomeUnknown(orderId:)`	`acceptPayment`	El SDK no puede saber si el pago llegó a MONEI. La tarjeta puede estar cobrada.	No vuelvas a intentarlo. Espera el webhook firmado, o busca el `orderId` en MONEI. Consulta Resultado desconocido.
`paymentFailed(code:)`	Todas las llamadas	El pago o la configuración falló.	Consulta Códigos de fallo.

Códigos de fallo

paymentFailed(code:) tiene uno de estos valores de TapToPayErrorCode:

Código	Significado	Qué hacer
`cardDeclined`	La tarjeta se rechazó durante la lectura. No se produjo ningún pago.	Pide otra tarjeta.
`readerNotReady`	La sesión del lector no estaba lista o caducó.	Vuelve a intentarlo. El SDK prepara otra vez el lector en la siguiente llamada.
`locationTimeout`	El dispositivo no obtuvo una ubicación en 15 segundos.	Comprueba que la Localización está activada. Después, vuelve a intentarlo.
`readerSetupFailed(reason:)`	`prepare`, `acceptPayment`, `isAccountLinked` o `linkAccount` no pudo configurar el lector antes de que empezara un pago. No se produjo ningún pago. `reason` es un texto corto para tus registros y para el soporte de MONEI, por ejemplo `ENABLE_ERROR PaymentCardReaderError.notAllowed`. No dependas de su formato.	Vuelve a intentarlo. Si el error continúa, envía `reason` al soporte de MONEI.
`unknown`	El pago no empezó. No se produjo ningún pago.	Vuelve a intentarlo. Si el error continúa, contacta con MONEI.

Los pagos rechazados no son errores

Un PaymentResult con el estado .declined no es un error. La tarjeta se leyó y el emisor rechazó el pago. El pago está en MONEI con su paymentId. El motivo está en statusMessage. Consulta Muestra el motivo del rechazo. Pide otra tarjeta al cliente e inicia un pago nuevo.

Resultado desconocido

outcomeUnknown(orderId:) significa que el SDK no puede saber si el pago llegó a MONEI. La tarjeta puede estar cobrada.

Causas:

Un error de conexión o del servidor en cualquier paso del pago.
Un error de lectura de la tarjeta, un error al introducir el PIN, o una sesión del lector perdida durante el pago.
Una respuesta que no es una aprobación clara ni un rechazo claro. Esto también puede ocurrir cuando la tarjeta se rechaza.
Una tarea cancelada.

Algunas de estas causas ocurren antes de cobrar la tarjeta, pero el SDK no puede saber cuáles.

No vuelvas a intentarlo

No vuelvas a intentar el pago, y no cobres otra vez con un orderId nuevo. El cliente puede pagar dos veces.

Muestra un estado pendiente con el orderId.
Espera el webhook firmado de este orderId.
Si no llega ningún webhook, busca el orderId en MONEI:
- En MONEI Dashboard, abre Pagos y filtra por ID de pedido.
- Con la API GraphQL, usa la consulta charges con filter.orderId:
```
query {
  charges(filter: {orderId: {eq: "order-1042"}}) {
    items {
      id
      status
      amount
    }
  }
}
```
Si no aparece ningún pago, esto no demuestra que la tarjeta no se cobró. Contacta con el soporte de MONEI con el orderId antes de cobrar otra vez al cliente.

Preguntas frecuentes

¿Puedo volver a intentarlo después de cancelled?

Sí. cancelled significa que el usuario canceló en la pantalla de Apple y no se produjo ningún pago. Inicia un pago nuevo cuando el cliente esté listo.

¿Por qué recibo notPrepared después de un fallo de prepare?

Cuando prepare lanza invalidToken o tokenExpired, el SDK no guarda ningún token. Obtén un token nuevo de tu servidor, envía solo el campo token y llama otra vez a prepare.

¿Qué significa sdkUpgradeRequired?

MONEI bloqueó la versión del SDK de tu app. Todas las llamadas que necesitan el lector fallan con este error. Actualiza a una versión más reciente del SDK y publica una versión nueva de tu app. Consulta Versiones y compatibilidad.

¿Por qué un error de lectura de la tarjeta es un resultado desconocido?

Algunos errores del lector pueden ocurrir después de que el SDK envió el pago a MONEI. El SDK no puede distinguir estos errores de los que ocurren antes, así que lanza outcomeUnknown para todos. Así se evita un segundo cobro al cliente por error.

¿Te ha resultado útil esta página?

Gestiona los errores en el código​

Errores​

Códigos de fallo​

Los pagos rechazados no son errores​

Resultado desconocido​

Preguntas frecuentes​

¿Puedo volver a intentarlo después de cancelled?​

¿Por qué recibo notPrepared después de un fallo de prepare?​

¿Qué significa sdkUpgradeRequired?​

¿Por qué un error de lectura de la tarjeta es un resultado desconocido?​