Link Search Menu Expand Document

Frequently Asked Questions

Find answers to frequently asked questions.

Table of Contents

  1. What is the difference between a charge and a payment intent?
  2. How can I include the Tilled gateway within an iFrame and/or use Tilled.js?
  3. Can I customize the merchant onboarding experience?
  4. I tried using the form method, but I keep receiving this error message: “Uncaught (in promise) TypeError: form.createField is not a function.” What is happening?
  5. What are the different user levels for production/Sandbox?
  6. Are my credentials for sandbox the same as for production?
  7. Is it possible to create a merchant account for a partner in production?
  8. Does Tilled offer tokenization to collect sensitive card or bank account details?
  9. How can I use platform fees to monetize my payments?
  10. What are the required billing details for a payment method?
  11. How can I vault my payment method with Tilled?
  12. How long is a payment method valid?
  13. Can my merchants share payment methods?
  14. Is there an example of Apple Pay?
  15. How can I successfully create an Apple Pay Domain for Tilled verification?
  16. Which countries does Tilled accept for payment processing?
  17. Does Tilled block traffic from any particular cloud service providers?
  18. Is it possible to update the expiration date on credit cards?
  19. Does Tilled have a mobile app (Android / iOS) SDK?
  20. Can merchants be registered with just an SSN rather than a TIN?
  21. How long does it take to process a refund?
  22. Are partial refunds possible on payments that are not batched?
  23. Is it possible to perform more than one capture with the same payment intent?
  24. Is it possible to retrieve customer transactions and reconcile items that are associated with a payout?
  25. What is the simplest way to make test payments?
  26. Are there any account or routing numbers that can be used for testing ACH transfers?
  27. Are there any account numbers,transit numbers or institution ids that can be used for testing ETF transfers?
  28. What are some examples of specific failure codes that we can simulate in Sandbox?
  29. How long does a card settlement or batch take?
  30. Can I use Tilled to place a pre-authorization hold on a payment method?
  31. When does an uncaptured payment intent expire?
  32. How can I change the due date for a subscription?
  33. Are Split Payouts possible?
  34. Does Tilled support OAuth or OAuth 2.0?
  35. Does Tilled have an OCR method to send credit card information?
  36. Does Tilled support 3D Secure?

What is the difference between a charge and a payment intent?

A payment intent represents a payment’s whole lifecycle, from initiation to completion or cancelation. Charges, on the other hand, occur at the singular point in the payment process when a transfer of funds is initiated.

How can I include the Tilled gateway within an iFrame and/or use Tilled.js?

The Tilled.js API Documentation describes how to include a payment form in a partner’s application.

Tilled also offers a Simple Payment Example that incorporates Tilled.js into a website. You can see an example here.

Can I customize the merchant onboarding experience?

You can use Tilled’s Onboarding API to create custom onboarding forms. Tilled provides a GitHub project called Simple Onboarding Form as a roadmap for developers to customize the onboarding experience.

I tried using the form method, but I keep receiving this error message: “Uncaught (in promise) TypeError: form.createField is not a function.” What is happening?

The form method returns a promise rather than a form object. The browser engine is attempting to run createField before the promise has been fulfilled. Therefore, the method is not defined within the call’s execution context. Before you can access the form object’s methods, you must await the call’s return value.

What are the different user levels for production/Sandbox?

When creating a user, Tilled allows partner’s to choose from the following roles:

User RoleDescription
adminBest for business owners and company administrators.
developerBest for developers or people primarily using the Tilled API.
analystBest for people who need full access to Tilled data, but don’t need to update business settings.
view_onlyBest for people who need to view Tilled data, but don’t need to make any updates.
merchant_ownerBest for the business owners of merchants
merchant_adminBest for the company administrators of merchants

Are my credentials for sandbox the same as for production?

No. Your credentials for production will differ from those you used in sandbox. Check that you are not utilizing the sandbox account id for production.

Is it possible to create a merchant account for a partner in production?

Payments can only be processed by merchant/connected accounts, not partner accounts.

As a result, a partner may request to become a merchant on their own account. This is a conceivable circumstance in production, and the partner must be notified that they must be onboarded as a merchant, which is a slightly different process.

Does Tilled offer tokenization to collect sensitive card or bank account details?

