GuidesAPI ReferenceChangelog
Log In
Guides

Implement Bill Navigator

Suggest Edits

Overview

This guide explains how to enable Bill Navigator for an end user through Pinwheel's SDK.

Bill Navigator allows users to connect their existing bank accounts and credit cards and automatically identifies recurring bills & subscriptions. The user can then perform an automated payment method switch for their associated bills and subscriptions or will be prompted with instructions to perform a manual switch when an automated switch is not supported. Finally, Users can mark manual switches as completed and use Pinwheel’s overview screens to keep track of which bills they have switched.

Step 1: Subscribe to Webhook Events

Subscribe to the following webhook events when changes to a user's recurring transaction payments are available:

  • bill_switch.added: Notifies you when information about the bill switch is available. See Bill Navigator Webhook Events for the full webhook payload schema.

Register a webhook endpoint using Pinwheel's Create Webhook, as the following example illustrates.

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "bill_switch.added"
  ],
  "version": "2023-11-22",
}

Step 2: Create a Link token

Start by creating a Link Token with the jobs that your application requires specified within the required_jobsparameter. For bill navigator, this list should only be [bill_switch]. To enable the navigation/identification of bills flow you must also set the enable_bill_navigator field to true.

Bill Navigator

To ensure switches can be successfully made regardless of merchant, you must provide details for the card and target bank account that you want the user to switch their bills to. Each bank account needs to include type, account_number, and routing_number and is recommended to include name as well for returning in webhooks. See Link Token Creation docs for full details on required fields.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "name": "My Checking Account",
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },

 "cards": [
   {
      "card_name": "Card Name",
      "card_number": "12345678912345",
      "cvc": "111",
      "expiration_date": "05/29",
      "name_on_card": "Jane Doe",
      "card_zip_code": "12345",
      "billing_address": "123 Lane St",
      "billing_address2": "Apt 987",
      "city": "New York",
      "state": "NY"
    }
  ]
  "enable_bill_navigator": true,
  "required_jobs": [
  	"bill_switch",
  ]
}

Step 3: Initialize Link

Use the Link token to open the Link modal in your client application. In addition to passing in the token, you can optionally pass several callback handlers.

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

The onSuccess callback handler is executed on job success and contains metadata about the bill switch job. It is important to note that multiple bill switch jobs can be executed within a single Pinwheel link flow.

Step 4: Respond to Webhook Events

After a user successfully logs into their payroll account, an account.added webhook event is published. Using the link_token_id, you can associate the account with the user who logged in with Link.

{  
  "event": "account.added",  
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",  
  "payload": {  
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",  
    "end_user_id": "my_user_12345",  
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",  
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",  
    "created_at": "2021-01-12T02:36:01.287148+00:00",  
    "connected": true  
  }  
}

Depending on if a user performs a bill switch, a bill_switch.added event will be published. For example:

bill_switch.added

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

Step 5: Query for Job Results

If you are not subscribed to webhook events, or there was an issue handling thebill_switch.added event, you can fetch job results by querying the Jobs endpoint with the link_token_idof a specific user.

Request

GET /v1/jobs?link_token_id=97f420ff-5d0a-46ee-9cfc-6f17d5d31256
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET

Response

{  
  "meta": {  
    "count": 1  
  },  
  "data": [  
    {  
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  
      "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",  
      "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",  
      "name": "bill_switch",  
      "timestamp": "2021-01-12T02:36:01.287148+00:00",  
      "outcome": "success",  
      "params": {  
        "action": "full_switch",  
        "allocation": {  
          "target": {  
            "account_type": "checking"  
          }  
        }  
      }  
    }  
  ]  
}

Step 6: Returning users

Pinwheel will use end_user_id passed in the Link token to keep track of returning users for recurring transaction monitoring and continued updating. Users who have previously connected an account will maintain their list of recurring transactions. For this use case a link token can be created exactly as above.

If you would like to send the user directly to a previously switched account that they may have switched away from paying with your card or account you can pass in account_id from a previous account.added webhook or login event in Link.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "account": "<Insert UUID>",
  "allocation": {
    "targets": [
      {
        "name": "My Checking Account",
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },

 "cards": [
   {
      "card_name": "Card Name",
      "card_number": "12345678912345",
      "cvc": "111",
      "expiration_date": "05/29",
      "name_on_card": "Jane Doe",
      "card_zip_code": "12345",
      "billing_address": "123 Lane St",
      "billing_address2": "Apt 987",
      "city": "New York",
      "state": "NY"
    }
  ]
  "required_jobs": [
    "bill_switch"
  ]
}

Once you've created the Link token, follow Step 3 to initialize the Link. When the user is presented with the Pinwheel Link flow, they are directed to the merchant platform associated with their account, bypassing login if possible.

Updated 4 days ago