Skip to navigation

Building a Direct Payout Program

Overview

The Direct Payout product enables partners to launch a payments platform, supporting both consumer and business payment rails.

A Direct Payout program follows four steps:

  1. Create a wallet for each consumer or business you pay out to.
  2. Add an external bank account that funds can be sent to and from.
  3. Create payments from the wallet over ACH, EFT, RTP, or Book Transfer, through the API or the embedded component.
  4. Register for webhooks so your system is notified as onboarding and payments progress.

For a comparison of the supported payment rails, see the Payments Overview guide.

Partner Steps

1. Creating A Consumer or Business Wallet

Every payout starts from a wallet held at Upward’s sponsor bank. Partners first create the entity (a consumer or a business), then run it through wallet onboarding. When onboarding is complete, the entity has a provisioned wallet that can send and receive funds.

Creating a Consumer or Business via API

Before partners can start onboarding, partners need to create the entity via API. Use a partner token for these calls. The pcid you provide is your own identifier for the entity and must be unique across your consumers and businesses.

Outcome: an Upward id for the consumer or business, which you use in every following step.

Onboarding the Newly Created Entity

Wallet onboarding is the same flow for consumers and businesses. The entity type decides how identity is verified (KYC for consumers, KYB for businesses), and the selected wallet product decides which sponsor bank the wallet is set up at.

  1. Start onboarding for the entity with the create onboarding API.
  2. Select the wallet product with the select product API.
  3. Verify identity (KYC or KYB) with the verify identity API.
  4. Accept terms with the accept terms API.
  5. Wait for provisioning. Upward opens the wallet at the sponsor bank and sends the Onboarding.Completed webhook. You can also poll the get onboarding API.

Outcome: a verified consumer or business with an active wallet.

For full request and response examples, see:

2. Adding an External Bank Account reference

To pay out to a bank account outside of Upward, the entity needs an external bank account on file. The account stores the routing and account number used as the destination for ACH and RTP payments.

Partners can add external accounts in two ways:

Upward sends Consumer.BankAccount.Created once the account is added, and Consumer.BankAccount.VerificationFailed if the account holder does not match the consumer on file. See Bank Account Management Webhooks.

Adding an External Bank Account Via your own Plaid Instance

If you already run Plaid Link in your application, you can register the linked account with Upward instead of having the consumer link it a second time.

  1. Complete Plaid Link in your application and exchange the public token for a Plaid access_token.
  2. Call the create consumer bank account API with the consumer’s consumer_id, routing_number, account_number, bank_name, and account_name, plus the plaid_account_id and plaid_access_token from your Plaid instance.
  3. Confirm the account with the list consumer bank accounts API or the Consumer.BankAccount.Created webhook.

Outcome: an external bank account linked to the entity, ready to receive payouts.

3. Creating Payments

With a funded wallet and an external account in place, partners can move money. Choose the rail based on speed and cost:

RailUse it forSpeed
ACHA US Standard, low-cost payouts to an external bank accountStandard ACH settlement
EFT (Canada Only)A Canadian Standard, low-cost payouts to an external bank accountStandard EFT settlement
RTP (Instant)Urgent payouts to an external bank account. A fee applies.Real time
Book TransferMoving funds between accounts inside the Upward ecosystemImmediate

See the Payments Overview guide for details on each rail.

Creating a Payment using the Upward APIs

Create payments directly from your backend. These calls require the api:write or api:purchase:write scope.

Each payment is returned with an ID and status. Track it to completion with the payment webhooks (see step 4) or the matching retrieve and list endpoints.

Outcome: a payment created on the selected rail, moving funds from the wallet to the destination account.

Creating a Payment Via the Upward Embedded Component

If you don’t want to build your own payout UI, send the consumer to the hosted Direct Payout component. The consumer selects the destination account and amount, and Upward creates the payment.

URL: https://component-embedded-sandbox.upwardli.com/en/direct-payout/?access_token=

This component uses a consumer scoped token. Partner token will not work here.
Use the token exchange API to get a new consumer token. See Token Exchange for details.

To react to events inside the component, such as completion, see Component Messaging.

Outcome: a payment initiated by the consumer, with the same webhooks as an API-created payment.

4. Registering for Webhook Notifications

Webhooks tell your system when onboarding finishes and when payments change status, so you don’t need to poll. Use the register webhook API to subscribe to these events:

EventWhen it is sent
Onboarding.StartedThe entity’s wallet onboarding was started.
Onboarding.(Step).*Each individual step was “Successful” or “Failed”.
Onboarding.CompletedThe entity’s wallet is provisioned and ready for payouts.
Consumer.BankAccount.Created / Consumer.BankAccount.VerificationFailedAn external bank account was added, or failed verification.
Payment.ACH.*An ACH payment was created, completed, failed, or canceled.
Payment.EFT.*An EFT payment was created, completed, failed, or canceled.
Payment.Instant.*An RTP payment was created, sent, completed, failed, or canceled.
Payment.Transfer.*A Book Transfer was created, completed, failed, or canceled.

Outcome: your system receives status updates for every entity and payment in the program.

For the full list of events, see the Webhook Event Catalog. To manage registrations and verify signatures, see Registration and Security.