@mindtdilly / Omnipay-2
Code Commits Issues Pulls Sessions CI/CD
main
feat/agentic-commerce-x402-local-sim feat/checkout-funding-ach main
mdx 123 lines 5.61 KB
Raw
1 ---
2 title: "Automate Field Evaluator Payments with the VCI Bridge"
3 sidebarTitle: "Field Payments"
4 description: "Automatically pay field evaluators in USDC when their offline assessments sync — no manual intervention required for eligible score tiers."
5 ---
6
7 ProcureNet's VCI bridge connects your offline field evaluation queue directly to the USDC payment infrastructure. When a field evaluator completes assessments without connectivity and later comes back online, the bridge intercepts the sync event, calculates the appropriate USDC payout based on the evaluator's average score, creates a payment request, and fires a wallet event your UI can listen to. You handle the UI feedback; ProcureNet handles the on-chain settlement.
8
9 ## How the Payment Flow Works
10
11 <Steps>
12
13 ### Evaluator Completes Assessments Offline
14
15 Field evaluators submit assessments through your app while disconnected. These records are queued locally on the device until connectivity is restored.
16
17 ### Evaluation Queue Syncs on Reconnect
18
19 When the device comes back online, the evaluation queue syncs and fires a `vci-sync-status` browser event. This is the trigger that kicks off the automated payment flow.
20
21 ### VCIProcureNetBridge Calculates the Payout
22
23 The bridge intercepts `vci-sync-status`, reads the evaluator's average score across all synced assessments, and maps that score to a USDC payout tier.
24
25 | Avg Evaluation Score | USDC Payout |
26 |---|---|
27 | ≥ 9.0 | 500 USDC |
28 | ≥ 7.0 | 250 USDC |
29 | ≥ 5.0 | 100 USDC |
30 | < 5.0 | 0 USDC (no payment) |
31
32 ### Payment Request Is Created and Attached
33
34 The bridge calls `POST /mods/procurement_wallet/usdc/request` to create a USDC payment request on the Base network by default. The response includes a `deposit_address` and an optional `qr_code`. Both are attached to the evaluation record for traceability.
35
36 GPS metadata captured by the field device — latitude, longitude, accuracy, and timestamp — is automatically included in the payment request metadata, creating a location-stamped audit record.
37
38 ### `vci-wallet-sync` Event Fires
39
40 Once the payment request is created, the bridge dispatches a `vci-wallet-sync` browser event containing the payment details. Your UI can listen for this event to show confirmation feedback to the evaluator.
41
42 ### ProcureNet Watches for On-Chain Confirmation
43
44 If you instantiate the bridge with `autoWatch: true`, ProcureNet polls `GET /mods/procurement_wallet/usdc/watch/{paymentId}` automatically and resolves the payment once the transaction is confirmed on-chain. If `autoWatch` is false, you trigger confirmation manually.
45
46 </Steps>
47
48 ## Setting Up the Bridge
49
50 Instantiate `ProcureNetWalletClient` with your API key and bridge configuration, then pass it to `VCIProcureNetBridge` along with your evaluation queue and a tenant resolver function.
51
52 ```typescript
53 import { VCIProcureNetBridge, ProcureNetWalletClient } from './integrations/VCIProcureNetBridge';
54
55 const wallet = new ProcureNetWalletClient(
56 'https://api.procurenet.io',
57 process.env.PROCURENET_API_KEY!,
58 { autoWatch: true }
59 );
60
61 const bridge = new VCIProcureNetBridge(queue, wallet, () => 'tenant_abc');
62 ```
63
64 <Note>
65 The `x-perplexity-mod-key` header is set automatically from the API key you pass to `ProcureNetWalletClient`. You do not need to attach it manually to wallet endpoint calls.
66 </Note>
67
68 ## Supported Networks
69
70 ProcureNet's USDC bridge supports the following networks. Payments default to **Base** unless you configure an alternative network:
71
72 <CardGroup cols={2}>
73 <Card title="Base" icon="circle-b">
74 Low-fee L2 — the default network. Recommended for high-volume field payment operations.
75 </Card>
76 <Card title="Arbitrum" icon="circle-a">
77 High-throughput L2 with strong DeFi ecosystem support.
78 </Card>
79 <Card title="Polygon" icon="hexagon">
80 Fast finality and broad wallet compatibility for field devices.
81 </Card>
82 <Card title="Ethereum" icon="ethereum">
83 Mainnet settlement for maximum finality guarantees on high-value payments.
84 </Card>
85 </CardGroup>
86
87 ## Listening for Payment Events
88
89 Register a `vci-wallet-sync` listener in your frontend to surface payment confirmation details to the evaluator as soon as the payment request is created.
90
91 ```typescript
92 window.addEventListener('vci-wallet-sync', (event) => {
93 const { paymentId, amount, qrCode, expiresAt } = (event as CustomEvent).detail;
94 console.log(`Payment ${paymentId} created for ${amount} USDC`);
95 // Render qrCode and expiresAt in your UI for the evaluator to track
96 });
97 ```
98
99 ## Manual Confirmation
100
101 If you instantiate the bridge with `autoWatch: false`, you are responsible for triggering on-chain confirmation. Call `bridge.manualConfirmPayment` with the local evaluation record ID and your admin key.
102
103 ```typescript
104 const result = await bridge.manualConfirmPayment(localId, adminKey);
105
106 if (result.confirmed) {
107 console.log('Transaction hash:', result.transaction_hash);
108 }
109 ```
110
111 <Tip>
112 Use `autoWatch: true` for production deployments unless you have a specific reason to gate confirmation — it eliminates the need for a manual confirmation step and reduces payment latency.
113 </Tip>
114
115 ## GPS Metadata Attachment
116
117 <Info>
118 Location metadata is attached automatically. If the field device has GPS enabled, the bridge reads `lat`, `lng`, `accuracy`, and `timestamp` from the device context and includes them in the payment request metadata sent to ProcureNet. No additional configuration is required.
119 </Info>
120
121 <Warning>
122 Evaluations with an average score below 5.0 receive no USDC payment. Verify your scoring rubrics and calibration against this threshold before deploying the bridge to production — evaluators below the floor will not receive a payout regardless of submission volume.
123 </Warning>