Overview

Upwardli provides a seamless and secure way for businesses to enable a credit building card to their end users. End users can incorporate credit building into their daily activities by loading money to their FDIC insured DDA account and then swiping their card at any location where Mastercard is accepted. Upwardli’s platform customers are able to monetize the card through interchange, deposit interest, and expedited external payments.

Introduction

Welcome to the Credit Builder Card! Our documentation will walk you through the basics (authentication, request structure) to using and creating the financial products associated with the Credit Builder Card (accounts, cards, payments, etc.).

The introduction covers basic concepts you should be familiar with in order to make the most out of the Upwardli card issuance and management platform.

How the Credit Builder Card Works

• The card’s available credit is equal to:
  • the available funds that the user maintains in a linked deposit account, plus
  • any verified incoming payments to the user, such as payments due for wages or gig work
• The user may obtain a physical, digital card or both. The user makes purchases anywhere Mastercard is accepted.
• As the user makes purchases on the card, an equal amount of funds in the linked deposit account are put on hold, and the card’s available credit decreases in an equal amount.
• The cardholder may opt in to automatic payments to pay off balances as they incur charges, but must pay the card’s balance in full on the payment due date.
• If the balance is not paid on time and the DDA balance is at zero the card will freeze until the user has made a payment.
• By default, there are no fees to use the card and the user is charged 0% APR.

Implementation Options

Upwardli offers three ways to integrate the credit builder card into your website or mobile app for your credit program.

• Use Credit Builder Card APIs. When integrating credit builder cards into your own website or app, this option offers flexibility in designing a unique user experience including the credit services and financial products you wish to offer. This option provides a secure, PCI-compliant, customizable experience for purchasing and providing basic banking services (i.g statements, transaction, history, card management, etc).
• Use our Embedded Integration. The embedded flow is a drop-in module that enables you to seamlessly offer a credit builder card within your app or web page. It allows individuals to easily access their credit and credit builder card details securely without redirecting away from your app or website.
• Leverage an Upwardli Hosted App. If you do not want to build and host a credit account and banking experience, Upwardli can handle the product build and push to your app store instance. This approach offers less flexibility and, while easier to implement, it requires higher platform fees.

Environments

There are two types of environments for the Upwardli Credit Suite:

1. Sandbox
   You can test out your integration and explore common usage patterns in our sandbox environment. This environment is fully isolated and will not perform any “live” financial transactions.

You can request sandbox access once you have a signed contract.

2. Production
   Once you have completed sandbox testing and submitted your test plans, you will be provisioned production access keys. These details will be shared with you via a secure sharing mechanism. All transactions in our production environment are live financial activity.

Getting Started

Regardless of which method you choose for integration you will always need to follow our authentication methods.

Authentication

Upwardli’s API uses OAuth 2.0 to authenticate requests. All API calls must include a token. These authentication tokens are used for machine to machine communication.

URLs

Tokens

Upwardli has the concept of three different tokens:

• Customer Onboarding Tokens: are system level and assigned to a specific organization that allows you to onboard new users. Once a user is onboarded you would use the customer token to access their specific information.
• Customer Access Tokens: are specific to an end user also known as consumers in our product and only provide data specific to that consumer. These tokens are used to secure our embedded components.
• Partner API Tokens: are highly secure tokens that are used to integrate your backend platform with Upwardli’s APIs. These tokens SHOULD NOT BE USED OUTSIDE OF DIRECT API CALLS BETWEEN YOUR SYSTEM AND UPWARDLI.

When a token is created, it is assigned a set of Scopes. The scopes define the resources that can be accessed using the token, and the access level (read/write) that will be allowed using that token.

Scopes

Scopes define the access level of a token.

A list of all scopes within Upwardli:

Embedded Component Endpoints

The Credit Builder Card API provides access to several different types of detail.

You decide which of the experiences you want to include:

Requesting Tokens Using The API

The Upwardli API uses OAuth 2.0 for authentication and authorization. Before you can use the API, you must obtain an access token using the client_id and client_secret provided to you. Once a token has been obtained, it must be passed in the Authorization header of each request to the API.

Customer Onboarding Token Request

