Passer des commandes de matériel

Commandez des lecteurs précertifiés compatibles avec Stripe Terminal depuis votre Dashboard ou à l’aide de l’API Stripe (bêta). Achetez des lecteurs directement auprès de Stripe afin qu’ils soient dotés des applications de paiement et des clés de chiffrement sécurisé de Stripe.

Pour commencer, accédez à la section Lecteurs de votre Dashboard. Cliquez sur Acheter pour afficher les produits disponibles.

Produits proposés

Premièrement, commandez un lecteur et une carte bancaire de test afin de tester l’ensemble de votre intégration avec du matériel physique. Une fois votre intégration prête à l’emploi, commandez autant de lecteurs que vous souhaitez.

Vous ne savez pas quel lecteur choisir ? Consultez l’article Concevoir une intégration pour sélectionner le lecteur adapté à votre intégration.

Vous pouvez commander une quantité maximale de 10000 par article dans une seule et même commande. Si vous souhaitez bénéficier de ristournes sur volume, prenez contact avec nos équipes.

Tarifs

Le tarif de chaque lecteur varie selon les pays. Vous pouvez consulter les tarifs actuels dans le Dashboard.

	Lecteur M2 de Stripe	BBPOS WisePOS E	BBPOS WisePad 3	Lecteur Stripe S700
Australie	–	329 AUD	89 AUD	499 AUD
Canada	–	299 CAD	79 CAD	449 CAD
Autriche France Allemagne Irlande Belgique Espagne Pays-Bas Luxembourg Finlande Portugal Italie	–	199 EUR	59 EUR	299 EUR
République tchèque	–	4990 CZK	1490 CZK	7 250 CZK
Malaisie	–	999 MYR	279 MYR	1 499 MYR
Nouvelle-Zélande	–	349 NZD	99 NZ	549 NZD
Singapour	–	299 SGD	89 SGD	449 SGD
Royaume-Uni	–	179 GBP	49 GBP	279 GBP
Switzerland	–	199 CHF	59 CHF	329 CHF
Norway	–	1990 NOK	590 NOK	3 590 NOK
Danemark	–	1499 DKK	449 DKK	2 400 DKK
Suède	–	2195 SEK	645 SEK	3 490 SEK
États-Unis	59 USD	249 USD	–	349 USD
	Acheter US only	Acheter	Acheter Non-US	Acheter

Suivre et annuler des commandes

Après avoir passé votre commande, consultez son état dans le Dashboard :

Retours en libre-service

Les retours en libre-service concernent les commandes passées et expédiées dans des pays spécifiques (voir la liste ci-dessous). Pour toutes les autres commandes, consultez les informations sur les retours dans les pays où le libre-service n’est pas pris en charge.

Si vous avez passé commande depuis le Dashboard Stripe à partir d’un pays où le libre-service est pris en charge et souhaitez retourner tout ou partie des articles de votre commande, les utilisateurs disposant des autorisations requises peuvent effectuer le processus de retour dans le Dashboard Stripe. Nous remboursons les articles qui nous sont retournés dans leur emballage d’origine (avec tous les accessoires) dans un délai de 30 jours suivant la date d’achat. Pour les retours au-delà de ce délai, veuillez contacter le service d’assistance Stripe.

Une fois le processus de retour effectué dans le Dashboard, une étiquette de retour est générée. Après avoir créé l’étiquette de retour, vous pouvez déposer votre colis chez un transporteur local.

Nous procédons au remboursement à la réception du colis dans notre centre de distribution. En cas de paiement par carte bancaire, le remboursement peut prendre jusqu’à 10 jours avant d’apparaître sur le compte bancaire du client.

Cliquez sur le bouton Retourner les articles

Pour effectuer un retour depuis le Dashboard, accédez à vos commandes de matériel et sélectionnez la commande que vous souhaitez retourner. Après avoir sélectionné la commande, cliquez sur Retourner les articles pour lancer le processus. Le bouton Retourner les articles est disponible sur la page des détails de la commande Terminal si la commande de matériel présente l’état Shipped ou Delivered.

Confirmation du nombre d'unités à retourner

Lorsque la fenêtre contextuelle s’ouvre, sélectionnez le nombre d’articles que vous souhaitez retourner pour chaque produit de la commande (si vous avez plus d’un article). Nous afficherons uniquement le nombre d’articles pouvant être retournés. Ainsi, si vous avez déjà acheté trois articles et en avez retourné un, vous ne pourrez sélectionner que deux unités à retourner.

