Skip to main content
This guide covers a more advanced marketplace integration where buyers have their own Consul accounts connected via OAuth. Funds flow from the buyer’s account into your platform’s central Consul account (escrow), and you release them to sellers when conditions are met. If you don’t need escrow or user-facing Consul accounts, see the simpler Adding Payouts to a Marketplace tutorial.

​
Prerequisites

WhatWhyWhere to get it
Consul API keyAuthenticate requests from your central (escrow) accountDashboard
OAuth credentials (client_id, client_secret, redirect_uri)Connect buyer Consul accounts to your appProvided during app registration with Consul
Webhook endpointTrack payout and deposit status updatesEvents and Webhooks

​
Architecture

Two sets of credentials are in play:
  • OAuth access tokens (per buyer) — used to move funds from a buyer’s Consul balance during checkout.
  • API key (your central account) — used to release funds to sellers on completion.

​
Connect Buyer Accounts

Use the OAuth authorization code flow to let buyers link their Consul accounts. When a buyer connects, you receive an access token scoped to their account. Store it (along with the refresh token) per user. The buyer sees a Consul consent screen and grants your app permission to initiate transfers on their behalf. See the OAuth Connections guide for the full implementation, including token refresh and revocation.

​
Checkout: Collect Funds into Escrow

When a buyer checks out, use their OAuth access token to call Create a Payout on their behalf. The payout recipient is your platform’s own Consul account (by email or recipient ID). This moves USDC from the buyer’s balance into yours - effectively placing funds in escrow. Before initiating the payout, check the buyer’s balance via GET /balance (using their OAuth token). If the balance is insufficient, you can request deposit instructions via the Deposits API on their behalf so they can fund their account. Listen for the deposit.updated webhook to know when funds arrive, then notify the buyer that their balance is ready and they can complete checkout.

​
Release: Payout to Seller

When your platform’s conditions are met - delivery confirmed, milestone completed, dispute resolved - release funds to the seller by calling Create a Payout with your API key. Target the seller by email. If the seller doesn’t have a Consul account yet, they’ll receive an email invite to claim their funds. Track settlement via payout.updated webhooks or by polling the Payouts API.

​
Creating a Wallet UI

With OAuth, you can surface each buyer’s Consul account details directly in your UI - effectively white-labelling Consul as a wallet in your platform. Use the buyer’s OAuth token to: This lets buyers view their funds and transaction history without ever leaving your app.

​
Refunds

If a dispute is resolved in the buyer’s favor, issue a payout from your central account back to the buyer’s email using the same Create a Payout endpoint.