To request a token send a POST to our auth server containing your client ID and client secret values.

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

1
{
2
  "header": "content-type: application/json",
3
  "grant_type": "client_credentials",
4
  "client_id": "[your id here]",
5
  "client_secret": "[your secret here]",
6
  "scope": "ui:client-onboarding"
7
}

Here’s a cURL example for the token request:

1
POST https://auth-sandbox.upwardli.com/auth/token/ \
2
3
    --header 'Content-Type: application/json' \
4
    --data \
5
'{
6
    "grant_type":"client_credentials",
7
    "client_id":"[api client key]",
8
    "client_secret":"[api client secret]",
9
    "scope":"api:read api:write ui:client-onboarding"
10
}'
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
  "access_token": "xxxxx",
3
  "expires_in": 86400,
4
  "token_type": "Bearer",
5
  "scope": "api:read api:write ui:client-onboarding"
6
}

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.

Notes:

• The audience must be for the correct Environment.
  • Sandbox: https://auth-sandbox.upwardli.com
  • Production: https://auth.upwardli.com
• The upwardli_consumer_id is the Upwardli 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",
11
    "scope":"<See scopes table> consumer:[upwardli_consumer_id]"
12
}

Here’s what a successful response looks like:

1
{
2
  "token_type": "Bearer",
3
  "expires_in": 3600,
4
  "access_token": "[scoped access token]",
5
  "scope": "<Scope(s)>",
6
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
7
}

Onboarding a New User

A consumer is the individual end user that you are creating a credit product. Consumers are limited to individuals using a valid SSN or ITIN, or single-member LLCs (coming soon).

A Consumer record is automatically created once an application is started and Upwardli will manage the ongoing regulatory requirements tied to application notice, approval and denial notifications to the end user.

Consumer onboarding is a fully asynchronous process due to the KYC and Banking integrations, which are themselves asynchronous. Our design goal for customers interacting with the Onboarding component is to capture data in realtime, and then process asynchronously. This will reduce elapsed consumer interaction time and improve the customer experience.

All consumers are created as part of our onboarding. Regardless of the integration method you’ll need to use our embedded iframe to offer our application flow. We do allow you to customize the UI of the application but to ensure consistent and fair lending practices we own the specific language and disclosures surrounding the application process.

Authentication & Loading the Onboarding Embedded Flow

Tip: Your API Key and Secret will be shared with you by your Upwardli client team.

The first step in integrating your product is to configure authentication. All Upwardli components and APIs require Oauth tokens for access.

Next, you load the onboarding embedded component in your app using URL below and the a Customer Onboarding Token with the ui:client-onboarding scope.

1
https://component-embedded-sandbox.upwardli.com/en/onboarding/card-product/?pcid={$partner_consumer_id}&access_token={$access_token}

When you load the onboarding embedded component, pass in the PCID property (your unique ID) as a query parameter and be sure to include the correct access token.

Once the consumer clicks “Get Started”, the UI component creates their consumer record using the Consumer API endpoint. The user’s pcid will be set to the value you provide us, and we will generate a unique id on our side to identify this record internally and within our APIs.

Upwardli sends out a consumer.created webhook message to your server. The Upwardli Servers will send a webhook message to you with the following general schema, indicating that the consumer record was created on our side.

1
{
2
  "id": "ea04f0a8-b005-47cd-ba33-b02a00c0c426",
3
  "created_at": "2023-06-23T07:41:50.45-04:00",
4
  "event_name": "consumer.created",
5
  "partner_id": "2f221c90-b82d-4e12-9bfd-ae8301097de3",
6
  "resources": ["https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"],
7
  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
8
}

You Link the Upwardli ID to your Local Object. Upon receiving the webhook message, you will parse it for the eventName property and determine that this message means that a new consumer was created. You can then call the url in the resources property to get information about that consumer.

Example of output via API - assuming the consumer stopped before complete KYC and that you did not pre-fill any data for that user.

