Documentation de l'API JavaScript

Méthodes d’API

• StripeTerminal.create()
• discoverReaders()
• connectReader()
• disconnectReader()
• getConnectionStatus()
• getPaymentStatus()
• clearCachedCredentials()
• collectPaymentMethod()
• cancelCollectPaymentMethod()
• processPayment()
• collectSetupIntentPaymentMethod()
• cancelCollectSetupIntentPaymentMethod()
• confirmSetupIntent()
• readReusableCard()
• cancelReadReusableCard()
• setReaderDisplay()
• clearReaderDisplay()
• setSimulatorConfiguration()
• getSimulatorConfiguration()
• collectRefundPaymentMethod()
• processRefund()
• cancelCollectRefundPaymentMethod()
• collectInputs()
• cancelCollectInputs()

StripeTerminal.create([options])

Crée une instance de StripeTerminal avec les options données :

Configuration du comportement du lecteur

Aujourd’hui, il n’existe qu’une seule option de configuration du comportement :

discoverReaders([options])

Commence à découvrir les lecteurs avec les options données :

Retourne une Promise qui résulte en un objet avec les champs suivants :

• discoveredReaders : une liste d’objets Reader de simulation, si la commande a réussi.
• error: Une erreur, si la commande a échoué.

connectReader(reader, connectOptions)

Tentatives de connexion au lecteur donné avec les options données :

Retourne une Promise qui résulte en un objet avec les champs suivants :

• reader : L’objet Reader connecté, si la commande a abouti.
• error: Une erreur, si la commande a échoué.

disconnectReader()

Se déconnecte du lecteur connecté.

getConnectionStatus()

Retourne l’état de connexion en cours.

ConnectionStatus peut être à l’état connecting, connected ou not_connected.

getPaymentStatus()

Retourne l’état du paiement du lecteur.

PaymentStatus peut être à l’état not_ready, ready, waiting_for_input ou processing.

clearCachedCredentials()

Efface le ConnectionToken en cours, et tout autre identifiant mis en cache.

Utilisez cette méthode pour passer d’un compte à l’autre dans votre application (par exemple, pour passer entre les clés API Stripe en mode production et en mode test sur votre back-end). Pour passer d’un compte à l’autre, effectuez ces étapes :

1. Si un lecteur est connecté, appelez disconnectReader.
2. Configurez votre gestionnaire onFetchConnectionToken pour retourner les tokens de connexion pour le nouveau compte.
3. Appelez clearCachedCredentials.
4. Reconnectez-vous à un lecteur. Le SDK demande un nouveau token de connexion à votre gestionnaire onFetchConnectionToken.

collectPaymentMethod(request, options)

Commence à collecter un moyen de paiement pour un PaymentIntent. Ce moyen nécessite un paramètre requis, request :

• request : le champ clientSecret d’un objet PaymentIntent créé sur votre back-end. Découvrez comment créer un PaymentIntent et transmettre sa clé secrète du client.
• options : un objet contenant des paramètres de paiement supplémentaires.

{
  update_payment_intent: boolean,
  payment_intent_id: string,
  enable_customer_cancellation: boolean,
  skip_tipping: boolean,
  tipping: object,
  allow_redisplay: string,
  moto: boolean,
}

L’option suivante est disponible pour l’objet tipping :

{
  eligible_amount: number,
}

Retourne une Promise qui résulte en un objet avec les champs suivants :

• paymentIntent : l’objet PaymentIntent mis à jour, si la commande a abouti.
• error: Une erreur, si la commande a échoué.

Pour obtenir plus d’informations sur l’encaissement de paiements, veuillez consulter notre guide sur l’encaissement des paiements.

cancelCollectPaymentMethod()

Annule une commande collectPaymentMethod en suspens.

Retourne une Promise qui résulte en un objet vide une fois que la commande a été correctement annulée. Si l’annulation échoue, la Promise résulte en un objet avec une erreur.

processPayment(paymentIntent, options)

Traite un paiement après qu’un moyen de paiement a été collecté.

Cette méthode nécessite un paramètre obligatoire, paymentIntent :

• paymentIntent : un objet PaymentIntent obtenu à partir d’un appel réussi à collectPaymentMethod.
• options : un objet contenant des paramètres de paiement supplémentaires.

