Tilled

https://docs.tilled.com/
Admin
Tilled is an embedded payments and PayFac-as-a-Service platform that enables software companies to...
Tokens:45,339
Snippets:488
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Full Webhook Verification Example

Source: https://docs.tilled.com/docs/webhooks/how-to-set-up-webhooks

A complete implementation demonstrating header parsing, payload preparation, and signature validation.

```javascript
// Can be found in the webhook payload header
let tilled_signature = "t=1614049713663,v1=8981f5902896f479fa9079eec71fca01e9a065c5b59a96b221544023ce994b02"
// Can be found in the payload
let body = JSON.stringify(webhook.body);

const details = parseHeader(tilled_signature, "v1");

console.log(details);

if (!details || details.timestamp === -1) {
 try {
  throw new Error("Unable to extract timestamp and signature from header")
  console.log("Unable to extract timestamp and signature from header")
 } catch (e) {
  console.log(e.name, e.message);
 }
}

if (!details || details.signature === -1) {
 try {
  throw new Error("No signature found with expected scheme")
  console.log("No signature found with expected scheme")
 } catch (e) {
  console.log(e.name, e.message);
 }
}

let payload = details.timestamp + "." + body;
let expectedSignature = CryptoJS.HmacSHA256(payload, private_key).toString(CryptoJS.enc.Hex);

console.log(expectedSignature);

if(expectedSignature == details.signature) {
 console.log("Signature match with tilled_signature");
}
  
function parseHeader(header, scheme) {
 if (typeof header !== 'string') {
  return null;
 }

 return header.split(',').reduce(
  (accum, item) => {
   const kv = item.split('=');

   if (kv[0] === 't') {
    accum.timestamp = kv[1];
   }

   if (kv[0] === scheme) {
    accum.signature = kv[1];
   }

   return accum;
  },
  {
   timestamp: -1,
   signature: -1,
  }
 );
}
```

--------------------------------

### Account Response Schema

Source: https://docs.tilled.com/api-reference

Example JSON response structure returned when successfully retrieving account information.

```json
{
  "bank_accounts": [
    {
      "account_holder_name": "…",
      "account_id": "…",
      "bank_name": "…",
      "created_at": "2026-08-25T00:07:59.826Z",
      "currency": "aud",
      "default_for_currency": true,
      "id": "…",
      "last4": "…",
      "routing_number": "…",
      "status": "new",
      "type": "checking",
      "updated_at": "2026-08-25T00:07:59.826Z"
    }
  ],
  "business_profile": {
    "address": {
      "city": "…",
      "country": "…",
      "created_at": "2026-08-25T00:07:59.826Z",
      "id": "…",
      "postal_code": "…",
      "state": "…",
      "street": "…",
      "street2": "…",
      "updated_at": "2026-08-25T00:07:59.826Z"
    },
    "category": "ACCT",
    "created_at": "2026-08-25T00:07:59.826Z",
    "id": "…",
    "legal_name": "…",
    "locale": "en_US",
    "phone": "…",
    "region": "US",
    "representatives": [
      {
        "addresses": [
          {
            "city": "…",
            "country": "…",
            "created_at": "2026-08-25T00:07:59.826Z",
            "id": "…",
            "postal_code": "…",
            "state": "…",
            "street": "…",
            "street2": "…",
            "updated_at": "2026-08-25T00:07:59.826Z"
          }
        ],
        "created_at": "2026-08-25T00:07:59.826Z",
        "email": "…",
        "first_name": "…",
        "id": "…",
        "is_applicant": true,
        "is_control_prong": true,
        "job_title": "…",
        "last_name": "…",
        "middle_name": "…",
        "phone": "…",
        "type": "director",
        "updated_at": "2026-08-25T00:07:59.826Z"
      }
    ],
    "structure": "CHARITY",
    "tax_identification_number": "…",
    "updated_at": "2026-08-25T00:07:59.826Z",
    "website": "…"
  },
  "capabilities": [
    {
      "attributes": {
        "esignature": {
          "document": {
            "id": "…",
            "status": "sent"
          },
          "signers": [
            {
              "email": "…",
              "embedded": true,
              "esignature_document_id": "…",
              "id": "…",
              "name": "…",
              "status": "sent"
            }
          ]
        }
      },
      "id": "…",
      "onboarding_application_progress": 1,
      "onboarding_application_url": "…",
      "pricing_template": {
        "account_id": "…",
        "account_monthly_fee": 1,
        "account_monthly_minimum_fee": 1,
        "ach_debit": {
          "return_fee": 1,
          "transaction_fee": 1,
          "transaction_fee_type": "flat_rate"
        },
        "card": {
          "bank_account_change_fee": 1,
          "card_update_fee": 1,
          "chargeback_fee": 1,
          "markups": [
            {
              "card_type": "amex",
              "rate": 1
            }
          ],
          "pci_fee_details": {
            "monthly_pci_compliance_fee": 1,
            "non_pci_validation_fee": 1,
            "pci_annual_fee": 1,
            "pci_owner": "PROCESSOR"
          },
          "retrieval_fee": 1,
          "reversal_fee": 1,
          "transaction_fee": 1,
          "transaction_fee_type": "flat_rate"
        },
        "card_present": {
          "bank_account_change_fee": 1,
          "chargeback_fee": 1,
          "markups": [
            {
              "card_type": "amex",
              "rate": 1
            }
          ],
          "monthly_terminal_fee": 1,
          "pci_fee_details": {
            "monthly_pci_compliance_fee": 1,
            "non_pci_validation_fee": 1,
            "pci_annual_fee": 1,
            "pci_owner": "PROCESSOR"
          },
          "retrieval_fee": 1,
          "reversal_fee": 1,
          "transaction_fee": 1,
          "transaction_fee_type": "flat_rate"
        },
        "created_at": "2026-08-25T00:07:59.826Z",
        "currency": "aud"
```