1
{
2
    "id": "{consumer_id}",
3
    "pcid": "{pcid}",
4
    "first_name": null,
5
    "last_name": null,
6
    "email": null,
7
    "is_active": true,
8
    "kyc_status": "NotStarted",
9
    "phone_number": null,
10
	  "date_of_birth": null,
11
	  "tax_id_type": "SSN",
12
	  "tax_identifier": null,
13
	  "address_line1": null,
14
	  "address_line2": null
15
    "address_city": null,
16
    "address_state": null,
17
    "address_zip": null
18
}

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 =
3
    "https://component-embedded-sandbox.upwardli.com/en/onboarding/card-product/?pcid={$partner_consumer_id}&access_token={$access_token}";
4
  return (
5
    <SafeAreaView>
6
      <View>
7
        <JwtAuthWebview url={url} />
8
      </View>
9
    </SafeAreaView>
10
  );
11
}

Onboarding Flow UI Specifics

The details below outline the flow of onboarding a consumer:

1. Get Started
2. Create Consumer
3. Accept Terms, and
4. Ordering a Card.

Step 1: Get Started

Each consumer will see an entry screen that will highlight the value props and also include the appropriate disclaimers for the product.

Step 2: Create Consumer

The create consumer step is where we will initiate a consumer record, collect and verify KYC details, as well as complete required PEP and OFAC scans.

Consumer Completes the KYC step(s)

Once the user has successfully completed KYC, then we will send a further webhook with an event_name of consumer.updated

1
{
2
  "id": "ea04f0a8-b005-47cd-ba33-b02a00c0c426",
3
  "created_at": "2023-06-23T07:41:50.45-04:00",
4
  "event_name": "consumer.updated",
5
  "partner_id": "2f221c90-b82d-4e12-9bfd-ae8301097de3",
6
  "resources": ["https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"],
7
  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
8
}

When you retrieve the updated consumer record related to this webhook, you will see that the kyc_status value has changed to "kyc_status": "Complete", indicating that this consumer has successfully completed the KYC step. In some cases, we will need to complete a manual review of the information provided by the consumer.

This webhook will also allow you to see the KYC information that was provided by the consumer when completing this step. We do not provided the full tax_identifier.

1
{
2
  "id": "{consumer_id}",
3
  "pcid": "{pcid}",
4
  "first_name": "John",
5
  "last_name": "Doe",
6
  "email": "john.doe@gmail.com",
7
  "is_active": true,
8
  "kyc_status": "Complete",
9
  "phone_number": "+12065559034",
10
  "date_of_birth": "2000-01-01",
11
  "tax_id_type": "SSN",
12
  "tax_identifier": "***-**-1234",
13
  "address_line1": "100 Main Street",
14
  "address_line2": null,
15
  "address_city": "Tuscaloosa",
16
  "address_state": "AL",
17
  "address_zip": "354050000"
18
}

Optional: KYC Data Pre-Fill

Before loading the embedded component, you can pre populate data for a consumer by calling the api: POST: https://api-sandbox.upwardli.com/v2/consumer/ and providing the following fields:

1
{
2
    "pcid": "{pcid}",
3
    "first_name": "John",
4
    "last_name": "Doe",
5
    "email": "john.doe@email.com",
6
    "phone_number": "+12065559034",
7
    "date_of_birth": "2000-01-01",
8
    "address_line1": "100 Main Street",
9
    "address_line2": "Apt 123"
10
    "address_city": "Tuscaloosa",
11
    "address_state": "AL",
12
    "address_zip": "354050000"
13
}

Edge Cases / Unhappy path:

1. If a user does not complete KYC, then you will only receive the consumer.created message
2. If a user fails KYC, then we will send a consumer.updated webhook, with a kyc_status value of Failed. We will not open a credit line for any users who do not pass KYC.

Step 3: Accept the Credit Card Terms

A user will naturally be sent through to accept the terms of the product -

**However** if a user doesn’t complete KYC or drops off during the signup process, you can restart the session by sending a new unexpired token with the PCID for that consumer and the the correct scopes for accessing onboarding. This will ensure the consumer is dropped back to the right portion of the app.

Example:

Step 3: Card Selection & Ordering

A user will naturally be sent through to order either a digital or physical card. If they select a physical card they will be asked to verify their shipping address. Once they confirm their card type onboarding will be completed.

