# Stripe ### Integration setup To set up the payment integration through the user interface:
1. Navigate to the settings section in Swallow 2. Select the **"Integrations"** page 3. Click **"Connect to Stripe"** and add a new connection 4. Give this new connection a name and a code 5. Enter your payment provider API key; and 6. Click **"Connect"** to confirm. By default, customers created in Swallow are not automatically created in the payment provider. If you want your Swallow customers to be added to the payment provider, you need to activate this option. ### Redirect url after quote completion After establishing the connection with the payment provider, set a "next button URL" where your end customer will be directed after completing the quote. Please note that if it's not defined, your end customer will be redirected to the payment provider's website. URL defined should always begin with \`http\://\` or \`https\://\`. ### Customer information To collect payments automatically, the customer must exist in both the Swallow and payment provider databases. #### New customer If the customer does not already exist in the payment provider, you can first create them in Swallow, either via the user interface or the API. When adding customer information, you must: 1. Define the payment provider as the **default payment provider**; 2. Leave the field associated with the **payment provider customer ID** blank; 3. **Enable** the option to automatically create the customer in the payment provider; and 4. Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`. The customer will automatically be added to the payment provider. The payment provider will then return the customer ID, which will be stored in Swallow. #### Existing customer If the customer already exists in the payment provider but not in Swallow, you should create the customer record, either via the user interface or [the API](https://api.llow.io/sw/customers). When adding customer information, you must: 1. Define the payment provider as the **default payment provider**; 2. Provide the **payment provider customer ID**; 3. **Disable** the option to automatically create the customer in the payment provider; and 4. Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`. ### Supported payment methods Swallow's payment integration accommodates a variety of payment methods, both generic and region-specific. The quote URL provided by Swallow is designed to handle multiple payment options seamlessly.
Card payments Swallow's payment integration includes a universal card payment method that supports various currencies, ideal for global transactions. This method is set as the default to facilitate recurring payments, ensuring Swallow can process charges for your customers efficiently. ```bash curl --location --request POST "https://api.llow.io/sw/customers" \ --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": "payment_provider", "provider_customer_id": "cus_12345", "sync": true, "sync_with_provider": true, "provider_payment_methods": ["card"] } } }' ```
SEPA debits (EU only) For European customers, Swallow supports SEPA Debit (Single Euro Payments Area). Accepting a mandate through this method authorizes you to debit your customers' accounts for recurring payments via Swallow. The designated payment method for SEPA transactions within Swallow is identified as `sepa_debit`. It's important to note that **this payment option is exclusive to invoices in `EUR` currency**. ```bash curl --location --request POST "https://api.llow.io/sw/customers" \ --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": "payment_provider", "provider_customer_id": "cus_12345", "sync": true, "sync_with_provider": true, "provider_payment_methods": ["sepa_debit"] } } }' ```
ACH debits (US only) For US-based transactions, Swallow integrates ACH Debit, leveraging the Automated Clearing House for electronic bank-to-bank payments. Upon accepting a mandate, you gain authorization to execute recurring debits from your customers' accounts through Swallow. The designated payment method for ACH transactions within Swallow is identified as `us_bank_account`. It's important to note that **this payment option is exclusive to invoices in `USD` currency**. ```bash curl --location --request POST "https://api.llow.io/sw/customers" \ --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": "payment_provider", "provider_customer_id": "cus_12345", "sync": true, "sync_with_provider": true, "provider_payment_methods": ["us_bank_account"] } } }' ```
BACS debits (UK only) For UK transactions, Swallow integrates BACS Debit, utilizing the UK's BACS system for direct bank-to-bank payments. By accepting a mandate with this method, you're authorized to initiate recurring debits from your customers' accounts through Swallow. The specific payment method for BACS transactions within Swallow is designated as `bacs_debit`. It's important to note that **this payment method is exclusively for invoices in `GBP` currency.** ```bash curl --location --request POST "https://api.llow.io/sw/customers" \ --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": "payment_provider", "provider_customer_id": "cus_12345", "sync": true, "sync_with_provider": true, "provider_payment_methods": ["bacs_debit"] } } }' ```
Link For card transactions, you can enable the Link feature to offer one-click payments. Link automatically fills in your customers' payment information, ensuring a seamless and secure quote completion experience. If you are using the \`link\` feature, it must be used in conjunction with \`card\`. ```bash curl --location --request POST "https://api.llow.io/sw/customers" \ --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": "payment_provider", "provider_customer_id": "cus_12345", "sync": true, "sync_with_provider": true, "provider_payment_methods": ["card", "link"] } } }' ```
### Payment Provider Checkout: storing customer's payment method information Checkout page shows only selected payment methods for customers. When Swallow automatically creates a customer in the payment provider, you will receive a checkout link from Swallow to facilitate the storage of your customer's payment method information. The payload sent by Swallow will have the following structure, with the checkout link stored under `checkout_url`: ```json { "webhook_type": "customer.checkout_url_generated", "object_type": "payment_provider_customer_checkout_url", "payment_provider_customer_checkout_url": { "swallow_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371", "external_customer_id": "hooli_1234", "payment_provider": "payment_provider", "checkout_url": "https://checkout.payment_provider.com/c/pay/prod_c15sTbBMLep5FKOA9b9pZBiRBBYYSU1IJ5T89I5TTtpKgzE380JSmxnVYz#fidkdWxOYHw" } } ``` Note: The checkout link automatically expires after 24 hours! 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, Swallow will send the payment method details and securely store them into the payment provider 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](https://api.llow.io/sw/customers/%7Bcustomer_reference%7D/checkout_url). ```bash POST /sw/customers/:customer_reference/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 the payment provider, **Swallow automatically sets it as the default**. This guarantees that Swallow uses the latest payment method for a customer. However, if you manually designate one of multiple payment methods as the default, Swallow will use it for payments instead the most recent one. ### Payment intents Once the payment provider is connected and the customer exists in both databases, you can start collecting payments. #### Succeeded payments Each time a new quote with an **amount greater than zero** is generated by Swallow, a payment intent will automatically be created. The payment provider will record the quote reference and process the payment. If the payment is successful, the status of the payment will switch from `pending` to `succeeded`. #### Failed payments If the payment fails, the status of the payment will switch from `pending` to `failed` and Swallow will generate a `quote.payment_failure` [webhook](https://api.llow.io/sw/webhooks). #### Payments requiring validation When a payment requires multi-step authentication, such as 3D Secure (3DS), Swallow triggers a `payment.requires_action` [webhook](https://api.llow.io/sw/webhooks). This webhook provides the URL for completing the 3DS process. It's important to note that **most payments in India require 3DS authentication** due to RBI regulations. #### Minimum payment amount If the new quote amount falls below the minimum amount supported by the payment provider, the payment status will remain as `pending`. A valid payment method for the customer must be defined in the payment provider for the payment intent to succeed. ### Payment disputes In the event of a **lost** payment dispute within the payment provider, Swallow initiates an automatic response by marking the relevant quote as disputed lost. This action involves populating the `dispute_lost_at` field with the timestamp when the dispute was lost. Following this update: * The quote becomes non-voidable; * Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and * The quote cannot be resent for collection. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://swallow-1.gitbook.io/swallow/integrations/payments/stripe.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.