Credit Builder as a Service

This tutorial walks you through the basic steps of integrating your fintech product with the Upward Credit Builder as a Service (CBaaS) product.

Authentication

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

For a deeper dive into authentication, you can read these further details.

Consumer Onboarding

Once you are able to successfully request and receive authentication tokens, you can start onboarding your end users. Our onboarding process has three main steps:

1. End User KYC
2. View the Offer/Terms
3. Accept the Credit Terms Agreement

These steps are all managed automatically using our onboarding UI component, and you can view a detailed overview of the onboarding process here.

Purchase Flow

The User Purchase Flow is a three stage process:

Recording transactions with Upward is a three stage process:

Requesting a Hold

The transaction starts by requesting a hold. If there are sufficient funds in the end user’s account, then a new transaction will be created and the funds will be held until the transaction is completed, or for 1 calendar day. If there are insufficient funds in the account, a 4XX error will be returned with an error description in the body.

Clearing the Transaction

Once a hold is created, you can convert that hold into a transaction by calling the clear endpoint. This will disburse the funds from the end user’s line of credit and create the liability. This step should happen at the time of purchase in your system.

Close the Transaction

In this final step, the transaction is closed and recorded a complete. Successful closes will extinguish the liability that was created in the Clearing step and make those funds available, again, to the end user.

You can view further details about the Purchase Flow, and a detailed overview of the purchase cycle here.

APIs

All of our UI components use the same APIs that we make available to our consumers. You can view our full API documentation here.

Detailed UI Onboarding Walkthrough:

The following steps outline the steps encountered when onboarding a new consumer via our UI Components.

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": [
7
    "https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"
8
  ],
9
  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
10
}

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
}

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": [
7
    "https://api-sandbox.upwardli.com/v2/consumers/{consumer_id}"
8
  ],
9
  "last_attempted_at": "2023-06-23T07:41:50.45-04:00"
10
}

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
}

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
}

Edge Cases / Unhappy path:

1. If a user does not complete KYC, then you will only receive the first 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.

The CBaaS Transaction Flow

Recording transactions with Upward is a three stage process:

1. Request a Hold
2. Clear the Transaction
3. Close the Transaction

Requesting a Hold

The transaction starts by requesting a hold. If there are sufficient funds in the end user’s account, then a new transaction will be created and the funds will be held until the transaction is completed, or for 1 calendar day. If there are insufficient funds in the account, a 4XX error will be returned with an error description in the body.

The system will then send a webhook with an eventName of creditline.transaction.created immediately.

Clearing the Transaction

Once a hold is created, you can convert that hold into a transaction by calling the clear endpoint. This will disburse the funds from the end user’s line of credit and create the liability. This step should happen at the time of purchase in your system.

The system will then send a webhook with an eventName of creditline.transaction.cleared when the funds have successfully been transfered to the user’s account. note: This could be delayed for up to a couple minutes from the time that the clear api was called to allow funds to settle.

Close the Transaction

In this final step, The transaction is closed and recorded a complete. Successful closes will extinguish the liability that was created in the Clearing step and make those funds available, again, to the end user.

The system will then send a webhook with an eventName of creditline.transaction.closed when the funds have successfully been transfered to the user’s account. note: This could be delayed for up to a couple minutes from the time that the clear api was called to allow funds to settle.

You can read more about the Credit Line API in our API Documentation.

Successful Transaction Flow

The Transaction flow is broken down into the individual system actions at each step of the purchase flow. You must complete each step as defined in the flow below before moving on to the next step.

The Hold Stage

1. Consumer creates a transaction hold by calling /v2/credit-line/{credit_line_id}/hold/
2. The Upward API will immediately return a response containing the new transaction id. This transaction ID is immediately ready to use.
3. Asychronously, the Upward platform will send you a webhook message corresponding to this hold action with an eventName of creditline.transaction.created
4. The transaction status will be set to Hold

The Clear Stage

1. Consumer clears the hold and initiates a purchase agains the consumer credit line by calling /v2/credit-line/{credit_line_id}/transactions/{transaction_id}/clear/
2. The Upward API will immediately return a response indicating that the clear request was successful, or an error if the request was unable to be processed.
3. The Upward Platform will begin the funds transfer from the consumer’s line of credit to their account.
4. The transaction status will be set to InProgress
5. When the funds transfer is complete, the transaction status will be set to Received
6. Asychronously, the Upward platform will send you a webhook message corresponding to this hold action with an eventName of creditline.transaction.cleared

The Close Stage

Once the transaction is in Received state, then it is ready to be closed.

1. Consumer requests to record the closing of the transaction by calling /v2/credit-line/{credit_line_id}/transactions/{transaction_id}/close/
2. The Upward API will immediately return a response indicating that the close request was successful, or an error if the request was unable to be processed.
3. The Upward Platform will begin to pay off the transaction balance from the consumer’s account.
4. When the funds transfer is complete, the transaction status will be set to Completed
5. Asychronously, the Upward platform will send you a webhook message corresponding to this hold action with an eventName of creditline.transaction.closed

You can read more about transaction statuses here.