Bill Reporting Documentation

Overview

Upward enables companies to offer their end users a seamless way to build credit by reporting rent, telecom, and utility payments to the credit bureaus. Our platform provides a quick and easy integration via API or an embeddable widget, allowing businesses to effortlessly extend this valuable service. By helping consumers gain credit history through everyday expenses, partners can enhance engagement, differentiate their offerings, and unlock new revenue opportunities—all while empowering their customers’ financial growth.

What is Upward Bill Reporting?

Upward Bill Reporting is Upward’s turnkey solution for Consumer-Permissioned Data (CPD) furnishment, where Upward acts as the data furnisher on behalf of consumers. Unlike solutions that require partners to furnish data themselves, Upward manages the entire process, including:

• Furnisher credentialing
• Consumer data collection & validation
• Metro 2 file generation & submission With a seamless integration via API or embeddable widget, businesses can quickly enable credit reporting for rent, telecom, and utility payments—helping their users build credit with ease.

What is Consumer-Permissioned Data (CPD)

Consumer-Permissioned Data (CPD) refers to financial or personal data that a consumer explicitly authorizes a third party to access and use on their behalf. In the context of credit reporting, CPD allows consumers to grant permission for their rent, telecom, utility, or other payment history to be reported to credit bureaus to help build their credit profile.

Unlike traditional credit data, which is collected from lenders and financial institutions without direct consumer involvement, CPD gives individuals greater control over their financial information and how it is used to improve their credit standing.

Embedded Components

Bill Reporting functionality is exposed through two embedded components. The Bill Reporting Onboarding Component captures the consumer data necessary to enable bill reporting functionality. The Bill Reporting Component enables consumers to submit and monitor which bills are reported monthly.

Steps for onboarding via embedded component

1. Get token
2. Embed URL

POST https://auth-sandbox.upwardli.com/auth/token/

1
POST https://auth-sandbox.upwardli.com/auth/token/ \
2
3
1	--header 'Content-Type: application/json' \
4
2	--data \
5
3	'{
6
4	"grant_type":"client_credentials",
7
5	"client_id":"[api client key]",
8
6	"client_secret":"[api client secret]",
9
7	"scope":"api:read api:write ui:client-onboarding"
10
8	}'
11
12
curl --location 'https://auth-sandbox.upwardli.com/auth/token/' \
13
--header 'Content-Type: application/json' \
14
--data '{
15
    "grant_type": "client_credentials",
16
    "client_id": "XXXXXX",
17
    "client_secret": "XXXXXX",
18
    "scope":"api:read api:write ui:client-onboarding"
19
}'

Here’s what a successful response looks like:

1
{
2
2	    "access_token": "xxxxx",
3
3	    "expires_in": 86400,
4
4	    "token_type": "Bearer",
5
5	    "scope": "api:read api:write ui:client-onboarding"
6
6	}

Onboarding Component

Onboarding Flow UI Specifics

The URL below will provide an embedded widget for the full onboarding flow:

1. Get Started
2. KYC
3. Accept Terms
4. Link bank account via Plaid
5. Attestation to transactions

URL: https://component-embedded-sandbox.upwardli.com/en/onboarding/bill-reporting/?access_token={token}&pcid={pcid}

Example

The following is an example of how to load the onboarding UI Component in a react native application.

1
export default function OnboardingScreen({ route }: Props) {
2
  const url = "https://component-embedded-sandbox.upwardli.com/en/onboarding/bill-reporting/?access_token={token}&pcid={pcid}";
3
  return (
4
    <SafeAreaView>
5
      <View>
6
        <JwtAuthWebview url={url} />
7
      </View>
8
    </SafeAreaView>
9
  );
10
}

Plaid + Upward

1. You need a hosted link url from UPW to open the Plaid flow
2. UPW will send an iframe message to the parent frame with a plaid.token event

1
{
2
    "hostedLinkUrl": "https://secure.plaid.com/hl/ls948q0pr159oo9qq0ns8p951n5o83686q"
3
}

3. After receiving the hosted link, you’ll need to open a secure.plaid.com browser with the hosted link.

