Purchase Flow

Recording transactions with Upwardli 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 or the Transaction Webhooks.

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 Upwardli API will immediately return a response containing the new transaction id. This transaction ID is immediately ready to use.
  3. Asychronously, the Upwardli 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 Upwardli 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 Upwardli 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 Upwardli 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 Upwardli 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 Upwardli 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 Upwardli 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.