--------------------------------

### Create a Payment Request Button Field

Source: https://docs.tilled.com/docs/resources/error-codes

Example of initializing a payment request button field with the required paymentRequest attribute.

```javascript
var prButton = form.createField('paymentRequestButton', { paymentRequest: paymentRequest, });
```

--------------------------------

### Sample payment_intent.succeeded event payload

Source: https://docs.tilled.com/docs/webhooks/webhook-events

Example of the JSON structure for a successful payment intent webhook event.

```json
{
 "id": "evt_qLX9Fqyspi8bk0j06yc7s",
 "account_id": "acct_QvlHDyOkQ44HFHsZGs0Gi",
 "type": "payment_intent.succeeded",
 "data": {
  "id": "pi_Hf068QvxJax26OBIKgmw9",
  "status": "succeeded",
  ...
 }
}
```

--------------------------------

### GET /v1/accounts

Source: https://docs.tilled.com/api-reference

Retrieves the details of an existing Account.

```APIDOC
## GET /v1/accounts

### Description
Retrieves the details of an existing Account.

### Method
GET

### Endpoint
/v1/accounts

### Parameters
#### Headers
- **Tilled-Account** (string) - Required - The id of the Tilled Account (usually starting with the prefix acct_) that the request is performed on behalf of.

### Response
#### Success Response (200)
- **bank_accounts** (array) - List of bank accounts associated with the account.
- **business_profile** (object) - The business profile details including address, legal name, and representatives.
- **capabilities** (array) - List of capabilities enabled for the account.

#### Response Example
{
  "bank_accounts": [
    {
      "account_holder_name": "…",
      "account_id": "…",
      "bank_name": "…",
      "created_at": "2026-08-25T00:07:59.826Z",
      "currency": "aud",
      "default_for_currency": true,
      "id": "…",
      "last4": "…",
      "status": "new",
      "type": "checking"
    }
  ],
  "business_profile": {
    "legal_name": "…",
    "website": "…"
  },
  "capabilities": []
}
```

--------------------------------

### GET /v1/charges/{id}

Source: https://docs.tilled.com/api-reference

Retrieves details for a specific charge.

```APIDOC
## GET /v1/charges/{id}

### Description
A Charge represents money moving into an Account. This endpoint retrieves the details of a specific charge.
```

--------------------------------

### Create a Subscription with Surcharge

Source: https://docs.tilled.com/docs/payments/card/surcharging

Initiate a subscription with surcharging enabled, which sets the initial status to requires_confirmation.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/subscriptions' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "customer_id": "cus_xxxx",
      "payment_method_id": "pm_xxxx",
      "price_id": "price_xxxx",
      "apply_surcharge": true
    }'
```

--------------------------------

### GET /v1/batches

Source: https://docs.tilled.com/docs/payments/card/manual-batch-close

Retrieves a list of batches for a merchant, with optional filtering.

```APIDOC
## GET /v1/batches