A user will see a success screen.

After onboarding completion

• If the partner has provided a redirect_url the consumer will be redirected.
• Upwardli will also send an onboarding-success message to parent iFrame.
• A partner can implement a listener to take action from this event.
• The consumer bank account and card may not be open at this point while we are completing the onboarding with the bank. Once the accounts and card are provisioned you will receive a webhook message called PaymentCard.Created
• If a user doesn’t order a physical to start they can order under card management. A partner can order on behalf of a user by calling the card.order API

iFrame Messaging

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

Get started page → KYC

1
component.navigation;
2
{
3
  KYC: "NotStarted";
4
  component: "onboarding";
5
  path_from: "onboarding/card-product";
6
  path_to: "/onboarding/card-product/verify-identity";
7
}

KYC → Terms

1
{
2
	...
3
	path_to: "/onboarding/card-product/terms"
4
}

Terms → Card Confirmation

1
{
2
	...
3
	path_to: "/onboarding/card-product/card-confirmation"
4
}

Card Confirmation → Confirm Shipping

1
{
2
	...
3
	path_to: "onboarding/card-product/confirm-shipping"
4
}
5
->
6
{
7
	...
8
	path_to: "onboarding/card-product/on-the-way"
9
}

Card Confirmation (Digital) → on-the-way

1
{
2
	...
3
	path_to: "onboarding/card-product/on-the-way"
4
}

On the way → partner

1
component.closed;
2
{
3
  KYC: "NotStarted";
4
  component: "onboarding";
5
  path_from: "onboarding/card-product/on-the-way";
6
  path_to: undefined;
7
}

Example: View all message in the browser

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

Post Onboarding Display Options

Plaid + UPW

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. "hostedLinkUrl": "https://secure.plaid.com/hl/ls948q0pr159oo9qq0ns8p951n5o83686q"
3. After receiving the hosted link
4. You’ll need to open a secure.plaid.com browser with the hosted link
5. UPW plaid will send out upwardli://plaid-link url schema message to notify you when to close the secure.plaid.com browser
6. You’ll need add a listener for this url schema (plaid completion_redirect_uri) to close the browser
7. Here is the code example.

1
# Plaid completion/close browser
2
const handleUrl = ({ url }: { url: string }) => {if (url.includes("plaid-link")) { WebBrowser.maybeCompleteAuthSession(); } };

Onboarding options

Once a consumer is onboarded you have two option to display consumer account and card details.

1. Embedded widget - we display the UI for you in our hosted components, you have control over the look and feel but not the layout.
2. API - you query our platform for the raw data and have full control of how you display it in your own UI (beyond what is listed in the box below)

Card Management

The card management widget is intended to give consumers the ability to view their card, update actions tied to their card (transaction history, PIN set, ATM locator, freeze a card). A consumer will also be able to view their credit score, see statements, make payments and initiate transfers.

Card Management via Embedded Widget

To display the Card Management embedded widget you will follow the same authentication steps that are used to access the initial onboarding form.

Next, you load the card management embedded component in your app using URL below and the a Customer Access Token with the api:card-management:read.

Important Parameters

Once a user has completed onboarding you will have the ability to display the card management embedded widgets. You can either pull the home screen directly or have individual entry points for each of these experiences

The details below outline the 3 primary experiences associated with card management:

1. “Home” experience
2. Card Management
3. Card & Transaction Details

Home Experience

Card Management via API

When using our API method post onboarding you will be able to pull specific information regarding card details, transfers, credit insights and other actions directly into your app or website. The only two areas where you will need to use our standalone embedded widgets are (1) card image and (2) card details (i.e PIN set, freeze card, etc).

Authentication

You will need to authenticate to get access to the APIs you will use the URL below and the a Partner API Token with the applicable API url.

Card Image

This entry spot will provide a PCI compliant way to display the card image and transaction details for the user. A user will be able to add their card details to their Apple or Google mobile wallet manually. In-app push provisioning will be available in 2H 2025.

Card Details

