How to trigger wallet credits when a customer adds a payment method

Sometimes you may want to automatically add credits to a customer's wallet in Lago as soon as they add a payment method in Stripe. Lago does not have a native trigger for payment method addition, but you can build this flow by combining a Stripe webhook with Lago's wallet API.

How to set it up

Listen for the setup_intent.succeeded event in Stripe — this fires when a customer successfully completes adding a payment method. This is the most reliable signal that a customer's card is set up and ready. In your webhook handler, identify the corresponding Lago customer and call: POST /api/v1/wallet_transactions with a payload using granted_credits for the amount you want to issue:

{ 
  "wallet_transaction": { 
    "wallet_id":"the-customers-wallet-id", 
    "granted_credits": "5.00" 
  } 
}

Granted credits are settled immediately and require no payment — they are added directly to the customer's balance. This is the correct type for promotional or incentive credits. Use paid_credits only when you intend to charge the customer for the top-up.

Prerequisites

The customer must already have a wallet in Lago before you can issue credits. If your flow creates wallets on customer creation, this should be in place by the time the payment method is added. If not, you may need to create the wallet first via POST /api/v1/wallets before issuing the transaction.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.