### Description
Retrieve the current set of batches for a merchant.

### Method
GET

### Endpoint
https://sandbox-api.tilled.com/v1/batches

### Parameters
#### Query Parameters
- **status** (Enum) - Optional - One of open, closing, closed, or failed.
- **opened_at_gte** (ISO 8601 timestamp) - Optional - Include only batches opened on or after this timestamp.
- **opened_at_lte** (ISO 8601 timestamp) - Optional - Include only batches opened on or before this timestamp.
- **offset** (Integer) - Optional - Zero-based offset of the first item to return. Defaults to 0.
- **limit** (Integer) - Optional - Maximum number of items to return. Defaults to 30; capped at 100.

### Response
#### Success Response (200)
- **items** (array) - List of batch objects.
- **total** (Integer) - Total number of batches.
- **offset** (Integer) - Current offset.
- **limit** (Integer) - Current limit.

#### Response Example
{
  "items": [
    {
      "id": "bch_01HXYZGHI...",
      "account_id": "acct_...",
      "status": "open",
      "opened_at": "2026-07-15T13:00:00.000Z",
      "cutoff_at": "2026-07-15T23:59:59.000Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 30
}
```

--------------------------------

### Create a Subscription

Source: https://docs.tilled.com/docs/payments/collect-a-payment/subscriptions

Initialize a subscription by specifying billing cycle details, customer, and payment method. Billing cycles cannot be modified after creation.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/subscriptions' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "billing_cycle_anchor": "2024-07-04",
      "currency": "usd",
      "customer_id":  “{{CUSTOMER_ID}}”,
      "interval_count": 1,
      "interval_unit": "week",
      "metadata": {
        "order_id": "100123",
        "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
      },
      "payment_method_id": "{{PAYMENT_METHOD_ID}}",
      "platform_fee_amount": 500,
      "price": 10000
    }'
```

--------------------------------

### GET /v1/accounts

Source: https://docs.tilled.com/api-reference

Retrieves information about a specific account. Requires the tilled-account header.

```APIDOC
## GET /v1/accounts

### Description
Retrieves information about an account.

### Method
GET

### Endpoint
/v1/accounts

### Parameters
#### Headers
- **tilled-account** (string) - Required - The account identifier.
```

--------------------------------

### Tilled Initialization

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Instantiate the Tilled SDK using your publishable API key and account ID.

```APIDOC
## new Tilled(publishableKey, accountId, options)

### Description
Initializes the Tilled SDK instance.

### Parameters
- **publishableKey** (string) - Required - Your publishable API key.
- **accountId** (string) - Required - Your account ID.
- **options** (object) - Optional - Additional settings.
  - **sandbox** (boolean) - Optional - Indicates whether to use the sandbox environment (default: false).
```

--------------------------------

### GET /v1/events

Source: https://docs.tilled.com/docs/webhooks/overview

Retrieves a list of events, optionally filtered by their delivery status.

```APIDOC
## GET /v1/events

### Description
Retrieves a list of events. You can filter the results based on the delivery status of the events.

### Method
GET

### Endpoint
/v1/events

### Parameters
#### Query Parameters
- **delivery_status** (string) - Optional - Filter events by status: 'succeeded', 'failed', 'pending', or 'undelivered'.

### Request Example
GET /v1/events?delivery_status=undelivered
```

--------------------------------

### Onboarding API

Source: https://docs.tilled.com/api-reference

Endpoints for managing merchant applications and onboarding processes.

```APIDOC
## GET /v1/applications/{account_id}
## PUT /v1/applications/{account_id}
## POST /v1/applications/{account_id}/submit
## GET /v1/onboarding
## POST /v1/onboarding
## GET /v1/onboarding/esignature/{document_id}/signer/{id}
## POST /v1/onboarding/esignature/{document_id}/signer/{id}/resend
## GET /v1/onboarding/mcc
## POST /v1/onboarding/signing-links
## POST /v1/onboarding/submit
```

--------------------------------

### GET /v1/batches/{{BATCH_ID}}

Source: https://docs.tilled.com/docs/payments/card/manual-batch-close

Retrieves the details of a specific batch by its unique identifier.

```APIDOC
## GET /v1/batches/{{BATCH_ID}}

### Description
Look up a single batch by its ID.

### Method
GET

### Endpoint
https://sandbox-api.tilled.com/v1/batches/{{BATCH_ID}}

### Parameters
#### Path Parameters
- **BATCH_ID** (string) - Required - The unique identifier of the batch.

### Response
#### Success Response (200)
- **id** (string) - The batch ID.
- **account_id** (string) - The merchant account ID.
- **status** (string) - The status of the batch.
- **opened_at** (string) - ISO 8601 timestamp when the batch was opened.
- **close_requested_at** (string) - ISO 8601 timestamp when the close was requested.
- **closed_at** (string) - ISO 8601 timestamp when the batch was closed.
- **cutoff_at** (string) - ISO 8601 timestamp for the batch cutoff.

#### Response Example
{
  "id": "bch_01HXYZGHI...",
  "account_id": "acct_...",
  "status": "closed",
  "opened_at": "2026-07-15T13:00:00.000Z",
  "close_requested_at": "2026-07-15T18:30:00.000Z",
  "closed_at": "2026-07-15T18:30:03.000Z",
  "cutoff_at": "2026-07-15T23:59:59.000Z"
}
```

--------------------------------

### Tilled SDK Initialization and Payment Confirmation

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

This section covers initializing the Tilled instance, creating payment forms for different methods, and confirming payments.

```APIDOC
## Tilled SDK Methods

### Tilled(publicKey, accountId)
Initializes the Tilled SDK instance.

### form(options)
Creates a payment form instance. 
- **payment_method_type**: (string) The type of payment method (e.g., 'card', 'ach_debit').

### form.createField(type, options)
Creates a specific payment field (e.g., 'cardNumber', 'bankAccountNumber').

### form.inject(selector)
Injects the created field into the specified DOM element.

### form.build()
Builds the form instance.

### tilled.confirmPayment(clientSecret, data)
Confirms a payment using the client secret and payment details.
```

--------------------------------

### GET /v1/terminal-readers/{{TERMINAL_ID}}

Source: https://docs.tilled.com/docs/payments/collect-a-payment/in-person-payments

Retrieves details for a specific terminal reader associated with the merchant's account.

```APIDOC
## GET /v1/terminal-readers/{{TERMINAL_ID}}

### Description
Retrieves the details of a specific terminal reader linked to the merchant's account.

### Method
GET

### Endpoint
https://sandbox-api.tilled.com/v1/terminal-readers/{{TERMINAL_ID}}

### Parameters
#### Path Parameters
- **TERMINAL_ID** (string) - Required - The unique identifier of the terminal reader.
```

--------------------------------

### Initialize Tilled.js

Source: https://docs.tilled.com/docs/payments/card/applepay

Create an instance of the Tilled object using your publishable API key and merchant account ID.

```javascript
const tilled = new Tilled('pk_…', 'acct_…');
```

--------------------------------

### Create a Connected Account

Source: https://docs.tilled.com/api-reference

Use this cURL command to initiate the creation of a new connected account. Ensure the Tilled-Account header is populated with the appropriate parent account ID.

```bash
curl https://sandbox-api.tilled.com/v1/accounts/connected \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Tilled-Account: ' \
  --data '{
  "name": "Merchant Account",
  "email": "merchant@email.test"
}'
```

--------------------------------

### Initialize EFT bank account form

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Configures and injects bank account and routing number fields into the DOM, then handles payment confirmation.

```javascript
/**
 * Example assumptions:
 * The eft_debit fields have divs defined in the DOM
 * <div id="bank-account-number-element"></div>
 * <div id="bank-routing-number-element"></div>
 *
 * A submit button is defined
 * <button id='submit-btn'></button>
 */
const tilled = new Tilled("pk_…", "acct_…");

const form = await tilled.form({
  payment_method_type: "eft_debit",
});

const fieldOptions = {
  styles: {
    base: {
      fontFamily: "Helvetica Neue, Arial, sans-serif",
      color: "#304166",
      fontWeight: "400",
      fontSize: "16px",
    },
    invalid: {
      ":hover": {
        textDecoration: "underline dotted red",
      },
    },
    valid: {
      color: "#00BDA5",
    },
  },
};

form
  .createField("bankAccountNumber", fieldOptions)
  .inject("#bank-account-number-element");
form
  .createField("bankRoutingNumber", fieldOptions)
  .inject("#bank-routing-number-element");

await form.build();

const submitButton = document.getElementById("submit-btn");
submitButton.on("click", () => {
  // A payment intent will be created on your backend server and the
  // payment_intent.client_secret will be passed to your frontend to
  // be used below.
  tilled
    .confirmPayment(paymentIntentClientSecret, {
      payment_method: {
        billing_details: {
          name: "John Doe",
          address: {
            street: "350 Wellington St",
            city: "Ottawa",
            state: "ON",
            zip: "K1A 0N1",
            country: "CA",
          },
        },
        eft_debit: {
          account_holder_name: "John Doe",
        },
      },
    })
    .then(
      (paymentIntent) => {
        // Be sure to check the `status` and/or `last_payment_error`
        // properties to know if the charge was successful
        if (
          paymentIntent.status === "succeeded" ||
          paymentIntent.status === "processing"
        ) {
          alert("Payment successful");
        } else {
          const errMsg = paymentIntent.last_payment_error?.message;
          alert("Payment failed: " + errMsg);
        }
      },
      (err) => {
        // Typically an error with the request (>400 status code)
      }
    );
});
```

--------------------------------

### Create a Payment Intent with Surcharge

Source: https://docs.tilled.com/docs/payments/card/surcharging

Initiate a payment intent with the apply_surcharge flag set to true to automatically calculate and add the surcharge.

```bash
curl -L 'https://sandbox-api.tilled.com/v1/payment-intents' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "amount": 10000,
      "currency": "usd",
      "payment_method_types": ["card"],
      "payment_method_id": "pm_xxxx",
      "apply_surcharge": true
    }'
```

--------------------------------

### form()

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Creates a form instance to act as a container for payment fields.

```APIDOC
## tilled.form(options)

### Description
Initializes a main Form instance for adding payment fields.

### Parameters
- **options** (object) - Required
  - **payment_method_type** (string) - Required - Specifies 'card' or 'ach_debit' (default: 'card').
```

--------------------------------

### Create a Payment Method

Source: https://docs.tilled.com/docs/payments/collect-a-payment/subscriptions

Create a new payment method object to be used for future subscription charges.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/payment-methods' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "type": "card",
      "card": {
          "number": "4111111111111111",
          "exp_month": 12,
          "exp_year": 2031,
          "cvc": "123"
      },
      "billing_details": {
          "address": {
              "zip": "33139"
          }
      }
  }'
```

--------------------------------

### Create a Tilled Form

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Initialize the main form container for payment fields.

```javascript
const form = await tilled.form({ payment_method_type: 'card' });
```

--------------------------------

### Initialize Credit Card Payment Form

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Configures and injects credit card fields into the DOM and handles payment confirmation.

```javascript
/* Example assumptions:
* The card fields have divs defined in the DOM
* <div id="card-number-element"></div>
* <div id="card-expiration-element"></div>
* <div id="card-cvv-element"></div>
* A submit button is defined
* <button id='submit-btn'></button>
*/
const tilled = new Tilled('pk_...', 'acct_...');
const form = await tilled.form({
  payment_method_type: 'card',
});
const fieldOptions = {
  styles: {
    base: {
      fontFamily: 'Helvetica Neue, Arial, sans-serif',
      color: '#304166',
      fontWeight: '400',
      fontSize: '16px',
    },
    invalid: {
      \':hover\': {
        textDecoration: 'underline dotted red',
      },
    },
    valid: {
      color: '#00BDA5',
    },
  },
};
form.createField('cardNumber', fieldOptions).inject('#card-number-element');
form.createField('cardExpiry', {...fieldOptions, selector: '#card-expiration-element'});
form.createField('cardCvv', fieldOptions).inject('#card-cvv-element');
await form.build();
const submitButton = document.getElementById('submit-btn');
submitButton.onclick = () => {
  tilled.confirmPayment(paymentIntentClientSecret, {
    payment_method: {
      billing_details: {
        name: 'John Doe',
        address: {
          zip: '80021',
          country: 'US',
        },
      },
    },
  })
  .then((paymentIntent) => {
    if (paymentIntent.status === 'succeeded') {
      alert('Payment successful');
    } else {
      const errMsg = paymentIntent.last_payment_error?.message;
      alert('Payment failed: ' + errMsg);
    }
  })
  .catch((error) => {
    alert('An error occurred: ' + error.message);
  });
```

--------------------------------

### POST /v1/accounts/capabilities/{id}

Source: https://docs.tilled.com/api-reference

Updates an existing Account capability. This operation is only permitted before the onboarding application is submitted.

```APIDOC
## POST /v1/accounts/capabilities/{id}

### Description
Updates an Account capability. Account capabilities can only be managed before the onboarding application is submitted.

### Method
POST

### Endpoint
/v1/accounts/capabilities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required

#### Headers
- **tilled-account** (string) - Required - The id of the Tilled Account (usually starting with the prefix acct_) that the request is performed on behalf of.

#### Request Body
- **pricing_template_id** (string) - Required - The PricingTemplate id defining the capability to add to the account. Merchant accounts may only have 1 capability per payment_method_type.

### Response
#### Success Response (201)
```

--------------------------------

### POST /v1/subscriptions

Source: https://docs.tilled.com/docs/payments/card/surcharging

Creates a new subscription with surcharging enabled.

```APIDOC
## POST /v1/subscriptions

### Description
Creates a new subscription. To apply a surcharge, set the apply_surcharge field to true.

### Method
POST

### Endpoint
https://sandbox-api.tilled.com/v1/subscriptions

### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **payment_method_id** (string) - Required - The ID of the payment method.
- **price_id** (string) - Required - The ID of the price.
- **apply_surcharge** (boolean) - Optional - Whether to apply a surcharge to the subscription.

### Request Example
{
  "customer_id": "cus_xxxx",
  "payment_method_id": "pm_xxxx",
  "price_id": "price_xxxx",
  "apply_surcharge": true
}
```

--------------------------------

### Create a Customer

Source: https://docs.tilled.com/docs/payments/collect-a-payment/subscriptions

Use this request to create a new customer record with personal details and metadata.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/customers' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "email": "test@email.test",
      "first_name": "Jane",
        "middle_name": "Andrea",
      "last_name": "Doe",
      "metadata": {
        "order_id": "100123",
        "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
      },
      "phone": "1234567890"
    }'
```

--------------------------------

### POST /v1/auth-links

Source: https://docs.tilled.com/api-reference

Creates an Auth Link to provide access to a partner or merchant account.

```APIDOC
## POST /v1/auth-links

### Description
Creates an Auth Link to provide access to a partner or merchant Account through an authentication encoded URL.

### Method
POST

### Endpoint
/v1/auth-links
```

--------------------------------

### Confirm the Subscription

Source: https://docs.tilled.com/docs/payments/card/surcharging

Activate a subscription after obtaining customer consent for the surcharge details.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/subscriptions/sub_xxxx/confirm' \
    -X POST \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'tilled-api-key: {{SECRET_KEY}}'
```

--------------------------------

### Create a Subscription for a One-Time Payment

Source: https://docs.tilled.com/docs/payments/collect-a-payment/subscriptions

Use this request to schedule a payment by defining the billing cycle anchor and setting the cancellation date to one day after the anchor.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/subscriptions' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "billing_cycle_anchor": "2024-07-04",
      "cancel_at": "2025-07-05",
      "currency": "usd",
      "customer_id":  “{{CUSTOMER_ID}}”,
      "interval_count": 1,
      "interval_unit": "week",
      "metadata": {
        "order_id": "100123",
        "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
      },
      "payment_method_id": "{{PAYMENT_METHOD_ID}}",
      "platform_fee_amount": 500,
      "price": 10000
    }'
```

--------------------------------

### Create a Payment Intent

Source: https://docs.tilled.com/docs/payments/collect-a-payment/payment-intents

Initializes a payment intent by specifying the amount, currency, and payment method type.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/payment-intents' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
      "amount": 1000,
      "currency": "usd",
      "payment_method_types": [
        "card"
      ],
      "confirm": true,
      "payment_method_id": "{{PAYMENT_METHOD_ID}}"
              }'