This entry spot will provide a user the ability to manage the access to their card, freeze / unfreeze a card, reset a PIN, etc. From this screen users can also view their DDA account and routing numbers to facilitate external transfers or direct deposits to their accounts.

Related API Table

Below is a list of the API calls used to populate the Card Management embedded component.

Example: Payment Card

GET https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/payment-cards/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

1
{
2
    "count": 1,
3
    "next": null,
4
    "previous": null,
5
    "results": [
6
        {
7
            "id": "4a2472ea-75d9-4448-a4f4-e081a324e176",
8
            "consumer_id": "00000000-0000-0000-0000-000000000003",
9
            "status": "active",
10
            "emboss_hold": true,
11
            "available_balance": 197.02,
12
            "account_number": "1234567890",
13
            "routing_number": "021214891",
14
            "created_at": "2025-02-05T22:57:31.749142Z"
15
        }
16
    ]
17
}

Example: Bank Accounts

Get bank accounts

GET https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/accounts/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

1
{
2
    "count": 2,
3
    "next": null,
4
    "previous": null,
5
    "results": [
6
        {
7
            "id": "083959d1-8282-4512-a52e-5630a5af042f",
8
            "consumer_id": "00000000-0000-0000-0000-000000000003",
9
            "bank_name": "Upward Financial Inc",
10
            "balance": 0,
11
            "account_name": "Upwardli Credit Builder",
12
            "account_number": "******7890",
13
            "account_type": "Secured Card",
14
            "account_routing_number": "*****4891",
15
            "is_primary": false
16
        },
17
        {
18
            "id": "bbd3005f-b6b0-40fe-975e-34bae4b20a5c",
19
            "consumer_id": "00000000-0000-0000-0000-000000000003",
20
            "bank_name": ".",
21
            "balance": 0,
22
            "account_name": "Account Name",
23
            "account_number": "******6789",
24
            "account_type": "checking",
25
            "account_routing_number": "*****6789",
26
            "is_primary": true
27
        }
28
    ]
29
}

Get partner fbo account

GET https://api-sandbox.upwardli.com/v2/partners/{partner_id}/accounts/{account_id}

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

Create bank account

POST https://api-sandbox.upwardli.com/v2/accounts/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
	"account_name": "Account Name"
8
	"account_number": "0123456789"
9
	"bank_name": " . "
10
	"consumer_id": "00000000-0000-0000-0000-000000000003"
11
	"routing_number": "123456789"
12
}

Response

1
{
2
    "message": "Bank account created successfully",
3
    "data": {
4
        "id": "0f845102-f717-4bb9-a96a-c167a36148d6",
5
        "consumer_id": "00000000-0000-0000-0000-000000000003",
6
        "bank_name": ".",
7
        "balance": 0,
8
        "account_name": "Account Name",
9
        "account_number": "******6789",
10
        "account_type": "checking",
11
        "account_routing_number": "*****6789",
12
        "is_primary": true
13
        "is_active": true
14
    }
15
}

Delete bank account

Put https://api-sandbox.upwardli.com/v2/accounts/{account_id}/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
	"is_active": false
8
}

Example: Credit Insights

GET https://api-sandbox.upwardli.com/v2/credit-insights/{consumer_id}/summary/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

1
{
2
    "credit_score_card": {
3
        "score": 655,
4
        "change": 28,
5
        "credit_usage": 14,
6
        "total_tradelines": 3,
7
        "payment_history": 2,
8
        "credit_inquiries": 1,
9
        "credit_age": 35,
10
        "debt_collection_count": 1,
11
        "report_date": "2025-01-06",
12
        "late_payment_percentage": 0,
13
        "total_public_records": 0,
14
        "total_open_revolving_accounts": 0,
15
        "total_open_collection_accounts": 0,
16
        "total_bankruptcies": 0,
17
        "credit_report_status": "NotOrdered"
18
    },
19
    "credit_score_history": [
20
        {
21
            "month": "2025-01",
22
            "score": 655
23
        },
24
        {
25
            "month": "2024-12",
26
            "score": 627
27
        },
28
        {
29
            "month": "2024-11",
30
            "score": 601
31
        },
32
        {
33
            "month": "2024-10",
34
            "score": 587
35
        },
36
        {
37
            "month": "2024-09",
38
            "score": 688
39
        }
40
    ]
41
}

