Stripe integration

​

Integration setup

To set up the integration with Stripe through the user interface:

1. In the side menu, select “Settings”;
2. Select the “Integrations” tab;
3. Click “Stripe” and add a new connection;
4. Give this new connection a name and a code;
5. Enter your Stripe API key (locate your API key); and
6. Click “Connect to Stripe” to confirm.

​

Redirect url after checkout

After establishing the connection with Stripe, set a success URL where your end customer will be directed after completing the checkout. Please note that if it’s not defined, your end customer will be redirected to Stripe’s website.

Please note that you can edit or delete the redirect URL, and this will only affect new checkout URLs created.

​

Customer information

To collect payments automatically, the customer must exist in both the Lago and Stripe databases.

​

New customer

If the customer does not already exist in Stripe, you can first create them in Lago, either via the user interface or the API. When adding customer information, you must:

1. Define Stripe as the default payment provider;
2. Leave the field associated with the Stripe customer ID blank;
3. Enable the option to automatically create the customer in Stripe; and
4. Define payment method options for this customer. Possible values are card and sepa_debit.

The customer will automatically be added to Stripe. Stripe will then return the customer ID, which will be stored in Lago.

Creation of a new customer with Stripe

​

Existing customer

If the customer already exists in Stripe but not in Lago, you should create the customer record, either via the user interface or the API. When adding customer information, you must:

1. Define Stripe as the default payment provider;
2. Provide the Stripe customer ID;
3. Disable the option to automatically create the customer in Stripe; and
4. Define payment method options for this customer. Possible values are card and sepa_debit.

Migration of an existing Stripe customer

​

Supported payment methods

Lago’s Stripe integration accommodates a variety of payment methods, both generic and region-specific. The checkout URL provided by Lago is designed to handle multiple payment options seamlessly.

    LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "provider_payment_methods": ["card"]
      }
    }
  }'

    LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "provider_payment_methods": ["sepa_debit"]
      }
    }
  }'

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "provider_payment_methods": ["us_bank_account"]
      }
    }
  }'

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "provider_payment_methods": ["bacs_debit"]
      }
    }
  }'

​

Stripe Checkout: storing customer’s payment method information

When Lago automatically creates a customer in Stripe, you will receive a checkout link from Lago to facilitate the storage of your customer’s payment method information.

The payload sent by Lago will have the following structure, with the checkout link stored under checkout_url:

{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "stripe",
    "checkout_url": "https://checkout.stripe.com/c/pay/prod_c15sTbBMLep5FKOA9b9pZBiRBBYYSU1IJ5T89I5TTtpKgzE380JSmxnVYz#fidkdWxOYHw"
  }
}

By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It’s important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Stripe for future transactions.

​

Regenerate checkout link on demand

In cases where your end customer has not had the opportunity to complete the checkout process to inform their payment method or wishes to modify the saved payment information, you can generate a new checkout link using the designated endpoint.

POST /api/v1/customers/:customer_external_id/checkout_url

Upon successful generation, the new checkout link will be available in the endpoint response, and it will not be delivered through a webhook message. It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.

​

Default payment method

When you add a new payment method in Stripe, Lago automatically sets it as the default. This guarantees that Lago uses the latest payment method for a customer. However, if you manually designate one of multiple payment methods as the default, Lago will use it for payments instead the most recent one.

​

Payment intents

Once Stripe is connected and the customer exists in both databases, you can start collecting payments.

Each time a new invoice with an amount greater than zero is generated by Lago, a payment intent will automatically be created. Stripe will record the invoice ID and process the payment. If the payment is successful, the status of the payment will switch from pending to succeeded.

If the payment fails, the status of the payment will switch from pending to failed and Lago will generate an invoice.payment_failure webhook.

If the new invoice amount falls below the minimum amount supported by Stripe, the payment status will remain as pending.

​

Payment disputes

In the event of a lost payment dispute within Stripe, Lago initiates an automatic response by marking the relevant invoice as disputed lost. This action involves populating the dispute_lost_at field with the timestamp when the dispute was lost. Following this update:

• The invoice becomes non-voidable;
• Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
• The invoice cannot be resent for collection.