Tillify Connect for till and platform providers

Redirect the user's browser to:

GET https://www.tillify.nz/api/v1/connect/start
  ?partner_key=pk_…
  &redirect_uri=https://your-app.example/tillify/callback
  &state=<random value you store against the user's session>

All three parameters are required, and state can be up to 500 characters. redirect_uri must exactly match one you registered. If the link is invalid, we respond 400 with a JSON error and don't redirect.

The user signs in or creates a Tillify account, then confirms their business, or creates one and adds the bank account payments go to. The link is valid for 60 minutes and can only be completed by the first person who opens it.

We send the user back to your redirect_uri:

Always check that state matches the one you stored for this user before using the setup_token. That's what stops someone completing Connect for their own business and attaching it to your user.

Within 5 minutes:

POST https://www.tillify.nz/api/v1/connect/exchange
X-Partner-Key: pk_…
Authorization: Bearer ps_…
Content-Type: application/json

{
  "setup_token": "tok_…",
  "webhook_url": "https://your-app.example/webhooks/tillify",  // Optional, https only
  "external_user_id": "your-user-123"                          // Optional, for support
}

Response:

{
  "client_id": "live_…",
  "client_secret": "sk_live_…",
  "webhook_secret": "whsec_…",
  "business": { "id": "…", "name": "Harbour Street Bakery" },
  "payments_enabled": true,
  "reason": null
}

• The client_secret is only ever returned here. Store it encrypted.
• A Setup token works once, and expires after 5 minutes. See errors for what each failure returns.
• If the business connects your product again (for example, you lost the keys), the new exchange returns the same client_id with a new secret. The old secret keeps working until that exchange succeeds, then stops. A different webhook_url is added alongside the old one.
• payments_enabled can be false straight after Connect, most often because a bank account entered by hand is being checked (reason: "bank_account_pending", usually about an hour). Other reasons: no_bank_account, business_inactive, suspended_unpaid_fees. Poll GET /api/v1/account to find out when payments are enabled.
• The business owner can see and revoke your credentials in Tillify under Integrations. Revoked credentials return 401.

Authenticate every call with the business's credentials:

Authorization: Bearer <client_secret>
X-Client-Id: <client_id>

Create a payment

POST https://www.tillify.nz/api/v1/payments
{
  "amount": 1000,                 // Cents, before any fee the business passes on
  "currency": "NZD",
  "external_order_id": "till-42", // Optional, your reference
  "success_url": "https://…",     // Optional: leave out on a till
  "cancel_url": "https://…"       // Optional
}

{
  "checkout_url": "https://www.tillify.nz/pay/cs_…",
  "checkout_session_id": "cs_…",
  "status": "pending",
  "currency": "NZD",
  "amount": 1000,
  "total": 1035
}

• On a till, show checkout_url as a QR code and leave out success_url. The customer pays on their phone and sees a payment-confirmed page.
• Online, redirect the customer to checkout_url. They're sent to success_url after paying.
• Display total, not amount. If the business passes fees on, total includes the Pay by Bank fee. A customer who chooses card sees the card total on the checkout page.

Check a payment

GET /api/v1/payments/{checkout_session_id} returns status (pending, completed, failed, cancelled) plus, in cents: payment_method (pay_by_bank or card; null while pending), amount_requested, surcharge (the fee passed on for the method used) and amount_paid (null until completed).

Webhook

When a payment made with these credentials completes, we POST to your webhook. You only receive payments made with these credentials, never the business's other sales.

{
  "event": "payment.completed",
  "data": {
    "id": "…",
    "checkout_session_id": "cs_…",
    "external_order_id": "till-42",
    "status": "completed",
    "payment_method": "pay_by_bank",
    "amount_requested": 1000,
    "surcharge": 35,
    "amount_paid": 1035
  },
  "created_at": "…"
}

The X-Tillify-Signature header is the hex HMAC-SHA256 of the raw body using the webhook_secret. Verify it against the raw body: parsing the JSON and serialising it again can change the bytes. For example, with Node.js and Express:

const crypto = require("crypto");

app.post(
  "/webhooks/tillify",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected = crypto
      .createHmac("sha256", webhookSecretFor(req)) // The business's webhook_secret
      .update(req.body)                           // A Buffer of the raw body
      .digest("hex");
    const received = req.get("X-Tillify-Signature") ?? "";

    const valid =
      received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
    if (!valid) return res.status(401).end();

    const event = JSON.parse(req.body);
    // Mark event.data.external_order_id as paid, then acknowledge
    res.status(200).end();
  }
);

Check the business can take payments

GET /api/v1/account returns { "business": { "id", "name" }, "payments_enabled", "reason" }.