Example: Transactions

Note: payment_card_id is not bank account id

GET https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/transactions/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

1
{
2
    "count": 1,
3
    "next": null,
4
    "previous": null,
5
    "results": [
6
        {
7
            "id": "3a8ee16d-a561-4265-886b-186c10e409f2",
8
            "status": "posted",
9
            "amount": "57.57",
10
            "posted_at": "2025-02-03 23:13:38",
11
            "effective_at": "2025-02-03 23:13:38",
12
            "description": "Test Client Transaction: 0",
13
            "direction": "credit"
14
        }
15
    ]
16
}

Example: Create ACH

POSThttps://api-sandbox.upwardli.com/v2/payments/ach/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
	"amount": 6
8
	"consumer_id": "Consumer_id"
9
	"originating_account_id": "Account_id"
10
	"receiving_account_id": "Account_id"
11
	"description": "ACH originating_account_id to receiving_account_id"
12
}

Example: Create Partner transfer

POSThttps://api-sandbox.upwardli.com/v2/payments/transfer/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
	originating_account_id: "Partner FBO account id"
8
  receiving_account_id: "Consumer bank account id (not consumer id)"
9
  amount: 12.12
10
  description: "Partner FBO account to consumer account"
11
}

Example: Fund Card

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/simulations/payment-cards/{{payment_card_id}}/create-simulated-fund-card

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example: Simulate Card Auth

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/simulations/payment-cards/{{payment_card_id}}/create-simulated-card-auth

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
    "amount": 10.00,
8
    "association": "visa",
9
    "merchant_name": "Testing Transactions" length needs to greater than 5
10
}

Example: Simulate Card Settlement

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/simulations/payment-cards/{{payment_card_id}}/create-simulated-card-settlement

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
    "auth_id": "<auth_id_from_above_response>",
8
    "settle_amount": 10.00
9
}

Example: Close Upwardli account

POST https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/cancel-account/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Card Actions

Freeze

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/freeze

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
    "end_date": "input_formats=["%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S.%fZ"]",
8
}

Unfreeze

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/unfreeze

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Lost or Stolen

Note: payment_card_id is not bank account id

POST https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/replace-lost-stolen/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
		"card_status": "L|S"
8
}

Replace Card

POST https://api-sandbox.upwardli.com/v2/payment-cards/{payment_card_id}/reissue/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Credit Goals

Credit Goals via API

Example: Credit Insights

GET https://api-sandbox.upwardli.com/v2/credit-insights/{consumer_id}/summary/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Response

1
{
2
    "credit_score_card": {
3
        "score": 655,
4
        "change": 28,
5
        "credit_usage": 14,
6
        "total_tradelines": 3,
7
        "payment_history": 2,
8
        "credit_inquiries": 1,
9
        "credit_age": 35,
10
        "debt_collection_count": 1,
11
        "report_date": "2025-01-06",
12
        "late_payment_percentage": 0,
13
        "total_public_records": 0,
14
        "total_open_revolving_accounts": 0,
15
        "total_open_collection_accounts": 0,
16
        "total_bankruptcies": 0,
17
        "credit_report_status": "NotOrdered"
18
    },
19
    "credit_score_history": [
20
        {
21
            "month": "2025-01",
22
            "score": 655
23
        },
24
        {
25
            "month": "2024-12",
26
            "score": 627
27
        },
28
        {
29
            "month": "2024-11",
30
            "score": 601
31
        },
32
        {
33
            "month": "2024-10",
34
            "score": 587
35
        },
36
        {
37
            "month": "2024-09",
38
            "score": 688
39
        }
40
    ]
41
}

Profile

Important Parameters

Profile via Embedded Widget

Profile via API

Example: Statements

GET https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/statements

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example: Download statements

GEThttps://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/statements/{pdf_filename}/download

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example: Create dispute

POSThttps://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/dispute/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}
5
Body
6
{
7
	"reason": "Payment not correct",
8
	"details": "I took out $20 from the ATM. Why do I need $22.50 charge."
9
}

