Guide d'intégration des services financiers intégrés

Créer un compte connecté

Créez un compte connecté pour représenter une entreprise cliente de votre plateforme. Par exemple, si votre produit est une plateforme SaaS à destination de restaurants, chaque restaurant est représenté par un compte connecté.

La requête suivante crée un compte connecté établi aux États-Unis avec la bonne configuration et demande les fonctionnalités requises :

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[requirement_collection]"=application \
  -d "capabilities[transfers][requested]"=true \
  -d "capabilities[card_issuing][requested]"=true \
  -d "capabilities[treasury][requested]"=true \
  -d "capabilities[us_bank_account_ach_payments][requested]"=true

Les informations du compte de l’utilisateur apparaissent dans la réponse :

{
    ...
    "id":   "{{CONNECTED_ACCOUNT_ID}}",
    "controller": {
      "stripe_dashboard": {
        "type": "none"
      },
      "fees": {
        "payer": "application"
      },
      "losses": {
        "payments": "application"
      },
      "is_controller": true,
      "type": "application",
      "requirement_collection": "application"
    },
    ...
}

Notez l’id du compte connecté. Vous le transmettrez dans les requêtes de l’en-tête Stripe-Account pour vous authentifier sous ce compte.

Si un compte connecté existe déjà, vous pouvez ajouter les fonctionnalités requises en spécifiant son id dans la requête :

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "capabilities[transfers][requested]"=true \
  -d "capabilities[treasury][requested]"=true \
  -d "capabilities[card_issuing][requested]"=true

Vérifier le compte connecté

Choisissez l’une des options d’inscription des utilisateurs suivantes :

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

{
  "object": "account_link",
  "created": 1612927106,
  "expires_at": 1612927406,
  "url": "https://connect.stripe.com/setup/s/…"
}

À ce stade, Stripe a créé et vérifié le compte connecté, qui est doté des fonctionnalités active pertinentes pour l’utilisation d’Issuing et de Financial Accounts pour les plateformes.

Pour en savoir plus, consultez les pages suivantes :

• Configurer une intégration Issuing et Connect
• Inscription hébergée par Stripe pour les comptes connectés
• Création et utilisation de comptes connectés
• Vérification d’identité pour les comptes connectés

Après avoir activé la fonctionnalité Financial Accounts sur votre plateforme, ajoutez des objets FinancialAccount à l’architecture de votre plateforme afin de permettre la sauvegarde, l’envoi et la réception efficaces de fonds. Stripe associe un compte financier à votre compte de plateforme après l’activation et vous permet de provisionner un compte financier individuel pour chaque compte connecté éligible sur votre plateforme.

Dans l’API Stripe, les objets FinancialAccount servent de source et de destination aux requêtes API de mouvement de fonds. Vous pouvez demander via l’API d’affecter des Features aux FinancialAccounts afin de fournir des fonctionnalités supplémentaires aux comptes financiers de votre plateforme.

Un compte financier possède son propre solde de fonds, distinct du solde des paiements du compte connecté auquel il est associé. Par exemple, le propriétaire d’un compte connecté de votre plateforme peut disposer de 100 USD sur son solde de compte connecté et de 200 USD sur son solde de compte financier. Dans ce cas, son solde total s’élève à 300 USD, soit la somme des soldes de son compte financier et de son compte connecté. Ces deux soldes sont distincts, mais l’API permet de transférer des fonds depuis le solde du compte connecté vers le solde du compte financier.

Créer un compte financier

Une fois que Stripe a ajouté la fonctionnalité treasury à un compte et qu’elle est marquée active, vous pouvez créer un objet FinancialAccount pour le compte connecté. Pour ce faire, appelez FinancialAccounts et demandez les Features (fonctionnalités) que vous souhaitez fournir :

curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d "features[card_issuing][requested]"=true \
  -d "features[deposit_insurance][requested]"=true \
  -d "features[financial_addresses][aba][requested]"=true \
  -d "features[inbound_transfers][ach][requested]"=true \
  -d "features[intra_stripe_flows][requested]"=true \
  -d "features[outbound_payments][ach][requested]"=true \
  -d "features[outbound_payments][us_domestic_wire][requested]"=true \
  -d "features[outbound_transfers][ach][requested]"=true \
  -d "features[outbound_transfers][us_domestic_wire][requested]"=true

Lorsque vous demandez des fonctionnalités lors de la création du compte financier, la réponse indique leur état dans les paramètres active_features, pending_features et restricted_features :

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": ["card_issuing"],
  "pending_features": ["financial_addresses.aba"],
  "restricted_features": [],
  // No FinancialAddress added as the financial_addresses.aba feature is not yet active
  "financial_addresses": [],
  "livemode": true,
  "status": "open",
  ...
}

L’activation peut être instantanée pour certaines fonctionnalités (par exemple card_issuing). Cependant, d’autres fonctionnalités, telles que financial_addresses.aba, s’activent de manière asynchrone et peuvent rester à l’état pending jusqu’à 30 minutes, le temps que Stripe communique avec les systèmes externes. Une fois toutes les fonctionnalités pertinentes activées, vous recevez une confirmation sur le récepteur webhook treasury.financial_account.features_status_updated. Pour en savoir plus sur les fonctionnalités des comptes financiers, consultez la section sur les fonctionnalités disponibles.

Associer un compte bancaire

