GuidesAPI ReferenceChangelog
Log In
Guides

Reseller Implementation Guide

Overview

The Partnership Model enables Pinwheel partners who act as resellers to associate Link sessions, jobs, and webhook events with their own customers. By passing a partner_customer_id during Link token creation, each interaction through Pinwheel can be traced back to the reseller’s specific customer.

This allows for unified reporting, monitoring, and analytics across all downstream customers, while still operating from a single reseller workspace.

Prerequisites

Before implementing the Partnership Model, ensure that:

  1. Your workspace has been configured as a Reseller Workspace by the Pinwheel team.
  2. You have your API key for the correct mode (Sandbox/Production).
  3. You have webhook endpoints set up to receive job notifications.
  4. You have upgraded to API version 2025-07-08 or later.

📘 Note
Only Reseller (and Banking Platform) workspaces may include partner_customer_id. Attempting to use this parameter from other workspace types will result in a 400 error.

Step 1: Onboarding a new customer

When you're ready to onboard a new resold customer, provide a unique identifier for that customer to Pinwheel. This will be the value you pass as partner_customer_id.

Use a consistent partner_customer_id that aligns with your internal CRM or database. Avoid using dynamic or transient values.

Once you've chosen the value for partner_customer_id, contact your Pinwheel Client Success Manager and provide them with the value and which customer it refers to. We will register it as a valid mapping in our system.

❗

Note: all values for partner_customer_id must be registered with Pinwheel. Passing in an unknown value when creating a link token will result in an error.

Step 2: Create a Link Token with partner_customer_id

Include the partner_customer_id parameter when creating a Link Token.
This value uniquely identifies your customer within your system and will appear in all downstream webhook payloads and reports.

Example: Direct Deposit Switch Link Token

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "end_user_id": "end_user_12345",
  "partner_customer_id": "customer-001",
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "solution": "Deposit Switch",
  "features": [
    "direct_deposit_switch"
  ]
}

📘 Note

  • The partner_customer_id must be unique within your reseller workspace.
  • The parameter is required for reseller workspaces and not accepted for other workspace types.

The response includes a short-lived token (valid for one hour) and an identifier that you should persist for tracking and job retrieval.

Step 3: Launch Pinwheel Link

Use the returned token to initialize Pinwheel Link in your client application.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.getpinwheel.com/pinwheel-v3.0.js"></script>
    <script>
      Pinwheel.open({
        linkToken: "INSERT LINK TOKEN",
        onSuccess: (result) => {
          console.log("Job succeeded!", result);
        },
        onError: (error) => {
          console.error("Link error:", error);
        }
      });
    </script>
  </head>
  <body></body>
</html>

When the user completes their payroll connection and performs a Direct Deposit Switch, your application will be notified via webhook.

Step 4: Receive Webhook Events

Webhook events for reseller workspaces include the partner_customer_id field in the event payload.
This enables your system to map events directly to your internal customer record.

Example: direct_deposit_switch.added

{
  "event": "direct_deposit_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "partner_customer_id": "customer-001",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "name": "direct_deposit_switch",
    "timestamp": "2025-10-01T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "full_switch",
      "allocation": {
        "target": {
          "account_type": "checking",
          "last_four_account_number": "0294"
        }
      }
    }
  }
}

📘 Note
You can use the partner_customer_id to associate this webhook event with the customer in your internal system.
If you log event_id, you can also ensure idempotency and track delivery status for debugging.

Step 5: Reporting and Analytics

All downstream reports for your reseller workspace include the partner_customer_id field.
This makes it easy to filter or group performance data by customer—for example, to measure conversion rates or identify adoption trends.

Best Practices

  • Use stable identifiers: Use a consistent partner_customer_id that aligns with your internal CRM or database. Avoid using dynamic or transient values.
  • Secure your webhooks: Always verify the webhook signature included in the x-pinwheel-signature header.
  • Store identifiers: Persist link_token_id, account_id, and partner_customer_id for audit and reconciliation.
  • Monitor outcomes: Use webhook outcomes (success, error, pending) to track user journey and handle retries gracefully.

Example End-to-End Flow

  1. Your system creates a Link Token with a partner_customer_id (e.g., "customer-001").
  2. The user completes the Direct Deposit Switch in Pinwheel Link.
  3. Pinwheel sends a webhook event including partner_customer_id.
  4. The transaction appears in your reports and dashboards, filterable by that same ID.

Support

If you are a reseller and want to enable this feature or migrate from an existing tagging model, contact your Pinwheel Client Success Manager.

For detailed API reference and webhook event schemas, visit the Pinwheel API Reference.

Updated about 2 hours ago

Did this page help you?