```

--------------------------------

### Tilled(publicKey, accountId)

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Initializes the Tilled SDK instance with your public key and account ID.

```APIDOC
## Tilled(publicKey, accountId)

### Description
Initializes the Tilled SDK instance.

### Parameters
- **publicKey** (string) - Required - Your Tilled public key.
- **accountId** (string) - Required - Your Tilled account ID.
```

--------------------------------

### Documents

Source: https://docs.tilled.com/api-reference

Endpoints for uploading and managing files for compliance and onboarding.

```APIDOC
## GET /v1/documents
## POST /v1/documents/bulk-submit
## GET /v1/documents/{id}
## POST /v1/documents/{id}/submit
```

--------------------------------

### Implement Apple Pay with Tilled.js

Source: https://docs.tilled.com/docs/sdks-applications/tilledjs

Sets up a payment request button for native payment methods and handles the payment method event.

```javascript
/**
 * Example assumptions:
 * The paymentRequestButton field has a div defined in the DOM
 * <div id="native-payment-element"></div>
 *
 */
const form = tilled.form({
	payment_method_type: 'card',
});

const paymentRequest = tilled.paymentRequest({
	total: {
		label: 'Tilled tee',
		amount: secretData.amount,
	},
});

const prButton = form.createField('paymentRequestButton', {
	paymentRequest: paymentRequest,
});

