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:
- Create a wallet for each consumer or business you pay out to.
- Add an external bank account that funds can be sent to and from.
- Create payments from the wallet over ACH, EFT, RTP, or Book Transfer, through the API or the embedded component.
- 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.
- Consumers: see the create consumer API.
- Businesses: see the create business API.
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.
- Start onboarding for the entity with the create onboarding API.
- Select the wallet product with the select product API.
- Verify identity (KYC or KYB) with the verify identity API.
- Accept terms with the accept terms API.
- Wait for provisioning. Upward opens the wallet at the sponsor bank and sends the
Onboarding.Completedwebhook. 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:
- Consumer Wallet Onboarding
- Business Wallet Onboarding
- Handling a Fallback Inquiry if identity verification needs more information
- Handling Drop-offs & Resuming Onboarding if a user leaves before finishing
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-hosted Plaid: Upward generates a Plaid Link token and verifies the account for you. See the Plaid Integration and Post Onboarding Plaid Integration guides, and the create Plaid link token and verify bank account APIs.
- Your own Plaid instance: described below.
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.
- Complete Plaid Link in your application and exchange the public token for a Plaid
access_token. - Call the create consumer bank account API with the consumer’s
consumer_id,routing_number,account_number,bank_name, andaccount_name, plus theplaid_account_idandplaid_access_tokenfrom your Plaid instance. - Confirm the account with the list consumer bank accounts API or the
Consumer.BankAccount.Createdwebhook.
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:
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.
- ACH: create ACH request
- EFT: create EFT request
- RTP: create instant payment. See the Instant Payments guide for RTP eligibility and balance requirements.
- Book Transfer: create transfer
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.
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:
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.

