Trickl

Start here. Without an integration, explains the ways to add Trickl (own business such as a SaaS, or a multi-seller platform) and how to choose. With one, returns a step-by-step plan for the coding agent: keys, exact API calls, webhook handling, what to store, and how to prove it works with this server's sandbox tools.

{
  "type": "object",
  "properties": {
    "integration": {
      "description": "own_*: the user's own business gets paid (SaaS, app, course, membership); own_embedded_checkout puts checkout inside their app. platform_*: many sellers on the user's platform get paid. embedded = in-page iframe, hosted = redirect to Trickl. embed_widget: paste-in pricing widget, no backend. Omit to see the choices.",
      "type": "string",
      "enum": [
        "embed_widget",
        "own_embedded_checkout",
        "own_hosted_checkout",
        "platform_embedded_checkout",
        "platform_hosted_checkout"
      ]
    }
  },
  "additionalProperties": false
}

Keyword search over the Trickl partner docs (platform API, webhooks, embed widget). Returns section ids with snippets; read one with read_doc. Leave query empty for the full table of contents.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "e.g. \"deadline goal\", \"verify signature\", \"REDIRECT_URL_NOT_ALLOWED\"",
      "type": "string"
    }
  },
  "additionalProperties": false
}

Returns one section of the Trickl docs in full (Markdown), by id from search_docs.

{
  "type": "object",
  "properties": {
    "id": {
      "description": "Section id, e.g. \"platform-api/sandbox-test-mode\"",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Confirms this connector's test key works and shows its platform, scopes and mode. Run it before the other sandbox tools; if it fails, the message says what the user needs to fix.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Registers a seller (provider) under the test key via POST /providers/register and returns providerLinkCode (needed to create goals) and webhookSecret (to verify webhooks). Idempotent on externalCreatorId. webhookUrl must be a public https URL that reaches the user's receiver, e.g. an ngrok or cloudflared tunnel to localhost. Sandbox webhooks are real signed HTTP requests.

{
  "type": "object",
  "properties": {
    "webhookUrl": {
      "description": "https URL of the user's webhook receiver",
      "type": "string"
    },
    "externalCreatorId": {
      "description": "The seller's id in the user's app. Default: sandbox-seller-1",
      "type": "string"
    },
    "businessName": {
      "description": "Default: Sandbox Seller",
      "type": "string"
    },
    "email": {
      "description": "Must not belong to an existing Trickl provider. Default: a per-seller @example.com address",
      "type": "string"
    },
    "websiteUrl": {
      "description": "Seller site; its host is allowed for redirects and embedded checkout",
      "type": "string"
    },
    "stripeConnectAccountId": {
      "description": "Leave empty in sandbox: a placeholder is used, since sandbox goals never reach Stripe",
      "type": "string"
    }
  },
  "required": [
    "webhookUrl"
  ],
  "additionalProperties": false
}

Creates a goal with POST /goals/create using the test key. No money moves. Returns goalId, paymentUrl (hosted checkout) and clientSecret (embedded checkout). Amounts are integer cents, USD.

{
  "type": "object",
  "properties": {
    "providerLinkCode": {
      "description": "From register_test_provider",
      "type": "string"
    },
    "targetAmount": {
      "description": "Price in cents, e.g. 2999 = $29.99",
      "type": "integer",
      "minimum": 50,
      "maximum": 9007199254740991
    },
    "description": {
      "description": "What the buyer is saving for, max 500 characters",
      "type": "string"
    },
    "metadata": {
      "description": "Echoed verbatim in every webhook, e.g. { orderId }",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "depositAmount": {
      "description": "Upfront card charge in cents. One-time: ≥ 50 and < targetAmount. Subscription: = targetAmount or omit",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "depositRefundable": {
      "type": "boolean"
    },
    "frequency": {
      "description": "Makes it a recurring subscription; omit for a one-time purchase",
      "type": "string",
      "enum": [
        "WEEKLY",
        "BIWEEKLY",
        "MONTHLY",
        "QUARTERLY",
        "YEARLY"
      ]
    },
    "deadline": {
      "description": "ISO 8601 due date, 24h to 2 years out (one-time goals only)",
      "type": "string"
    },
    "callbackUrl": {
      "description": "Where the buyer returns after confirming; localhost is allowed in test mode",
      "type": "string"
    },
    "cancelUrl": {
      "type": "string"
    },
    "imageUrl": {
      "type": "string"
    }
  },
  "required": [
    "providerLinkCode",
    "targetAmount",
    "description"
  ],
  "additionalProperties": false
}

Returns a sandbox goal's current state via GET /goals/:goalId: status, amounts saved, buyer, deadline.

{
  "type": "object",
  "properties": {
    "goalId": {
      "description": "goalId from create_test_goal",
      "type": "string"
    }
  },
  "required": [
    "goalId"
  ],
  "additionalProperties": false
}

Moves a sandbox goal through its lifecycle instantly; each event sends the real signed webhook to the seller's webhookUrl, exactly as live would. confirm: the buyer signs up and links a bank (goal.deposit_paid if there is a deposit; for subscriptions also goal.subscription_created, plus goal.cycle_paid at once if the deposit paid the first period in full). collect: one round-up chunk, $3 by default (goal.round_up_collected); fails with ALREADY_FUNDED when the current period is already paid. complete: one-time goals finish (goal.completed); subscriptions pay the current period and start the next (goal.cycle_paid; the goal stays SAVING). payment_failed: a failed chunk (goal.payment_failed), with reversal=true for the clawback path. expire: a deadline goal fell short (goal.deadline_charge_failed). Confirm first.

{
  "type": "object",
  "properties": {
    "goalId": {
      "description": "goalId from create_test_goal",
      "type": "string"
    },
    "event": {
      "type": "string",
      "enum": [
        "confirm",
        "collect",
        "complete",
        "payment_failed",
        "expire"
      ]
    },
    "amount": {
      "description": "collect / payment_failed only: cents, default 300",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "reversal": {
      "description": "payment_failed only: true = a chunk already counted is reversed (clawback); false = a collection failed",
      "type": "boolean"
    },
    "reason": {
      "description": "payment_failed with reversal only",
      "type": "string",
      "enum": [
        "ach_return",
        "dispute"
      ]
    }
  },
  "required": [
    "goalId",
    "event"
  ],
  "additionalProperties": false
}

Cancels a sandbox goal via POST /goals/:goalId/cancel, as the user's server would when a customer cancels: collected chunks (and a refundable deposit) are refunded in the ledger only, and goal.cancelled is sent.

{
  "type": "object",
  "properties": {
    "goalId": {
      "description": "goalId from create_test_goal",
      "type": "string"
    }
  },
  "required": [
    "goalId"
  ],
  "additionalProperties": false
}

Shows every webhook Trickl sent for a sandbox goal, newest first, with its payload and the receiver's result. DELIVERED = got a 2xx. FAILED = rejected, retry scheduled at nextRetryAt. EXHAUSTED = gave up. PENDING / DELIVERING = in flight; check again in a few seconds. Use lastStatusCode and lastError to debug the receiver.

{
  "type": "object",
  "properties": {
    "goalId": {
      "description": "goalId from create_test_goal",
      "type": "string"
    }
  },
  "required": [
    "goalId"
  ],
  "additionalProperties": false
}