paymentRequest.canMakePayment().then((result) => {
	if (result) {
		prButton.inject('#native-payment-element');
	} else {
		document.getElementById('native-payment-element').style.display = 'none';
	}
});

paymentRequest.on('paymentmethod', (ev) => {
	let paymentMethod = ev.paymentMethod;
	tilled
		.confirmPayment(paymentIntentClientSecret, {
			payment_method: paymentMethod.id,
		})
		.then(
			(paymentIntent) => {
				// The payment intent confirmation occurred, but the
				// actual charge may still have failed. Check
				if (
					paymentIntent.status === 'succeeded' ||
					paymentIntent.status === 'processing'
				) {
					ev.complete('success');
					alert('Successul payment');
				} else {
					ev.complete('fail');
					const errMsg = paymentIntent.last_payment_error?.message;
					alert('Payment failed: ' + errMsg);
				}
			},
			(err) => {
				ev.complete('fail');
			}
		);
});
```

--------------------------------

### POST /v1/accounts/connected

Source: https://docs.tilled.com/api-reference

Creates a connected Account associated with your partner/parent Account.

```APIDOC
## POST /v1/accounts/connected

### Description
Creates a connected Account associated with your partner/parent Account.

### Method
POST

### Endpoint
/v1/accounts/connected

### Parameters
#### Headers
- **Tilled-Account** (string) - Required - The id of the Tilled Account (usually starting with the prefix acct_) that the request is performed on behalf of.