Pour permettre à vos clients de transférer de l’argent vers et depuis un compte externe, créez un SetupIntent avec les paramètres requis, et indiquez que votre client est titulaire du compte externe en le rattachant à self :

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d attach_to_self=true \
  -d "flow_directions[]"=inbound \
  -d "flow_directions[]"=outbound \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_data[type]"=us_bank_account \
  -d "payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "payment_method_data[us_bank_account][account_holder_type]"=company \
  -d "payment_method_data[billing_details][name]"="Company Corp" \
  -d confirm=true \
  -d "mandate_data[customer_acceptance][type]"=online \
  -d "mandate_data[customer_acceptance][online][ip_address]"="123.123.123.123" \
  --data-urlencode "mandate_data[customer_acceptance][online][user_agent]"="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36"

La réponse de l’API inclut un identifiant de payment_method unique, qui sert à référencer ce compte bancaire lors des virements ACH :

{
  "id": "{{SETUP_INTENT_ID}}",
  "object": "setup_intent",
  "next_action": {
    "type": "verify_with_microdeposits",
    "verify_with_microdeposits": {
      "arrival_date": 1642579200,
      "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_xxx",
      "microdeposit_type": "amounts"
    }
  },
  ...
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_types": [
    "us_bank_account"
  ]
}

Pour utiliser un compte bancaire, vous devez d’abord le vérifier à l’aide de microversements (option sur laquelle nous nous concentrons ici) ou de connexions financières (option la plus rapide). La réponse SetupIntent de l’étape précédente inclut une URL hosted_verification_url que vous devez présenter à votre client pour qu’il puisse saisir le code de libellé associé au microversement. Utilisez la valeur SM11AA pour vérifier le compte bancaire ou testez d’autres cas de figure à l’aide des numéros de comptes de test fournis par Stripe.

Vérification à l’aide de microversements

Ajouter des fonds au compte financier

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
"{{CONNECTED_ACCOUNT_ID}}" \
  -d "components[financial_account][enabled]"=true \
  -d "components[financial_account][features][send_money]"=true \
  -d "components[financial_account][features][transfer_balance]"=true \
  -d "components[financial_account][features][external_account_collection]"=true

// Include this element in your HTML
const financialAccount = stripeConnectInstance.create('financial-account');
financialAccount.setFinancialAccount('{{FINANCIAL_ACCOUNT_ID')
container.appendChild(financialAccount);

À ce stade, le compte connecté dispose d’un FinancialAccount crédité des fonds d’un InboundTransfer. Vous pouvez les dépenser avec des cartes ou des OutboundPayments, comme les virements bancaires ou ACH.

Pour en savoir plus, consultez les pages suivantes :

• Obtenir les autorisations pour les InboundTransfers
• Utiliser Financial Accounts pour les plateformes
• Utilisation de Financial Accounts pour transférer des fonds
• Demander des fonctionnalités sur un Financial Account
• Utilisation de SetupIntents, PaymentMethods et BankAccounts
• Transférer des fonds à l’aide d’objets InboundTransfer
• Transférer des fonds à l’aide d’objets ReceivedCredit

Créer une autorisation

Pour observer l’impact des activités de carte sur le solde associé, générez une autorisation test. Vous pouvez le faire sur la page Issuing du Dashboard du compte connecté ou en effectuant l’appel suivant à l’API Authorization :

curl https://api.stripe.com/v1/test_helpers/issuing/authorizations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d card=
"{{CARD_ID}}" \
  -d amount=1000 \
  -d authorization_method=chip \
  -d "merchant_data[category]"=taxicabs_limousines \
  -d "merchant_data[city]"="San Francisco" \
  -d "merchant_data[country]"=US \
  -d "merchant_data[name]"="Rocket Rides" \
  -d "merchant_data[network_id]"=1234567890 \
  -d "merchant_data[postal_code]"=94107 \
  -d "merchant_data[state]"=CA

Après approbation, Stripe crée une Authorization à l’état pending en attendant la capture. Notez l’id d’autorisation que vous utiliserez pour capturer les fonds :

{
  "id": "iauth_1NvPyY2SSJdH5vn2xZQE8C7k",
  "object": "issuing.authorization",
  "amount": 1000,
  ...
  "status": "pending",
  "transactions": [],
}

Vous pouvez récupérer les détails du solde du compte financier et consulter l’effet de l’autorisation :

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

La réponse de l’API est un objet FinancialAccount avec un hachage balance (solde) détaillant les fonds et leur disponibilité :

{
  "object": "treasury.financial_account",
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  ...
  "balance": {
    "cash": {"usd": 19000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  }
}

La réponse indique que 190 USD sont actuellement disponibles, ainsi que 10 USD supplémentaires placés dans outbound_pending à partir de l’autorisation pending. Vous pouvez désormais simuler la capture de l’autorisation avec l’API.

Capturer les fonds

Capturez les fonds à l’aide du code suivant :

curl -X POST https://api.stripe.com/v1/test_helpers/issuing/authorizations/
{{AUTHORIZATION_ID}}
/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Une fois l’autorisation capturée, Stripe crée une transaction Issuing. L’attribut status de l’autorisation reçoit la valeur closed et un webhook ReceivedDebit est créé à partir de ces informations. La récupération des informations du solde du compte financier montre que la valeur outbound_pending est désormais de 0 USD alors que le solde disponible reste de 190 USD :

{
  "object": "treasury.financial_account",
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  ...
  "balance": {
    "cash": {"usd": 19000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 0}
  }
}