Yes, we offer a JavaScript library for tokenizing payments. For more information , see Tilled.js.

How can I use platform fees to monetize my payments?

Tilled allows partners to specify a platform_fee amount when creating a payment intent, which is a fee that is deducted from the user and directed to the partner. Consider it a per-transaction service fee that users pay to partners. Platform fees cannot be greater than the total payment amount less fees.

For example, if a customer makes a $10 payment to a merchant with a platform fee of $1.00, the merchant would receive $9 and the partner would receive $1.00.

Note: For the sake of simplicity, this example ignores the merchant’s pricing.

What are the required billing details for a payment method?

Depending on the type of payment method, different billing information is needed. The table below can be used to check that the information you are passing is accurate.

TypeRequired billing_details
cardzip, country
ach_debitcity, state, street, zip, country
eft_debitcity, state, street, zip, country

How can I vault my payment method with Tilled?

When a payment method is entered into Tilled.js, the raw data passes directly into our vault, and Tilled.js returns a payment token to be passed in a call to our API. Tilled’s documentation may use the terms “vault” and “tokenize” interchangeably.

Note: A vaulted payment method will not persist in our system unless it has been attached to a customer. Please see the question below for more information.

How long is a payment method valid?

When a payment method is created, a created_at and expires_at value will be provided in the response.

A card has a 5-minute validity period, while an ach_debit has a 15-minute validity period. However, payment methods will not expire once they have been attached to a customer, allowing them to be reused in multiple payment intents.

Can my merchants share payment methods?

A customer created at the partner level may use a previously saved payment with any of your merchants.

When you create a customer or make any calls to the payment method endpoints, you must include your partner account id in the header parameters.

Is there an example of Apple Pay?

For code examples please see the PaymentRequest on Tilled.js.

How can I successfully create an Apple Pay Domain for Tilled verification?

You will not register the merchant using your Apple Developer account. We manage the process on our end when you utilize our Domain Verification File. Please follow the steps below to successfully create an Apple Pay domain for Tilled verification on Tilled:

  1. You’ll need an HTTPS-secured domain.
  2. Add Tilled’s Apple Domain Verification File to the /.well-known/apple-developer-merchantid-domain-association path to your domain.
  3. POST /v1/apple-pay-domains with your domain hostname: Example: "hostname": "https://example.com”
  4. You should be able to proceed with the rest of the Apple Pay integration with Tilled.

For code examples please see the PaymentRequest on Tilled.js.

Which countries does Tilled accept for payment processing?

Payments can be processed by any country unless that country is on our banned list. Please reach out to [email protected] for the complete list.

Does Tilled block traffic from any particular cloud service providers?

Tilled accepts traffic from all major, reputable cloud providers. However, we also continuously monitor inbound network traffic for security threats and will block internet traffic from malicious origins as-needed. Currently the only provider we block all traffic from globally is Digital Ocean. If your applications or services are hosted on Digital Ocean, you can provision static outbound IP addresses in your environment and you can provide those to Tilled’s integration support team. We’ll then work with our security team to get your IP addresses allow-listed in our firewalls.

Is it possible to update the expiration date on credit cards?

At the moment, it is not possible to update a credit card’s expiration date.

Does Tilled have a mobile app (Android / iOS) SDK?

Tilled does not currently have any mobile SDKs.

Can merchants be registered with just an SSN rather than a TIN?

If they are a sole proprietor, they should be able to use it. As a general rule, for the following business types:

  • Sole Proprietor/Sole Trader can use their SSN
  • LLC, Corporation, or LLP will need a Federal Tax ID
  • Charity will need 501c3

How long does it take to process a refund?

The status of a refund is typically updated around 7 a.m. ET. Refunds are processed the following business day unless they occurred after 5 p.m. ET.

Are partial refunds possible on payments that are not batched?

A partial refund is not possible until the charge has been batched. Charges from the current batch are processed automatically shortly after midnight ET. We propose that developers either initiate the partial refund after the midnight batch, for example, at 1 AM ET, to verify that all charges from the previous day have been successfully batched or cancel the payment by refunding the full amount and generating a new paymentIntent for the correct amount.

Is it possible to perform more than one capture with the same payment intent?

No, A payment intent can only be captured once even if the amount captured is less than the authorized amount.