{
  return_url: string,
}

Retourne une Promise qui résulte en un objet avec les champs suivants :

• paymentIntent : l’objet PaymentIntent confirmé, si la commande a abouti.
• error : une erreur, si la commande a échoué. Pour obtenir plus d’informations, veuillez consulter la section Gestion des échecs de traitement.

collectSetupIntentPaymentMethod(clientSecret, allowRedisplay, config)

Commence à collecter un moyen de paiement pour une réutilisation en ligne en lien avec un SetupIntent.

Le moyen nécessite deux paramètres requis :

• clientSecret : le champ clientSecret d’un objet SetupIntent créé sur votre back-end.

• allowRedisplay : valeur d’énumération indiquant si les futurs tunnels de paiement peuvent afficher ce moyen de paiement au client.

• config : un objet facultatif contenant la configuration de la collection.

Retourne une Promise qui résulte en un objet avec les champs suivants :

• setupIntent : l’objet SetupIntent mis à jour, si la commande a réussi.
• error: Une erreur, si la commande a échoué.

Pour en savoir plus sur l’enregistrement des moyens de paiement, consultez notre guide Enregistrement des informations de paiement pour les paiements en ligne.

cancelCollectSetupIntentPaymentMethod()

Annule une commande collectSetupIntentPaymentMethod en suspens.

Retourne une Promise qui résulte en un objet vide une fois que la commande a été correctement annulée. Si l’annulation échoue, la Promise résulte en un objet avec une erreur.

confirmSetupIntent(setupIntent)

Confirme un SetupIntent après qu’un moyen de paiement a été collecté.

Cette méthode nécessite un seul paramètre, un objet SetupIntent obtenu à partir d’un appel réussi à collectSetupIntentPaymentMethod.

Retourne une Promise qui résulte en un objet avec les champs suivants :

• setupIntent : l’objet SetupIntent confirmé, si la commande a réussi.
• error: Une erreur, si la commande a échoué.

readReusableCard()

Lit une carte bancaire pour une réutilisation en ligne.

Les paiements en ligne initiés depuis Terminal ne bénéficient pas des tarifications plus basses et du transfert de responsabilité donné aux paiements Terminal standard. La plupart des intégrations n’ont pas besoin d’utiliser readReusableCard. Pour encaisser uniquement le paiement par TPE d’un client, utilisez le flux standard.

Retourne une Promise qui résulte en un objet avec les champs suivants :

• payment_method : l’objet PaymentMethod, si la commande a abouti.
• error: Une erreur, si la commande a échoué.

cancelReadReusableCard()

Annule une commande readReusableCard en suspens.

Retourne une Promise qui résulte en un objet vide une fois que la commande a été correctement annulée. Si l’annulation échoue, la Promise résulte en un objet avec une erreur.

setReaderDisplay(displayInfo)

Met à jour l’affichage du lecteur avec les informations du panier.

Cette méthode nécessite un objet DisplayInfo comme entrée.

{
  type: 'cart',
  cart: {
    line_items: [
      {
        description: string,
        amount: number,
        quantity: number,
      },
    ],
    tax: number,
    total: number,
    currency: string,
  }
}

Renvoie une Promise qui résulte en un objet vide si la commande aboutit. Si la commande échoue, la Promise résulte en un objet avec une erreur.

clearReaderDisplay()

Si le lecteur affiche les informations du panier définis sur setReaderDisplay, cette méthode efface l’écran de présentation.

Renvoie une Promise qui résulte en un objet vide si la commande aboutit. Si la commande échoue, la Promise résulte en un objet avec une erreur.

setSimulatorConfiguration(configuration)

Définit l’objet de configuration pour le lecteur de carte de simulation.

Cette méthode prend uniquement effet lorsque l’objet est connecté au lecteur de simulation, sinon elle n’effectue aucune action.

Le lecteur de simulation suivra la configuration spécifiée uniquement jusqu’à ce que processPayment soit terminé. À ce stade, le lecteur de simulation revient à son comportement par défaut.

Notez que cette méthode remplace tout objet de configuration actif actuellement. Pour ajouter des paires de clé-valeur spécifiques, assurez-vous d’utiliser une combinaison de cette méthode et de getSimulatorConfiguration.

Les options de configuration disponibles sont :

