DOCSEARCHbyAlgolia
Submit Docs

Tilled Documentation

website·Indexed 34 days ago

https://docs.tilled.com

Developer guides and API references for Tilled's payment processing platform. Includes documentation for Payments.js, webhooks, merchant onboarding, bank-to-bank (ACH) payments, card processing, terminal readers, and PCI compliance.

Tokens
37.8K
Snippets
83
Records
240
Agent score
58%

What's inside Tilled

  1. Overview of Manual Batch Close

    A Batch groups captured card transactions to be submitted together for settlement. While batches typically close automatically once per day, enrolled merchants can trigger a Manual Batch Close on demand (e.g., at the end of a business day).

    Constraints:

    • Currently supports card-not-present transactions only.
    • Only available for enrolled merchants. Contact your representative to enable this on a merchant Account.

  2. Interpret Commission Statement v2 reports

    The Commission Statement v2 provides detailed automated calculations across several tabs:

    • Summary: Overview of commissions by payment method and currency.
    • Card: Pivot table of revenue, costs, and net commissions for online and in-person card volume (split by USD and CAD).
    • Bank-to-Bank: Pivot table of revenue, costs, and net commissions for bank-to-bank volume (split by USD and CAD).
    • Transaction Details: Transaction-level calculation details used for auditing and custom analysis.
    • Glossary: Definitions for fields found in the Transaction Details tab.

  3. Understand Card Processing Levels (Level 1, 2, and 3)

    Card payment processing is categorized into three levels based on the amount of data provided. Providing more detailed data can lower interchange fees, particularly for merchants handling commercial credit cards.

    • Level 1: Basic transaction details (amount, date, merchant name). Highest interchange fees.
    • Level 2: Includes Level 1 data plus taxes, customer details, and merchant ZIP code. Lower fees than Level 1.
    • Level 3: Most detailed information, including line-item details, shipping addresses, and invoice numbers. Lowest interchange fees.

  4. Enable printed receipts for customers and merchants

    Enabling printed receipts allows the Tilled terminal to generate physical copies of transaction receipts for both the customer and the merchant, providing a physical proof of purchase for the business and the buyer.

  5. Manage document requests via API or Dashboard

    Merchant document requests can be managed through two primary methods:

    1. Partner Dashboard: A manual interface for uploading and viewing request statuses.
    2. DocumentsAPI: Used to build a custom, automated document management experience within your own application.

  6. Understand how Card Account Updater (CAU) works

    Card Account Updater (CAU) automatically updates expired or replaced credit card information for online payments to reduce disruptions in recurring payments and subscriptions.

    Key Operational Details:

    • Availability: Only available for online payments.
    • Activation: Must be enabled on the account (contact support to enable).
    • Schedule: Stored card details are checked weekly on Mondays. The update process can take up to 3 days.
    • Automation: If an update is found, the card on file is automatically updated with the new details.

  7. Manage merchant preferences via no-code modules

    Merchant preferences can be customized across three primary no-code modules. Note that edit capabilities are restricted to software platform owners and admin users:

    • Onboarding: Tailor the hosted application to the software's vertical.
    • Payments: Restrict merchants from collecting new payments through the Merchant Dashboard.
    • Notifications: Configure default email settings for merchants.

  8. Manage payment disputes in Tilled

    Disputes occur when a customer challenges a payment on their credit card statement due to misunderstandings, unauthorized charges, or dissatisfaction. Merchants can manage these disputes via the Tilled Dashboard or programmatically using the Disputes API.

  9. Understand how Tilled webhooks work

    Tilled uses webhooks to provide real-time notifications for asynchronous events (e.g., ACH debit charge processing, payout notifications, and connected account status changes). Event details are sent in JSON format via a POST request to a designated notification URL. Webhook endpoints are configured at the parent account level to cover events across all connected accounts. Your server must respond with a 200 status code as quickly as possible to acknowledge receipt; any other response is treated as a failure.

  10. Understand the Tilled subscription lifecycle

    A Tilled subscription follows a specific status sequence:

    1. Created with a status of pending.
    2. On the billing_cycle_anchor date, a Payment Intent is created and confirmed.
    3. Upon successful payment, the status updates to active.
    4. The subscription remains active until it reaches the cancel_at date, at which point it becomes canceled.

    If a payment fails, the status changes to past_due. No further payments are attempted until the payment method is updated and the subscription is manually retried.

  11. Understand the Tilled Webhook Event object structure

    Tilled delivers webhook events as EventAPI objects. Each event contains metadata about the event itself and a nested data object containing the full API resource associated with the event (e.g., a charge object for a charge.succeeded event).
    {
 "id": "evt_qLX9Fqyspi8bk0j06yc7s",
 "account_id": "acct_QvlHDyOkQ44HFHsZGs0Gi",
 "type": "payment_intent.succeeded",
 "created_at": "2024-03-12T18:22:41.000Z",
 "updated_at": "2024-03-12T18:22:41.000Z",
 "data": {
  "id": "pi_Hf068QvxJax26OBIKgmw9",
  "status": "succeeded",
  ...
 }
}

  12. Understand PCI DSS compliance requirements for merchants

    All merchants processing credit card payments through TSYS must maintain PCI DSS (Payment Card Industry Data Security Standard) compliance. Even though the payment provider is compliant, merchants must validate their own compliance annually via assessments and certifications. Failure to comply can lead to liability for data breaches, higher transaction fees, monthly fines ($5,000–$100,000), or loss of payment processing abilities.