Swallow
  • YOUR FIRST MODEL
    • Setting up your first project
    • Manual setup of a new product
    • Excel Model Upload
    • Create your team
    • Essential concepts
      • Syntax
      • Steps
      • Collections
      • Try Model
      • Spotlight
  • PROCESS
    • Team Management
    • Governance & Collaboration
  • BUILD
    • Building with AI
    • Step builder
      • Understanding step types
      • Ordering step blocks
      • Placeholder mode
      • Up/Downloading models
      • Sharing your model
      • Running tests
    • Inputs
    • Enriching Raw Data
      • Transform Data
      • Enrich via API
      • Data Set
      • Collection
      • Custom Code
    • Setting Up Decisions
      • Exclusions
      • Excesses
      • Endorsements
      • Refer
    • Making Calculations
      • Factors
      • Calculation
    • Outputs
  • TEST
    • Creating New Tests
    • Running Tests
    • Editing Tests
    • Reading & Interpreting Tests
    • Impact Testing
  • DATA
    • Working with real-time data
    • Data Views
    • Data Quotas
    • Troubleshooting
    • API Webhooks
    • Data Downloads
  • ADMIN & SETTINGS
    • Project Management
    • Account Management
  • INTEGRATIONS
    • Introduction
    • Payments
      • Stripe
      • GoCardless
      • Adyen
    • Alerting
      • Slack
      • Zapier
    • Data
      • AWS S3
      • Google Sheets
    • Admin
      • Socotra
      • Guidewire
      • Hubspot
      • Salesforce
  • Developer API
    • Introduction
    • Authentication
    • Errors codes
    • Endpoints
      • /quotes
      • /projects
      • /tests
      • /process
Powered by GitBook
On this page
  • Integration setup
  • Redirect url after quote completion
  • Customer information
  • Supported payment methods
  • Payment Provider Checkout: storing customer's payment method information
  • Regenerate checkout link on demand
  • Default payment method
  • Payment intents
  • Payment disputes
  1. INTEGRATIONS
  2. Payments

Stripe

Swallow's native integration allows you to collect payments automatically..

PreviousPaymentsNextGoCardless

Last updated 4 months ago

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

  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.

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.

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.

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.

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`.

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:

{
  "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

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

Payments requiring validation

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.

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 . When adding customer information, you must:

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 .

If the payment fails, the status of the payment will switch from pending to failed and Swallow will generate a quote.payment_failure .

When a payment requires multi-step authentication, such as 3D Secure (3DS), Swallow triggers a payment.requires_action . 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.

the API
endpoint
webhook
webhook