getSimulatorConfiguration()

Retourne l’objet de configuration actif actuellement.

Le SDK JavaScript Stripe Terminal peut remplacer cette valeur si nécessaire, y compris (mais sans s’y limiter) la redéfinition de la valeur après que processPayment est terminé, et la suppression des paires de clé-valeur inconnues.

collectRefundPaymentMethod(charge_id, amount, currency, options, config)

Commence à collecter un moyen de paiement pour être remboursé. La méthode nécessite deux paramètres requis :

• charge_id, l’ID du paiement qui sera remboursé.
• amount : un nombre qui représente le montant, en centimes, qui sera remboursé du paiement. Ce nombre peut être inférieur ou égal au montant facturé dans le paiement d’origine.
• currency : code ISO pour la devise composé de trois lettres en minuscules. Doit être une devise prise en charge.
• options : un objet facultatif contenant des paramètres de remboursement supplémentaires.

• config : un objet facultatif contenant la configuration de la collection.

Retourne une Promise qui résulte en :

• un objet vide si la collection du moyen de paiement a abouti, ou
• un objet avec un champ error si une erreur est survenue lors de la collecte du moyen de paiement lié au remboursement.

processRefund()

Traite un remboursement en cours. Ce moyen peut uniquement être appelé après que collectRefundPaymentMethod soit correctement retourné.

Retourne une Promise qui résulte en :

• un objet refund si le remboursement a réussi, ou
• un objet avec un champ error s’il y a eu une erreur pendant le traitement du remboursement.

cancelCollectRefundPaymentMethod()

Annule une commande collectRefundPaymentMethod en suspens.

Retourne une Promise qui résulte en un objet vide si l’annulation a abouti. Si l’annulation échoue, la Promise résulte en un objet avec un champ error.

collectInputs(collectInputsParameters)

Commencez à afficher des formulaires et à collecter des informations auprès des clients à l’aide de Collect Inputs.

Cette méthode nécessite la saisie d’un objet ICollectInputsParameters.

Renvoie une Promise qui résulte en la collecte des informations si la commande aboutit. Si la commande échoue, la Promise résulte en un objet avec une erreur.

cancelCollectInputs()

Annule une commande collectInputs en suspens.

Renvoie une Promise qui résulte en un objet vide si l’annulation aboutit. Si la commande échoue, la Promise résulte en un objet avec une erreur.

Erreurs

Les erreurs retournées par le SDK JavaScript incluent un code d’erreur, ainsi qu’un message pouvant être lu par l’utilisateur.

Pour les méthodes impliquant un PaymentIntent comme processPayment, l’erreur peut également inclure un objet payment_intent.

Codes d’erreur

Log des modifications

Si vous utilisez une version antérieure du SDK JavaScript (antérieure au 7 juin 2019), procédez à une mise à niveau vers la dernière version en changeant l’URL du script inclus dans votre intégration.

<script src="https://js.stripe.com/terminal/v1/"></script>

Pour en savoir plus sur la migration à partir de la version bêta de Stripe Terminal, consultez le Guide de migration vers Terminal Beta.

v1

• confirmPaymentIntent renommé en processPayment.
• Valeurs pour PaymentStatus renommées. PaymentStatus peut être à l’état not_ready, ready, waiting_for_input ou processing.
• Informations de carte supprimées des réponses à collectPaymentMethod, précédemment disponibles dans response.paymentIntent.payment_method.card_payment.
• Les informations de reçu sont désormais situées dans le hachage payment_intent.charges[0].payment_method_details.card_present.
• Modification de l’API permettant de découvrir un lecteur de simulation en discoverReaders({ simulated: true }).
• readSource renommé en readReusableCard. Un appel fructueux à readReusableCard renvoie un PaymentMethod au lieu d’une source. Les moyens de paiement doivent être utilisés avec des PaymentIntents. Pour en savoir plus, consultez l’aperçu de l’API Payment Methods.
• La réponse connectReader a été modifiée en { reader: Reader }. L’objet Connection de wrapper a été supprimé.
• Suppression des méthodes startReaderDiscovery et stopReaderDiscovery. Pour découvrir des lecteurs de manière répétée, vous pouvez utiliser la méthode setInterval JavaScript.
• clearConnectionToken renommé en clearCachedCredentials.