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: 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 user experience. 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"
    }
  ],
   "end_user": {
    "platform_matching": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]"
    }
  },
  "enable_bill_navigator": true,
  "required_jobs": [
  	"bill_switch",
  ]
}

Step 2: 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.

{  
  "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 3: 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.

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"
    }
  ],
  "end_user": {
    "platform_matching": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]"
    }
  },
  "enable_bill_navigator": true,
  "required_jobs": [
    "bill_switch"
  ]
}

Once you've created the Link token, follow Step 2 to initialize the Link.

Updated 7 months ago