Example: List dispute

GEThttps://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/dispute/list/

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example: Get dispute

GEThttps://api-sandbox.upwardli.com/v2/consumers/{consumer_id}/dispute/{dispute_id}/

General API information

If you are utilizing the API approach you will also want to access other APIs for requesting specific information about Upwardli resources

Using the Upwardli Webhooks

By design we do not include extensive information about the webhook data sources. To learn more about the object referenced by the webhook, you can use the url[s] in the webhook body to make api requests.

Available Webhooks

Webhook Message Description

All Upwardli webhook messages use the same format. To learn more about the resource(s) that are referenced by a specific webhook message, you can make an API request to the url(s) inside of the resources property.

1
{
2
    "id": "{Unique Webhook Id}",
3
    "created_at": "Datetime: YYYY-MM-DDTHH:MM:SS.SS-TZ",
4
    "event_name": "Webhook Message",
5
    "partner_id": "{Your unique Partner Id}",
6
    "resources": [
7
        "https://{environment}.upwardli.com/v2/{resource}/{resource_id}"
8
    ],
9
    "last_attempted_at": "Datetime: YYYY-MM-DDTHH:MM:SS.SS-TZ"
10
}

Webhook Authentication

Upwardli’s webhooks are secured using a Hashed Message Authentication Code (HMAC) in the webhook message header. The name of this header value is Upwardli-Signature. The Upwardli-Signature header contains two comma-separated key-value pairs encoding information about the request.

The first key-value pair will be in the form t=<unix_timestamp> and represents the unix time that the request was sent. The second key-value pair will be in the form v1=WeNeedSomethingHere, where the signature is a sha256 hash computed from the consumers webhook secret and a dot-separated string composed of the unix timestamp joined with the request body.

Note: computing the signature is sensitive to the exact characters input into the algortihm. The request data should be a json string with no whitespace formatting.

Sample Data

1
`client_id => 'public'``signature => 't=2023-10-12T20:44:58.082694+00:00,v1=263a5f79d899f7d5e04eb9a902b173d5901a9088966b932edca7174aec3d9e12'``message => '{"id":"954935cb-be33-47a4-99af-ec8bbc662ec7","createdAt":"2023-10-05T17:39:21.097794+00:00","eventName":"consumer_created","partnerId":"cb739356-5f69-429c-8157-756876d08d27","resources":["api/v2/consumers/00000000-0000-0000-0000-000000000000"],"lastAttemptedAt":"2023-10-05T17:39:21.097794+00:00"}'`;

Example decode in Python

1
1t, v1 = [value.split('=')[1] for value in request.headers['Upwardli-Signature'].split(',')]2computed_digest = hmac.new(<YOUR_CLIENT_ID>.encode(), (t + '.' + request.data.decode('utf-8')).encode(), 'sha256').hexdigest()34if hmac.compare_digest(v1, computed_digest):5    # Process webhook

Registering for Webhook Messages

POST https://api-sandbox.upwardli.com/v2/webhooks/registrations/

Header

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example Request Body

1
{
2
  "webhook_name": "{webhook_name}",
3
  "endpoint": "{endpoint to receive messages at}"
4
}

Get All Webhook Registrations

GET https://api-sandbox.upwardli.com/v2/webhooks/registrations/

Header

1
Header
2
{
3
    "Authorization":"Bearer [access_token]"
4
}

Example Response

1
{
2
    "count": 2,
3
    "next": null,
4
    "previous": null,
5
    "results": [
6
        {
7
            "id": "{webhook_registration_id}",
8
            "partner_id": "{partner_id}",
9
            "webhook_name": "consumer.created",
10
            "endpoint": "{webhook_endpoint}",
11
            "status": "active",
12
            "failures": 0,
13
            "last_failure": null
14
        },
15
        {
16
            "id": "{webhook_registration_id}",
17
            "partner_id": "{partner_id}",
18
            "webhook_name": "consumer.updated",
19
            "endpoint": "{webhook_endpoint}",
20
            "status": "active",
21
            "failures": 0,
22
            "last_failure": null
23
        }
24
    ]
25
}

Change Log