Sélection d'un motif de retour

Ensuite, sélectionnez un motif de retour dans le menu déroulant.

• Articles arrivés défectueux ou cassés : sélectionnez cette option si l’un des articles reçus était endommagé ou défectueux.
• J’ai commandé trop d’appareils : sélectionnez cette option si vous avez commandé un trop grand nombre d’appareils.
• La configuration de l’appareil est trop compliquée : sélectionnez cette option si la mise en route de Stripe Terminal était trop complexe ou si le produit ne répondait pas à vos attentes.
• Autre : sélectionnez cette option si aucune des options ci-dessus ne correspond à votre cas d’usage. Vous devez préciser un motif.

Confirmation et export de l'étiquette d'expédition

Vérifiez l’exactitude des informations, puis sélectionnez Effectuer un retour. Une fois l’article sélectionné, l’option permettant de télécharger l’étiquette d’expédition s’affiche. Vous pouvez sélectionner Afficher les adresses UPS pour trouver le point de dépôt le plus proche.

Retours dans les pays où le libre-service n’est pas pris en charge

Pour retourner un appareil qui ne propose pas le retour en libre-service, contactez le service d’assistance. Ouvrez le Dashboard, accédez à votre commande et cliquez sur Contacter le service d’assistance afin de nous envoyer automatiquement les détails de votre commande. Nous pouvons rembourser les articles qui nous sont retournés dans leur emballage d’origine (accompagnés de tous leurs accessoires) dans un délai de 30 jours suivant la date d’achat.

Expédition

Stripe collabore avec un partenaire de distribution pour traiter les commandes Terminal. Selon le pays de destination, vous pouvez choisir entre un envoi standard, un envoi express ou un envoi prioritaire. Le matériel doit être expédié vers des adresses physiques (et non vers des boîtes postales).

Si vous êtes une plateforme Connect qui utilise Terminal, vous pouvez expédier des lecteurs directement à vos comptes connectés en précisant l’adresse de destination au moment du paiement.

Rôles et autorisations des utilisateurs

Le tableau suivant indique quels rôles d’utilisateurs peuvent passer des commandes pour leur compte dans le Dashboard :

Utiliser l’API Hardware Orders Beta

Si vous le souhaitez, vous pouvez utiliser l’API Hardware Orders. Elle vous permet d’acheter des lecteurs et accessoires Terminal de manière programmatique et de les envoyer directement à vos utilisateurs. Les commandes sont traitées par les partenaires de distribution de Stripe. Vous n’avez donc pas de logistique complexe à gérer et pouvez vous concentrer sur le développement de votre activité de paiement par TPE.

• Créer un outil interne permettant à vos employés (des responsables de magasin par exemple) de commander du matériel
• Créez un système de commande en ligne permettant à vos clients de commander des lecteurs Terminal et des accessoires

Pour créer une commande de matériel à l’aide de l’API, suivez les étapes ci-dessous :

1. Récupérer les unités de gestion des stocks disponibles
2. Récupérer les moyens de livraison disponibles
3. (Facultatif) Prévisualiser la commande
4. Créer la commande

Récupérer des unités de gestion des stocks

Pour créer une page produit efficace pour vos utilisateurs, votre intégration doit demander les articles disponibles à Stripe. Chaque article est représenté par une unité de gestion des stocks et comprend des informations sur le produit en question, dont le token et le tarif.

Each SKU is associated with a country: a reader available in the US has a different SKU from the same reader that’s available in Canada. To retrieve SKUs, you must specify the country parameter when making a request to the Hardware Order SKUs endpoint:

curl https://api.stripe.com/v1/terminal/hardware_skus?country=US \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4"

Each SKU is also associated with a Hardware Product. Products represent different categories of devices. If you’re building an e-commerce ordering system for your customers, make sure you only show the SKUs for the products that apply for your Terminal integration. For example, if your Terminal integration only uses the BBPOS WisePOS E, don’t make the BBPOS Chipper 2X BT reader available for purchase. To retrieve all BBPOS WisePOS E SKUs, you can specify the optional product parameter when making a request to the Hardware Order SKUs endpoint:

curl 'https://api.stripe.com/v1/terminal/hardware_skus?country=US&product=
{{TERMINAL_HARDWARE_PRODUCT_ID}}
' \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4"

Disponibilité des unités de gestion des stocks

Les unités de gestion des stocks et les produits peuvent devenir obsolètes lorsque nous les remplaçons par de nouveaux composants matériels. Pour vous aider à gérer l’obsolescence programmée, consultez l’état de l’unité de gestion des stocks et des produits, qui indique lesquels sont available ou unavailable. Vous ne pouvez pas créer de commande si l’état de l’unité de gestion des stocks est unavailable.

En outre, chaque SKU et produit propose un champ unavailable_after facultatif qui indique quand il risque de devenir unavailable. Étant donné que la disponibilité de ces objets change au fil du temps, nous recommandons d’utiliser une approche permettant de les interroger de manière dynamique. Pour ce faire, vous pouvez soit effectuer une requête avant d’afficher les objets available à vos utilisateurs, soit périodiquement (tous les jours, par exemple) mettre en cache les résultats que vous présentez à vos utilisateurs.

Nous déconseillons de coder en dur les tokens pour ces objets, car cette intégration nécessite des modifications du code lorsqu’une méthode d’expédition devient unavailable. Si vous n’effectuez pas ces modifications à temps, vous risquez d’essayer de passer des commandes avec des objets unavailable, ce qui entraînera des erreurs.

Récupérer les moyens de livraison

L’objet Hardware Shipping Method est obligatoire lors de la création d’une commande. Il détermine le délai de livraison estimé pour votre commande, ainsi que les frais de livraison. Vous devez utiliser un mode de livraison disponible dans le pays de livraison lors de la création de la commande.

Like SKUs, each Shipping Method is associated with a country: the shipping methods available in the US might be different from those available in Canada. Each Shipping Method also has a name, which denotes the basic category for this shipping method. To retrieve Shipping Methods, you must specify the country and can optionally specify the name parameter when making a request to the Hardware Shipping Methods endpoint:

curl https://api.stripe.com/v1/terminal/hardware_shipping_methods?country=US \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4"

Tout comme les unités de gestion des stocks et les produits, les modes de livraison peuvent évoluer avec le temps. Pour vous aider à gérer ces changements, l’état de chaque mode de livraison indique s’il est actuellement disponible (available) ou non (unavailable). Ce mécanisme fonctionne de la même manière que pour les unités de gestion des stocks et les produits, comme décrit ci-dessus. Comme pour les unités de gestion des stocks et les produits, nous vous recommandons de récupérer régulièrement les Shipping Methods afin que votre intégration ne devienne pas obsolète.

Prévisualiser une commande de matériel

Pour prévisualiser une commande de matériel, envoyez à Stripe une requête contenant les unités de gestion des stocks, les quantités, l’adresse de livraison et le mode de livraison de la commande.

curl https://api.stripe.com/v1/terminal/hardware_orders/preview \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4" \
  --data-urlencode "shipping[name]"="Jenny Rosen" \
  --data-urlencode "shipping[address][line1]"="1234 Main Street" \
  --data-urlencode "shipping[address][city]"="San Francisco" \
  --data-urlencode "shipping[address][state]"=CA \
  --data-urlencode "shipping[address][country]"=US \
  --data-urlencode "shipping[address][postal_code]"=94111 \
  --data-urlencode "shipping[company]"="Rocket Rides" \
  --data-urlencode "shipping[phone]"=15555555555 \
  --data-urlencode "shipping[email]"="test@example.com" \
  --data-urlencode shipping_method=thsm_MfuTjLaPEgXMa4 \
  --data-urlencode payment_type=monthly_invoice \
  --data-urlencode "hardware_order_items[][terminal_hardware_sku]"=thsku_JokaJ6KpLMlDID \
  --data-urlencode "hardware_order_items[][quantity]"=2 \
  -G

Afficher l’aperçu d’une commande vous permet de la valider et de déterminer le montant global des taxes applicables à la commande sans pour autant la passer. Vous pouvez utiliser cette fonction pour concevoir une page de paiement en ligne pour vos clients. Appeler l’endpoint Preview ne crée pas réellement de commande.