Is it possible to retrieve customer transactions and reconcile items that are associated with a payout?

Yes, you will have to request to “List all balance transactions” and pass the payout_id in the query parameters. See the example below:

What is the simplest way to make test payments?

We have included a virtual terminal in our partner console. Simply log in with your credentials, click on the “Developer” tab on the left hand menu, and navigate to the virtual terminal. Please see our Testing page for test card numbers and cvc values to simulate various responses.

Are there any account or routing numbers that can be used for testing ACH transfers?

When creating a payment method in sandbox, a developer may be required to enter ACH account and routing numbers. Routing numbers must be valid ABA routing numbers in order to successfully create the payment method, but any 12-digit number can be passed as an account number.

The following are some examples of well-known routing numbers:

Bank nameABA Routing Number
TD Bank Connecticut011103093
TD Bank Florida067014822
Bank of America011000138
Wells Fargo Bank021101108
HSBC021004823

Are there any account numbers,transit numbers or institution ids that can be used for testing ETF transfers?

Any 5 or 20-digit number can be passed as an account_number or transit_number, but the institution_id must be valid for the payment method to be created successfully. Several well-known transit numbers are listed below:

Bank nameBank Code (or institution number)
Bank of Montreal001
Scotiabank (The Bank of Nova Scotia)002
Royal Bank of Canada003
The Toronto-Dominion Bank004
National Bank of Canada006

What are some examples of specific failure codes that we can simulate in Sandbox?

The following exact amounts will result in the associated error code on a payment intent. This is only accessible for card. Example: 777701 = $7777.01.

AmountsError Code
777701ChargeDeclineCode.INSUFFICIENT_FUNDS
777702ChargeDeclineCode.AVS_CHECK_FAILED
777703ChargeDeclineCode.GENERIC_DECLINE
777704ChargeDeclineCode.CALL_ISSUER
777705ChargeDeclineCode.EXPIRED_CARD
777706ChargeDeclineCode.PICKUP_CARD
777707ChargeDeclineCode.INVALID_NUMBER
777708ChargeDeclineCode.LIMIT_EXCEEDED
777709ChargeDeclineCode.NOT_PERMITTED
777710ChargeDeclineCode.INCORRECT_CVC
777711ChargeDeclineCode.SERVICE_NOT_ALLOWED
777712ChargeDeclineCode.INVALID_EXPIRY
777713ChargeDeclineCode.CARD_NOT_SUPPORTED
777714ChargeDeclineCode.RESTRICTED_CARD
777715ChargeDeclineCode.FRAUDULENT
777716ChargeDeclineCode.PROCESSING_ERROR

How long does a card settlement or batch take?

The batch card settlement process ends a little before midnight EST.

A charge made on Monday at 8 p.m, for example, will be settled Monday night, just before midnight EST.

Can I use Tilled to place a pre-authorization hold on a payment method?

You must create a payment intent with the capture method set to manual to first create a payment intent with a status of requires_capture. From there, you capture it with the Capture a PaymentIntent endpoint.

When does an uncaptured payment intent expire?

Payment intents that have not been captured for seven days will be canceled.

How can I change the due date for a subscription?

The billing_cycle_anchor cannot be changed at any point during the subscription’s lifecycle. Tilled calculates all future payments from the initial date once the first payment is made. If the billing anchor needs to be changed, we recommend canceling the previous subscription and starting over with the new anchor.

Are Split Payouts possible?

Tilled supports split payouts in the form of platform fees attached to a payment intent, enabling split payouts between you, the partner, and the merchant account that generated the payment intent. Tilled does not allow split pay between multiple merchant accounts. For more information see the question on platform fees.

Does Tilled support OAuth or OAuth 2.0?

Tilled supports authentication using JWT. OAuth 2.0 allows for the use of JWTs as Bearer Tokens to encode all relevant aspects of an access token within the access token itself instead of storing them in a database.

Does Tilled have an OCR method to send credit card information?

Although we do not support OCR, there are third party libraries that can be leveraged. For example: card.io or Dyneti.

Does Tilled support 3D Secure?

Tilled does not currently support 3D secure.

Customers must perform an additional verification step with the card issuer when paying with 3D Secure (3DS) for enhanced fraud protection.


Copyright © 2022 Tilled