#### Request Body
- **name** (string) - Required - The name of the merchant account.
- **email** (string) - Required - The email address for the merchant account.

### Request Example
{
  "name": "Merchant Account",
  "email": "merchant@email.test"
}

### Response
#### Success Response (201)
- **bank_accounts** (array) - List of bank accounts associated with the account.
- **business_profile** (object) - The business profile details of the account.
- **capabilities** (array) - The capabilities enabled for the account.

#### Response Example
{
  "bank_accounts": [],
  "business_profile": {},
  "capabilities": []
}
```

--------------------------------

### POST /v1/checkout/sessions

Source: https://docs.tilled.com/docs/payments/card/surcharging

Creates a new checkout session with surcharging enabled.

```APIDOC
## POST /v1/checkout/sessions

### Description
Creates a checkout session with surcharging enabled by including the apply_surcharge flag in the payment_intent_data.

### Method
POST

### Endpoint
https://sandbox-api.tilled.com/v1/checkout/sessions

### Request Body
- **payment_intent_data** (object) - Required - Contains payment intent details including surcharging configuration.
  - **amount** (integer) - Required - The amount in cents.
  - **currency** (string) - Required - The currency code.
  - **payment_method_types** (array) - Required - List of allowed payment methods.
  - **apply_surcharge** (boolean) - Optional - Set to true to apply a surcharge to the transaction.

