Donation campaigns deploy a dedicated on-chain wallet per campaignId. Share walletAddress with donors, they send USDC from any wallet, any amount. Videpay tracks contributions, quotes fees, handles unsupported tokens, and sweeps or refunds based on goalUsd, deadline, and expiryAction. No hosted donate page yet; the campaign wallet address is the shareable link. Fundraising with block explorer receipts, transparency goes hard.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
You create campaignId campaign_id with goalUsd 50000 and a 30-day deadline. You post walletAddress on your site and Discord. Supporters send 5, 50, or 500 USDC whenever they want. You monitor donation.received webhooks, then POST /donations/campaigns/:campaign_id/sweep when ready to move funds to settlementAddress.
You might be staring at two different on-chain addresses in Videpay and thinking: why are these not the same thing? Respectfully, they are built for different vibes.
Two addresses, two jobs
Deposit session address (checkout / payments) is for exact invoices, you set a fixed `amount` when creating the session, and Videpay configures the on-chain route with that `expectedAmount`. Partial sends are tracked until the total is met; overpayment is settled up to the expected amount and the surplus is returned automatically. It's giving 'pay exactly 49.99 USDC for order #1042.' Donation campaign `walletAddress` is for open contributions, donors send whatever they want (5 USDC, 50, 500), there is no fixed session total, and you aggregate toward `goalUsd` over time. It's giving 'support the project whenever, however much.' Donation protocol fees are also lower than deposit session fees. Use deposits when the amount is the contract; use donations when the amount is the community's choice.
Dashboard → Donations
Create campaigns with goal, deadline, and expiry action. View raised progress, copy walletAddress to share with donors, reconcile mismatches, sweep to treasury, refund individual donors, and recover unsupported tokens: each action maps to the API endpoints below.
Preview protocol fee before showing net proceeds to donors. Donation fees use the Donation fee bucket, lower than deposit sessions. Use `token`: `"USDC"` and a human `amount`, same shape as checkout and transfers.
Human amounts and token symbols
Quote fee, sweep, and most campaign actions accept `token`: `"USDC"` and `amount`: `"100"`.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
campaignId | string | No | Optional campaign scope for fee context. |
token | string | Yes | Donation token symbol for the chain (e.g. `"USDC"`): same as checkout, transfers, and subscriptions. |
amount | decimal string | Yes | Human-readable donation amount (e.g. `"100"` for 100 USDC). Responses include `amount.raw` for reconciliation. |
/donations/quote-feeQuote fee for a donation amount against a campaign or token.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base",04 "campaignId": ":campaign_Id",05 "token": "USDC",06 "amount": "100"07}| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
campaignId | string | Yes | Your campaign identifier (max 120). Used in URLs and API paths: e.g. campaign_id. |
title | string | Yes | Public campaign title (max 160 characters). |
goalUsd | decimal string | No | Fundraising goal in USD human units (up to 6 decimals). Omit for open-ended campaigns. |
deadline | integer | No | Unix timestamp in seconds. Omit for campaigns without an expiry. |
expiryAction | enum | No | When deadline passes without meeting goal: refund_donors or sweep_to_treasury (default sweep_to_treasury). |
settlementAddress | address | No | Address receiving net sweep proceeds. Defaults to merchant settlement wallet when omitted. |
/donations/campaignsCreate a donation campaign. Emits donation.campaign.created.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base",04 "campaignId": ":campaign_Id",05 "title": "New Microphone Fund",06 "goalUsd": "50000",07 "deadline": 1767225600,08 "expiryAction": "sweep_to_treasury",09 "settlementAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"10}/donations/campaigns?limit=20List donation campaigns for the business.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/donations/campaigns/:campaign_IdRetrieve campaign details including wallet address and progress.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/donations/campaigns/:campaign_Id/closeManually close a campaign. Emits donation.campaign.closed.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{}List detected contributions, manually detect a transfer by txHash, or reconcile campaign state with on-chain balances.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
txHash | string | Yes | Transaction hash of the donor transfer. |
logIndex | integer | No | Log index within the transaction (default 0). |
/donations/campaigns/:campaign_Id/transfers?limit=20List transfers detected for a campaign.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/donations/campaigns/:campaign_Id/transfersManually detect a donation transfer by txHash and log index. Emits donation.received when confirmed.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base",04 "txHash": "0xdonate...",05 "logIndex": 006}/donations/campaigns/:campaign_Id/reconcileReconcile campaign raised amounts with on-chain wallet balances.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{}| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
donorRef | string | No | Donor reference from transfer record: path param on refund endpoint. |
token | string | No | Token to sweep (e.g. `"USDC"`) or recover. For unsupported tokens not in your registry, pass the contract address. |
sweepRef | string | No | Your reconciliation reference for the sweep. |
/donations/campaigns/:campaign_Id/sweepSweep net campaign balance to settlementAddress. Emits donation.campaign.swept.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base",04 "token": "USDC",05 "sweepRef": "treasury-sweep-march"06}/donations/campaigns/:campaign_Id/refunds/donor-001Refund a specific donor by donorRef.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{}/donations/campaigns/:campaign_Id/recover/tokenRecover unsupported ERC-20 tokens sent to the campaign wallet.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base",04 "token": "0xUnsupportedToken1234567890123456789012345678"05}/donations/campaigns/:campaign_Id/recover/nativeRecover native ETH/MATIC accidentally sent to the campaign wallet.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "businessId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",03 "chain": "base"04}| Field | Type | Required | Description |
|---|---|---|---|
campaignId | string | No | Your stable campaign identifier: API paths and public URL slug. |
goalUsd | decimal string | No | Fundraising target in USD human units (6 decimal precision on-chain). |
deadline | integer | No | Unix timestamp in seconds. Omitted for open-ended campaigns. |
expiryAction | enum | No | refund_donors or sweep_to_treasury when deadline passes without meeting goal. |
settlementAddress | address | No | Receives net sweep proceeds. Defaults to merchant settlement wallet. |
raisedUsd / walletAddress | string / address | No | Progress metric and on-chain deposit address for donors. |
Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
donation.campaign.createdSent when a campaign is created and wallet deployment is queued.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: donation.campaign.created04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...donation.campaign.closedSent when a campaign is manually closed.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: donation.campaign.closed04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...donation.campaign.sweptSent when campaign funds are swept to settlementAddress.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: donation.campaign.swept04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...donation.receivedSent when a supported USDC donation is detected on-chain.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: donation.received04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...donation.unsupported_tokenSent when a donor sends a token other than the campaign's supported asset.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: donation.unsupported_token04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...