4. UPW plaid will send out upwardli://plaid-link url schema message to notify you when to close the secure.plaid.com browser.

5. You’ll need to add a listener for this url schema (plaid completion_redirect_uri) to close the browser.

Here is the code example:

1
// Plaid completion/close browser
2
// Handle deep links
3
  useEffect(() => {
4
    const handleUrl = ({ url }: { url: string }) => {
5
      if (url.includes("plaid-link")) {
6
        WebBrowser.maybeCompleteAuthSession();
7
      }
8
    };
9
10
    const subscription = Linking.addEventListener("url", handleUrl);
11
12
    return () => {
13
      subscription.remove();
14
    };
15
  }, []);

Onboarding iFrame messages

As the consumer completes the onboarding flow you’ll receive iFrame message from our component following what the consumer.

1
Get started -> Verify identity
2
{
3
    "component": "onboarding",
4
    "path_from": "onboarding/bill-reporting",
5
    "path_to": "onboarding/bill-reporting/verify-identity",
6
    "creditbuilder": "Initialized",
7
    "KYC": "NotStarted"
8
}

1
Verify identity -> Accept terms
2
{
3
    "component": "onboarding",
4
    "path_from": "onboarding/bill-reporting/verify-identity",
5
    "path_to": "/onboarding/bill-reporting/terms",
6
    "creditbuilder": "Initialized",
7
    "KYC": "NotStarted"
8
}

1
Accept terms -> Connect Plaid
2
{
3
    "component": "onboarding",
4
    "path_from": "onboarding/bill-reporting/terms",
5
    "path_to": "onboarding/bill-reporting/connect",
6
    "creditbuilder": "Initialized",
7
    "KYC": "NotStarted"
8
}

1
Connect Plaid -> List transactions to attest
2
{
3
    "component": "onboarding",
4
    "path_from": "onboarding/bill-reporting/connect",
5
    "path_to": "onboarding/bill-reporting/bill-details",
6
    "creditbuilder": "Initialized",
7
    "KYC": "NotStarted"
8
}

Example: View all message in the browser

Copy and paste the code in your console in the browser

1
window.addEventListener("message", (event) => {
2
    const { Event, body } = event.data;
3
4
    switch (Event) {
5
        case "component.navigation":
6
            console.log("Navigation detected", body);
7
            break;
8
9
        case "component.closed":
10
            console.log("The component was closed", body);
11
            break;
12
13
        case "component.alert":
14
            console.log("Alert received", body);
15
            console.log(body.message || "Component alert");
16
            break;
17
        case "plaid.token":
18
            console.log(body || "Component Plaid");
19
            break;
20
21
        default:
22
            console.warn("Unknown event received:", Event);
23
    }
24
}, false);

Exchanging Partner API Token for a Customer Token

Once a valid token has been obtained using the Authentication API, a limited scope token can be obtained using the token exchange API. This token can be used to make requests for a specific consumer, and is safe to send to the client application/web browser as needed.

To request a token exchange send a POST to our auth server containing the access_token and requested scope.

• The audience must be for the correct Environment.
  • Sandbox: https://auth-sandbox.upwardli.com
  • Production: https://auth.upwardli.com
• The upward_consumer_id is the Upward id that you get from the Consumer API or the consumer.created webhook.
• The new access token is a significantly longer string than the original access token.

POST https://auth-sandbox.upwardli.com/auth/token/exchange/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
    "grant_type":"urn:ietf:params:oauth:grant-type:token-exchange",
8
    "subject_token_type":"urn:ietf:params:oauth:token-type:access_token",
9
    "subject_token":"[access_token]",
10
    "audience":"[https://auth-sandbox.upwardli.com](https://auth-sandbox.upwardli.com/)",
11
    "scope":"<See scopes table> consumer:[upwardli_consumer_id]"
12
}

Bill Reporting Component

URL: https://component-embedded-sandbox.upwardli.com/bill-reporting?access_token={consumer_scope_token}

Attest to Transactions from home page

If the consumer can not attest to the transactions on the onboarding, they will have the ability to do it here

File a dispute

Consumer can report any incorrect information they see