Collecter les numéros fiscaux des clients avec Checkout

Lorsque la collecte des numéros fiscaux est activée, Checkout affiche ou masque le formulaire de recueil du numéro fiscal en fonction de la localisation de votre client. Si la collecte du numéro fiscal est prise en charge dans le pays où se trouve votre client, Checkout affiche une case à cocher permettant au client d’indiquer s’il est une entreprise. Quand la case est cochée, Checkout affiche des champs supplémentaires pour la saisie du numéro fiscal et de la dénomination sociale de l’entreprise. Checkout détermine la localisation du client à l’aide de son adresse de livraison lorsqu’elle est disponible. Sinon, la localisation est basée sur l’adresse de facturation du client. Chaque client ne peut saisir qu’un seul numéro fiscal.

Nouveaux clients

Pour activer le recueil de numéros fiscaux pour les nouveaux clients, définissez le paramètre tax_id_collection[enabled] sur true lors de la création d’une session Checkout.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Cet exemple crée une session en mode payment avec collecte des numéros fiscaux activée. Pour les abonnements, faites les mêmes changements avec le mode défini sur subscription.

Vous pouvez également configurer Checkout de sorte à créer automatiquement un nouveau Customer à l’aide de customer_creation. Dans ce cas, Checkout enregistre les informations fiscales collectées au cours d’une session pour ce nouveau client. Sinon, les informations relatives au numéro fiscal seront toujours disponibles dans customer_details.tax_ids.

Clients existants

Si vous transmettez un objet Customer existant lors de la création d’une session, Checkout met à jour cet objet Customer en remplaçant les informations fiscales existantes par celles qui sont recueillies lors de la session. Checkout enregistre la dénomination sociale recueillie sous la propriété nom et le numéro fiscal recueilli dans le tableau customer.tax_ids de l’objet Customer. Puisque la collecte de la dénomination sociale peut effacer le nom existant de l’objet Customer, vous devez définir le paramètre customer_update.name sur auto lors de la création de la session.

Lorsque vous collectez des numéros fiscaux de clients existants, vous pouvez baser leur localisation sur les adresses existantes de ces clients ou sur les adresses saisies lors du règlement. Checkout recherche par défaut l’adresse existante des clients pour déterminer leur localisation :

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Si les adresses de vos clients existants ne sont pas enregistrées, vous pouvez baser leur localisation sur l’adresse de facturation ou de livraison saisie lors du règlement. Pour indiquer que vous souhaitez déterminer la localisation du client à l’aide de l’adresse de facturation saisie lors du règlement, vous devez définir le paramètre customer_update.address sur auto. Lorsque customer_update.address est réglé sur auto, Checkout remplace toutes les adresses précédemment enregistrées sur le client par l’adresse saisie pendant la session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[address]"=auto \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Si vous recueillez les adresses de livraison de clients existants, vous devez baser leur localisation sur l’adresse de livraison saisie lors du règlement. Pour ce faire, définissez le paramètre customer_update.shipping sur auto. Lorsque customer_update.shipping est réglé sur auto, Checkout remplace toutes les adresses de livraison précédemment enregistrées sur le client par l’adresse de livraison saisie lors de la session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_HQmikpKnGHkNwW \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "tax_id_collection[enabled]"=true \
  -d "customer_update[name]"=auto \
  -d "customer_update[shipping]"=auto \
  -d "shipping_address_collection[allowed_countries][0]"=DE \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

L’exemple de code ci-dessus crée une session en mode payment avec la collecte du numéro fiscal activée. Pour les abonnements, effectuez les mêmes modifications en définissant le mode sur subscription.

Checkout inclut les numéros fiscaux fournis dans l’objet Session correspondant. Lorsqu’une session est finalisée, Checkout génère un événement checkout.session.completed que vous pouvez écouter à l’aide d’un endpoint de webhook. Si vous souhaitez récupérer le numéro fiscal collecté par un objet Session, vous pouvez le trouver dans le tableau customer_details.tax_ids de la session :

{
  "object": {
    "id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y",
    "object": "checkout.session",
    ...
    "customer": "cus_id_of_new_customer",
    "customer_details": {
      ...
      "tax_ids": [
        {
          "type": "eu_vat",
          "value": "FRAB123456789"
        }
      ]
    },
    ...
    "tax_id_collection": {
      "enabled": true
    },
    ...
  }
}

Checkout enregistre également les dénominations sociales et numéros fiscaux recueillis dans l’objet Customer associé à la session, le cas échéant. Les numéros fiscaux recueillis lors du règlement sont accessibles dans le tableau customer.tax_ids de l’objet Customer. Vous pouvez également retrouver tous les numéros fiscaux enregistrés d’un objet Customer à l’aide de la ressource Tax IDs en définissant le paramètre owner.type sur customer et le paramètre owner.customer sur l’ID du client. Tout nouveau numéro fiscal comporte une dénomination sociale associée, que Checkout enregistre dans la propriété nom de l’objet Customer. De cette façon, la dénomination sociale recueillie apparaît sur toutes les factures d’abonnement de ce client.

In testing environments, you can enter any alphanumeric string that is in the correct format of a supported tax ID type (for example, DE123456789 for eu_vat). For a full list of example tax IDs you can reference our Customer Tax ID guide. You can also use our test tax IDs to test various verification state flows.