Essayez de réduire le plus possible le délai entre l’envoi d’une requête aux endpoints Preview Hardware Order et Create Hardware Order, afin de limiter le (faible) risque que les tarifs évoluent dans l’intervalle. Si ce problème vous préoccupe, vous pouvez enregistrer l’aperçu et créer une commande en utilisant les mêmes paramètres. Cela vous permet ainsi de comparer l’aperçu enregistré avec la commande et d’annuler la commande en cas de modification.

Créer une commande de matériel

Pour créer un objet Terminal Hardware Order, vous pouvez envoyer à Stripe une requête Create Hardware Order qui ressemble beaucoup à la requête Preview Hardware Order. Indiquez les unités de gestion des stocks, les quantités, l’adresse de livraison et le mode de livraison de la commande dans votre requête.

curl https://api.stripe.com/v1/terminal/hardware_orders \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4" \
  -d "shipping[name]"="Jenny Rosen" \
  -d "shipping[address][line1]"="1234 Main Street" \
  -d "shipping[address][city]"="San Francisco" \
  -d "shipping[address][state]"="CA" \
  -d "shipping[address][country]"="US" \
  -d "shipping[address][postal_code]"="94111" \
  -d "shipping[company]"="Rocket Rides" \
  -d "shipping[phone]"="15555555555" \
  -d "shipping[email]"="test@example.com" \
  -d "hardware_order_items[][terminal_hardware_sku]"="thsku_JokaJ6KpLMlDID" \
  -d "hardware_order_items[][quantity]"="2" \
  -d shipping_method="thsm_MfuTjLaPEgXMa4" \
  -d payment_type="monthly_invoice"

L’exemple ci-dessous indique un numéro de téléphone aux États-Unis. Si le numéro de téléphone spécifié via le paramètre shipping.phone est un numéro international, faites-le précéder du caractère d’échappement correspondant au signe + (par exemple, shipping[phone]="%2B358131234567" au lieu de shipping[phone]="+358131234567").

L’adresse e-mail renseignée dans le paramètre shipping.email reçoit des e-mails de mise à jour aux couleurs de Stripe en cas de changement d’état de la commande. Utilisez une adresse e-mail sur laquelle vous acceptez de recevoir des e-mails de Stripe.

Récupérer et interroger les commandes de matériel

Après avoir créé une commande, vous pouvez récupérer un objet Terminal Hardware Order à l’aide de la requête suivante.

curl https://api.stripe.com/v1/terminal/hardware_orders/
{{TERMINAL_HARDWARE_ORDER_ID}} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4"

Vous pouvez également établir la liste de tous les Terminal Hardware Order.

curl https://api.stripe.com/v1/terminal/hardware_orders \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -H "Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4"

Webhooks

Vous pouvez configurer des événements de webhook pour être informé des changements d’état des commandes. Vous devez ajouter une version d’en-tête (par exemple, Stripe-Version: 2024-11-20.acacia;terminal_hardware_orders_beta=v4) à vos endpoints de webhook pour recevoir les événements correctement. Nous prenons en charge les événements de webhook suivants :

• terminal_hardware_order.created
• terminal_hardware_order.canceled
• terminal_hardware_order.ready_to_ship
• terminal_hardware_order.shipped
• terminal_hardware_order.delivered
• terminal_hardware_order.undeliverable

Modifier l’état d’une commande en mode test

Vous pouvez modifier l’état d’une commande de lecteurs Terminal en mode test à l’aide des endpoints suivants dans l’API :

• /v1/test_helpers/terminal/hardware_orders/:hardware_order/mark_ready_to_ship
• /v1/test_helpers/terminal/hardware_orders/:hardware_order/ship
• /v1/test_helpers/terminal/hardware_orders/:hardware_order/deliver
• /v1/test_helpers/terminal/hardware_orders/:hardware_order/mark_undeliverable

Vous pouvez modifier l’état des commandes de lecteurs Terminal uniquement en mode test.

Taxes

Lors de la création d’une commande, Stripe renvoie le montant des taxes associées à la commande. Cette somme est calculée sur la base des taxes dues à Stripe au titre de l’achat. Si vous facturez les taxes à vos utilisateurs finaux pour des commandes passées à l’aide de l’API, vous pouvez calculer les montants qui vous sont dus et les imputer à vos utilisateurs. Il est possible que les montants qui vous sont dus soient différents de ceux que vous devez à Stripe.

Pour les factures avec TVA italienne, veuillez consulter le portail de la fiscalité italienne pour visualiser des factures.