### Request Example
{
  "payment_intent_data": {
    "amount": 10000,
    "currency": "usd",
    "payment_method_types": ["card"],
    "apply_surcharge": true
  }
}
```

--------------------------------

### POST /v1/subscriptions

Source: https://docs.tilled.com/docs/payments/collect-a-payment/subscriptions

Creates a new subscription for a customer with a specified payment method and billing cycle.

```APIDOC
## POST /v1/subscriptions

### Description
Creates a new subscription. Billing cycles cannot be edited after creation.

### Method
POST

### Endpoint
https://sandbox-api.tilled.com/v1/subscriptions

### Request Body
- **billing_cycle_anchor** (string) - Required - The date to start the billing cycle.
- **currency** (string) - Required - The currency code (e.g., usd).
- **customer_id** (string) - Required - The ID of the customer.
- **interval_count** (integer) - Required - The number of intervals.
- **interval_unit** (string) - Required - The unit of the interval (e.g., week).
- **metadata** (object) - Optional - Key-value pairs for internal tracking.
- **payment_method_id** (string) - Required - The ID of the payment method.
- **platform_fee_amount** (integer) - Optional - The fee amount for the platform.
- **price** (integer) - Required - The price of the subscription.

### Request Example
{
  "billing_cycle_anchor": "2024-07-04",
  "currency": "usd",
  "customer_id": "{{CUSTOMER_ID}}",
  "interval_count": 1,
  "interval_unit": "week",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "payment_method_id": "{{PAYMENT_METHOD_ID}}",
  "platform_fee_amount": 500,
  "price": 10000
}
```

--------------------------------

### Create a Payment Method

Source: https://docs.tilled.com/docs/payments/collect-a-payment/payment-intents

Registers a payment method by providing card details and billing information. Note that using this endpoint requires an Attestation of Compliance.

```curl
curl -L 'https://api.tilled.com/v1/payment-methods' \
              -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
              -H 'Content-Type: application/json' \
              -H 'tilled-api-key: {{SECRET_KEY}}' \
              -d '{
                "type": "card",
                "card": {
                    "number": "4111111111111111",
                    "exp_month": 12,
                    "exp_year": 2031,
                    "cvc": "123"
                },
                "billing_details": {
                    "address": {
                        "zip": "33139"
                    }
                }
            }'
