Onboarding

We pride ourselves on frictionless merchant onboarding -- because your end users should never have to wait to accept payments! Better yet, you can choose from a white-label hosted application or leverage our Tilled API to onboard your merchants -- it's your adventure to choose!

Tilled provides a hosted merchant onboarding form that can be customized to match your brand. If you want to personalize the entire experience, you can do it completely through the Tilled API.

Steps to onboard a merchant

  1. Create a merchant account using the Tilled Console or API.
    • When using the API, be sure to keep track the newly created account_id and the application status wherever you are storing user information to avoid creating duplicate merchant accounts. For more information, see our FAQ on preventing duplicate accounts.
  2. Update merchant application using the API
    • This can be completed before sending the link to the merchant.
    • You also have the ability to share the onboarding form with the Merchant Owner.
      • Go to the Merchants page by clicking on Merchants.
      • Click on the share button.
      • Enter the intended recipient's email address.
      • Click on "Share via email."
  3. Submit the onboarding using the API or hosted onboarding form.
  4. (Optional) Track webhooks of type=account.updated to be informed when a merchant is ready to begin processing.
Tilled allows bank account verification through Plaid. If you would like to test this functionality in the sandbox environment, visit our Testing Plaid Bank Account Verification page.
Create a Merchant Account/v1/accounts/connectedUpdate a MerchantApplication/v1/applications/{account_id}Validation Errors in ResponseSubmit a MerchantApplication/v1/applications/{account_id}/submitYESNOPOSTPUTPOSTMerchant Onboarding Logic

Updating a Merchant's Pricing

It is important to note that this can only be done before the Merchant's Onboarding Application has been submitted. This is only possible for Merchants with a status of created or started.

Currently, updating a merchant's pricing can only be done through the API.

  1. Use the merchant's account_id to make a call to our Get an Account endpoint and obtain the capabilities ID from the response body (capabilities.id).
  2. Retrieve the ID of the new Pricing Template you would like to apply to the merchant using the Get a Pricing Template endpoint.
  3. Delete the merchant's current Pricing Template using the Delete an Account Capability endpoint by passing the ID obtained in Step 1 as a path parameter in your request.
  4. Use the Add an Account Capability endpoint to apply the new Pricing Template by passing the ID of the new Pricing Template that you retrieved in Step 2 as a path parameter.

  1. Create Merchant Account

    • Retrieve Merchant Account ID from Response Body: "id": "acct_*************".

  2. Create a user using the newly created Merchant's ID in the tilled-account header.

    • In the Request Body, specify a email, name, role, and password.

    • After creating the new user, retrieve the User's ID from the Response Body: "id": "user_*************".

  3. Create an Auth Link using the newly created Merchant's ID in the tilled-account header.

    • In the Request Body, specify the following:

      • expiration - This will be the amount of days the Auth Link will be valid for (i.e. 1d, 7d, 30d)

      • user_id - The newly created User's ID for the Merchant.

    • Retrieve the Auth Link key from the Response Body: "id": "*************".

    • Use the Auth Link's key in the Magic Link as show below:

      https://app.tilled.com/auth/magic-link?key=AUTH_LINK_KEY.

      Or use your White Label Domain:

      https://SUBDOMAIN.paymentsonline.io/auth/magic-link?key=AUTH_LINK_KEY

    • Send the link to the person(s) who will be completing the Onboarding Application.

For this process to work, the user must be associated with the Merchant account. Creating a user, rather than an invite, is required for partners that would like to edit the application. This user is solely for use by the partner and can be deleted after the merchant has been onboarded.

Merchant Account Status

Merchant accounts will provide a status which indicates their current state in the onboarding process. These statuses help identify where merchants are in the onboarding journey. You can find these statuses in two places: the capabilities.status property of the Get an Account endpoint or within the same property of the account.updated webhook event.

Onboarding statuses:

  • created: Merchant application has been created in Tilled.
  • started: Merchant has started the merchant application.
  • submitted: Merchant has successfully submitted the merchant application. Awaiting a response from Underwriting.
  • active: Merchant has been approved to process payments. This is the normal status after submitting.
  • disabled: The merchant account has been disabled due to suspension or termination.
  • in_review: The merchant application is under review. Additional documentation may be requested.
  • rejected: The merchant application has been rejected by Underwriting.
  • withdrawn: The merchant application has been withdrawn.
Webhooks can be created via the Tilled Console or through the API. To keep track of the status of new merchant accounts, monitor the account.updated event and the property capabilities.status in the payload.