|
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> |