```

--------------------------------

### Create a Payment Intent

Source: https://docs.tilled.com/docs/payments/collect-a-payment/in-person-payments

Initiate a payment intent for a card-present transaction by specifying the payment_method_id.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/payment-intents' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
    "amount": 1000,
    "currency": "usd",
    "payment_method_types": [
      "card_present"
    ],
    "confirm": true,
    "capture_method": "automatic",
    "payment_method_id": "{{PAYMENT_METHOD_ID}}"
    }'
```

--------------------------------

### Create a Card-Present Payment Method

Source: https://docs.tilled.com/docs/payments/collect-a-payment/in-person-payments

Create a payment method with type set to card_present and the terminal_reader_id of the device.

```curl
curl -L 'https://sandbox-api.tilled.com/v1/payment-methods' \
    -H 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'tilled-api-key: {{SECRET_KEY}}' \
    -d '{
    "type": "card_present",
    "terminal_reader_id": "{{TERMINAL_READER_ID}}"
  }'
```

--------------------------------

### DELETE /v1/accounts/capabilities/{id}

Source: https://docs.tilled.com/api-reference

Deletes an existing Account capability. This operation is only permitted before the onboarding application is submitted.

```APIDOC
## DELETE /v1/accounts/capabilities/{id}

### Description
Deletes an Account capability. Account capabilities can only be managed before the onboarding application is submitted.

### Method
DELETE

### Endpoint
/v1/accounts/capabilities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required

#### Headers
- **tilled-account** (string) - Required - The id of the Tilled Account (usually starting with the prefix acct_) that the request is performed on behalf of.

### Response
#### Success Response (204)
```

--------------------------------

### POST /v1/payment-intents

Source: https://docs.tilled.com/docs/payments/collect-a-payment/in-person-payments

Initiates a payment intent for a card-present transaction, which triggers the terminal to prompt the customer for payment.

```APIDOC
## POST /v1/payment-intents

### Description
Creates a payment intent to process an in-person payment. Confirming the intent sends the request to the terminal.

### Method
POST

### Endpoint
https://sandbox-api.tilled.com/v1/payment-intents

### Request Body
- **amount** (integer) - Required - The payment amount.
- **currency** (string) - Required - The currency code (e.g., "usd").
- **payment_method_types** (array) - Required - List containing "card_present".
- **confirm** (boolean) - Required - Set to true to confirm the intent.
- **capture_method** (string) - Required - The capture method, e.g., "automatic".
- **payment_method_id** (string) - Required - The ID of the payment method created previously.

### Request Example
{
  "amount": 1000,
  "currency": "usd",
  "payment_method_types": ["card_present"],
  "confirm": true,
  "capture_method": "automatic",
  "payment_method_id": "{{PAYMENT_METHOD_ID}}"
}
```
Tokens:
Raw