Utiliser l'API Settings pour configurer Stripe Tax

Vérifier si le compte connecté est prêt à utiliser Stripe Tax

Effectuez cette vérification lorsque le compte Standard configure Stripe Tax via le Dashboard Stripe, mais que votre plateforme doit déterminer si Stripe Tax peut être activé.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application. Pour vérifier les paramètres Stripe Tax d’un compte connecté, récupérez l’objet tax.settings à l’aide de l’en-tête Stripe-Account défini sur l’ID du compte connecté :

curl https://api.stripe.com/v1/tax/settings \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

Vous pouvez également écouter l’événement webhook tax.settings.updated qui se déclenche lorsque les comptes mettent à jour leurs paramètres fiscaux ou lorsque de nouveaux paramètres fiscaux requis sont introduits. Pour savoir comment ajouter un endpoint de webhook, consultez la page Mettre les webhooks en production et veillez à sélectionner l’option Écouter des événements sur des comptes connectés dans le Dashboard.

Pour qu’un compte puisse utiliser Stripe Tax, l’objet tax.settings récupéré par l’API contenu dans la réponse ou l’événement webhook renvoie le status "active". Les paramètres defaults.tax_code et defaults.tax_behavior ne sont nécessaires que s’ils n’ont pas été renseignés dans le produit ou le tarif pour chaque appel à l’API.

{
  "object": "tax.settings",
  "defaults": {
    "tax_code": null,
    "tax_behavior": null
  },
  "head_office": {
    "address": {
      "country": "DE"
    }
  },
  "livemode": false,
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Pour qu’un compte puisse utiliser Stripe Tax, l’objet tax.settings de la réponse ne doit pas contenir le status "pending". Le status_details[pending][missing_fields] contient la liste de tous les champs requis manquants.

{
  "object": "tax.settings",
  "defaults": {
    "tax_code": null,
    "tax_behavior": null
  },
  "head_office": null,
  "livemode": false,
  "status": "pending",
  "status_details": {
    "pending": {
      "missing_fields": ["head_office"]
    }
  }
}

Configurer les paramètres des comptes connectés

Effectuez cette étape lorsque vous gérez la configuration de Stripe Tax est intégralement via une interface sur votre plateforme.

Vous pouvez modifier les paramètres du compte connecté via un appel de modification des paramètres. Effectuez un appel en indiquant l’adresse du siège de l’entreprise, le code de taxe par défaut et le comportement fiscal à l’aide de l’en-tête Stripe-Account défini sur l’ID du compte connecté.

curl https://api.stripe.com/v1/tax/settings \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "defaults[tax_code]"=txcd_10000000 \
  -d "defaults[tax_behavior]"=inclusive \
  -d "head_office[address][country]"=DE

L’objet tax.settings mis à jour comporte désormais un siège social, un code de taxe par défaut et un régime de taxe par défaut, ce qui vous permet d’activer Stripe Tax pour ce compte connecté.

{
  "object": "tax.settings",
  "defaults": {
    "tax_code": "txcd_10000000",
    "tax_behavior": "inclusive"
  },
  "head_office": {
    "address": {
      "country": "DE"
    }
  },
  "livemode": false,
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Validations et erreurs

Les codes de taxe doivent correspondre aux codes de taxe disponibles et le comportement fiscal doit être défini sur inclusive, exclusive ou inferred_by_currency (une fois défini, il ne peut plus être défini sur null). Le head_office doit inclure une adresse prise en charge.

La head_office[address] possède les champs line1, line2, city, state, postal_code et country. Les tableaux ci-dessous décrivent les formats d’adresse pris en charge.

Utilisez l’un des formats d’adresse ci-dessus pour nous permettre de reconnaître systématiquement le siège social de l’entreprise de votre compte connecté. Le champ du pays doit toujours correspondre à un code pays ISO valide.