Factures

Pendant la phase bêta, Stripe envoie des factures mensuelles pour toutes les commandes créées avec l’API. Vous pouvez modifier l’adresse e-mail qui reçoit les factures dans le Dashboard.

Suivi de livraison

Comme indiqué dans la section Livraison, Stripe travaille avec un partenaire de distribution qui traite les commandes Terminal. Lorsque notre partenaire reçoit les informations de suivi de la commande, celle-ci passe à l’état shipped. Vous pouvez configurer un endpoint de webhook pour la notification terminal_hardware_order.shipped si vous souhaitez recevoir une notification lorsqu’une commande dispose d’un numéro de suivi.

Log des modifications

Nouveaux transporteurs

• Ajoutez de nouvelles valeurs (canada_post, dhl, dpd et usps) au champ d’énumération Carrier.

v5 (2024-11-25)

• Add pagination to the List all Terminal Hardware SKUs, List all Terminal Hardware Products, and List all Terminal Hardware Shipping Methods endpoints.
• Require the country filter for the List all Terminal Hardware SKUs and List all Terminal Hardware Shipping Methods endpoints.

v4 (2023-01-23)

• Ajoutez un nouvel endpoint Preview Hardware Order. Supprimez les états de commande draft et expired. Supprimez l’endpoint /v1/terminal/hardware_orders/confirm et le paramètre confirm de l’endpoint Create Hardware Order.
• Ajoutez un nouvel état TerminalHardwareOrder dénommé ready_to_ship, qui représente une commande qui ne peut plus être annulée, mais n’a pas encore été expédiée.
• Ajoutez de nouveaux endpoints d’API pour faire passer l’état des commandes de lecteurs Terminal en mode test à l’état ready_to_ship, envoyée, livrée et livraison impossible.
• Ajoutez un nouvel objet Hardware Shipping Method pour remplacer l’ancien objet dans le champ shipping_method, ainsi que des endpoints d’API pour interroger ces nouveaux objets et les récupérer.
• Ajoutez un nouvel objet Hardware Product pour remplacer l’ancien champ product_type, ainsi que des endpoints d’API pour interroger et récupérer ces nouveaux objets.
• Ajoutez un nouveau champ dynamique orderable à l’objet TerminalHardwareSku, en remplacement de l’ancien champ max_per_order.
• Ajoutez des champs status et unavailable_after à TerminalHardwareSku pour déterminer le moment où une unité de gestion des stocks ne sera plus disponible à la commande, le cas échéant. Ces champs concernent également les nouveaux objets Hardware Shipping Method et Hardware Product.
• Si les webhooks v3 et v4 sont activés dans le même mode (en mode test ou en mode production) en même temps, Stripe envoie le webhook terminal_hardware_order.shipped deux fois. Nous envoyons le webhook terminal_hardware_order.shipped lorsqu’une commande passe à l’état ready_to_ship et shipped, et non simplement lorsqu’elle passe à l’état shipped. La version v3 en mode production et la version v4 en mode test n’entraînent pas de doublons de webhooks. Si vous devez activer simultanément les versions v3 et v4 dans le même mode, veillez à mettre à jour votre intégration afin qu’elle gère d’abord les webhooks terminal_hardware_order.shipped en double.
• Les commandes ready_to_ship dans la v4 apparaissent comme shipped dans la v3. Il est possible que vous voyiez une commande avec l’état shipped dans la v3 et ready_to_ship dans la v4 lors de la mise à jour de votre migration. Cela est dû au fait que le concept ready_to_ship n’existe pas dans la version v3. Ces commandes ne passent pas réellement à un état antérieur.

v3 (2019-04-03) Deprecated

• Mettez à jour l’unité de gestion des stocks Terminal Hardware et l’objet SKU du poste Terminal Hardware Order en supprimant les champs de texte tels que name, description, images et attributes.
• Rendez facultatif le paramètre de requête shipping_country des unités de gestion des stocks Hardware Order et renommez-le country.
• Ajoutez la possibilité d’interroger des unités de gestion des stocks dans l’API, via les paramètres product_type et country.

v2 (2019-12-20) Deprecated

• Mettez à jour Terminal Hardware Order en transformant l’objet structuré total_tax_amounts.rate.jurisdiction en chaîne.

v1 (20/11/2019) Deprecated

• Sortie initiale