Stripe
Swallow's native integration allows you to collect payments automatically..
Last updated
Swallow's native integration allows you to collect payments automatically..
Last updated
To set up the payment integration through the user interface:
Navigate to the settings section in Swallow
Select the "Integrations" page
Click "Connect to Stripe" and add a new connection
Give this new connection a name and a code
Enter your payment provider API key; and
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.
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://`.
To collect payments automatically, the customer must exist in both the Swallow and payment provider databases.
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:
Define the payment provider as the default payment provider;
Leave the field associated with the payment provider customer ID blank;
Enable the option to automatically create the customer in the payment provider; and
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.
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. When adding customer information, you must:
Define the payment provider as the default payment provider;
Provide the payment provider customer ID;
Disable the option to automatically create the customer in the payment provider; and
Define payment method options for this customer. Possible values are card, link, sepa_debit, us_bank_account and bacs_debit.
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.
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:
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.
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.
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.
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.
Once the payment provider is connected and the customer exists in both databases, you can start collecting 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.
If the payment fails, the status of the payment will switch from pending to failed and Swallow will generate a quote.payment_failure webhook.
When a payment requires multi-step authentication, such as 3D Secure (3DS), Swallow triggers a payment.requires_action webhook. 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.
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.
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.
