Clients

Le bundle persiste une projection locale du customer Stripe dans CashierBundle\Entity\StripeCustomer.

Créer ou récupérer un customer Stripe

use CashierBundle\Contract\BillableEntityInterface;
use CashierBundle\Service\CustomerService;
 
final readonly class CheckoutController
{
    public function __construct(
        private CustomerService $customerService,
    ) {
    }
 
    public function __invoke(BillableEntityInterface $user): void
    {
        $stripeId = $this->customerService->createOrGetStripeId($user);
    }
}

Le payload Stripe est construit à partir de votre entité billable:

• getEmail()
• getName()
• getPhone(): ?string (optionnel)
• getAddress(): ?array (optionnel, doit retourner ['line1' => '...', 'line2' => '...', 'postal_code' => '...', 'city' => '...', 'country' => 'FR'])

Mettre à jour le customer

$this->customerService->update($user, [
    'metadata' => [
        'source' => 'backoffice',
    ],
]);

Synchronisation locale

Le bundle conserve les données utiles en local pour éviter de dépendre uniquement d’un fetch Stripe temps réel.

Champs synchronisés automatiquement

Champs de StripeCustomer:

• stripeId
• email
• name
• phone
• currency
• balance (solde en centimes)
• address (tableau)
• invoicePrefix
• taxExempt
• pmType (type de méthode de paiement par défaut)
• pmLastFour (4 derniers chiffres)
• billableId
• billableType

Synchronisation depuis Stripe

Pour synchroniser les données depuis Stripe (utile dans un handler webhook customer.updated):

$this->customerService->sync($user); // synchronise depuis l'entité locale
$this->customerService->syncByStripeId('cus_xxx'); // synchronise depuis Stripe API

Suppression

Quando un customer est supprimé dans Stripe, le webhook customer.deleted déclenche CustomerDeletedHandler qui supprime le StripeCustomer local (pas l’entité User applicative).

Balance (solde)

Le bundle gère le solde customer Stripe (crédits/débits).

// Créditer le solde (montant négatif chez Stripe, en centimes)
$user->creditBalance(1000, 'Crédit bonus'); // 10€
 
// Débiter le solde
$user->debitBalance(500, 'Utilisation service');
 
// Solde formaté
$user->balance(); // string, ex: "10.00 EUR"

CustomerBalanceTransaction

Chaque opération de solde est persistée dans CashierBundle\Entity\CustomerBalanceTransaction:

• id — ID unique
• amount — montant en centimes (négatif = crédit, positif = débit)
• currency — devise
• type — type de transaction
• description — description
• isCredit() — retourne true si crédit
• isDebit() — retourne true si débit

Locale client

Pour les factures, la locale suit cette priorité:

1. locale explicite passée au rendu
2. preferred_locales du customer Stripe
3. cashier.invoices.default_locale

Si votre application connaît déjà la langue de l’utilisateur, poussez-la dans Stripe via preferred_locales au moment du checkout ou de la mise à jour du customer.

Paiements →