@mindtdilly / Omnipay
Code Commits Issues Pulls Sessions CI/CD
feat/agentic-commerce-x402-local-sim
feat/agentic-commerce-x402-local-sim feat/checkout-funding-ach main
mdx 208 lines 6.62 KB
Raw
1 ---
2 title: "Funding Method — Bind Payment to Procurement Session"
3 sidebarTitle: "POST /funding-method"
4 description: "Bind a payment method to an active procurement session. Accepts USDC on-chain, card, or bank transfer. Replaces the deprecated POST /api/payments/route."
5 ---
6
7 Once a procurement session is ready for payment, this endpoint binds a funding method to it. You specify the method type — USDC, card, or bank transfer — and for USDC payments, the target blockchain network. ProcureNet validates the combination against the session's state and the buyer's entitlements, then advances the session toward payment processing. This endpoint replaces the deprecated `POST /api/payments/route` — if your integration still uses that path, follow the migration guidance at the bottom of this page.
8
9 ## Authentication
10
11 <Warning>
12 This endpoint requires a valid Bearer JWT in the `Authorization` header. Requests without a token, or with an expired or malformed token, receive `401 Unauthorized`.
13 </Warning>
14
15 ```
16 Authorization: Bearer <your_jwt>
17 ```
18
19 ## Path Parameters
20
21 <ParamField path="id" type="string" required>
22 The session ID returned by `POST /api/v7/orchestrate`. The session must be in a state that accepts a funding method (for example, `pending_payment` or `escrow_accepted`).
23 </ParamField>
24
25 ## Request Body
26
27 <ParamField body="method" type="string" required>
28 The payment method to bind to this session. Accepted values:
29
30 | Value | Description |
31 |---|---|
32 | `usdc` | On-chain USDC transfer. Requires the `network` field. |
33 | `card` | Credit or debit card. Network field is ignored. |
34 | `bank_transfer` | ACH or wire transfer. Network field is ignored. |
35 </ParamField>
36
37 <ParamField body="network" type="string">
38 The blockchain network for USDC transfers. Required when `method` is `"usdc"`. Ignored for all other methods.
39
40 Supported values: `base`, `arbitrum`, `polygon`, `ethereum`.
41
42 <Tip>
43 `base` offers the lowest gas fees for most USDC transfers and is the recommended network unless your buyer or contract rules require otherwise.
44 </Tip>
45 </ParamField>
46
47 ## Request Examples
48
49 <CodeGroup>
50
51 ```typescript USDC on Base
52 const sessionId = 'sess_abc123';
53
54 const res = await fetch(
55 `https://api.procurenet.io/api/v7/sessions/${sessionId}/funding-method`,
56 {
57 method: 'POST',
58 headers: {
59 'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
60 'Content-Type': 'application/json'
61 },
62 body: JSON.stringify({
63 method: 'usdc',
64 network: 'base'
65 })
66 }
67 );
68
69 const result = await res.json();
70 ```
71
72 ```typescript Card Payment
73 const sessionId = 'sess_abc123';
74
75 const res = await fetch(
76 `https://api.procurenet.io/api/v7/sessions/${sessionId}/funding-method`,
77 {
78 method: 'POST',
79 headers: {
80 'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
81 'Content-Type': 'application/json'
82 },
83 body: JSON.stringify({
84 method: 'card'
85 })
86 }
87 );
88
89 const result = await res.json();
90 ```
91
92 ```typescript Bank Transfer
93 const sessionId = 'sess_abc123';
94
95 const res = await fetch(
96 `https://api.procurenet.io/api/v7/sessions/${sessionId}/funding-method`,
97 {
98 method: 'POST',
99 headers: {
100 'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
101 'Content-Type': 'application/json'
102 },
103 body: JSON.stringify({
104 method: 'bank_transfer'
105 })
106 }
107 );
108
109 const result = await res.json();
110 ```
111
112 </CodeGroup>
113
114 ## Response Fields
115
116 <ResponseField name="session_id" type="string" required>
117 Echoes back the session ID.
118 </ResponseField>
119
120 <ResponseField name="method" type="string" required>
121 Confirms the payment method that was bound to the session.
122 </ResponseField>
123
124 <ResponseField name="network" type="string">
125 The blockchain network confirmed for USDC transfers. Present only when `method` is `"usdc"`.
126 </ResponseField>
127
128 <ResponseField name="status" type="string" required>
129 The session status after the funding method was set. Typically `"payment_processing"` once the session advances.
130 </ResponseField>
131
132 ## Response Example
133
134 ```json
135 {
136 "session_id": "sess_abc123",
137 "method": "usdc",
138 "network": "base",
139 "status": "payment_processing"
140 }
141 ```
142
143 ## Supported Networks for USDC
144
145 <CardGroup cols={2}>
146 <Card title="Base" icon="circle-check">
147 Lowest fees. Recommended for most USDC transactions.
148 </Card>
149 <Card title="Arbitrum" icon="circle-check">
150 Low fees, high throughput. Good alternative to Base.
151 </Card>
152 <Card title="Polygon" icon="circle-check">
153 Widely supported. Use when buyer wallets are Polygon-native.
154 </Card>
155 <Card title="Ethereum" icon="circle-check">
156 Highest security and liquidity. Higher gas fees apply.
157 </Card>
158 </CardGroup>
159
160 ## Migration from POST /api/payments/route
161
162 <Note>
163 `POST /api/payments/route` is **deprecated** and will be removed in a future release. Migrate all integrations to the v7 session flow.
164 </Note>
165
166 Replace your existing single-call payment routing with the two-step v7 session pattern:
167
168 <Steps>
169 <Step title="Start an orchestration session">
170 Replace your call to `POST /api/payments/route` with a call to `POST /api/v7/orchestrate`. Pass your transaction amount, currency, and any buyer hints.
171
172 ```typescript
173 // Before (deprecated)
174 await fetch('/api/payments/route', {
175 method: 'POST',
176 body: JSON.stringify({ amount: 500, currency: 'USD', paymentMethod: 'usdc' })
177 });
178
179 // After
180 const session = await fetch('/api/v7/orchestrate', {
181 method: 'POST',
182 body: JSON.stringify({ amount: 500, currency: 'USD', hints: { email: 'buyer@example.com' } })
183 }).then(r => r.json());
184 ```
185 </Step>
186 <Step title="Set the funding method on the session">
187 Take the `session_id` from the orchestrate response and call this endpoint to bind your payment method.
188
189 ```typescript
190 await fetch(`/api/v7/sessions/${session.session_id}/funding-method`, {
191 method: 'POST',
192 headers: { 'Authorization': `Bearer ${jwt}` },
193 body: JSON.stringify({ method: 'usdc', network: 'base' })
194 });
195 ```
196 </Step>
197 </Steps>
198
199 ## Error Codes
200
201 | HTTP Status | Description |
202 |---|---|
203 | `400 Bad Request` | Missing required fields, unrecognized `method` value, or `method` is `"usdc"` but `network` is absent or invalid. |
204 | `401 Unauthorized` | Missing, expired, or invalid Bearer JWT. |
205 | `403 Forbidden` | The session state does not permit setting a funding method at this point (for example, escrow acceptance is still required). |
206 | `404 Not Found` | No session exists for the provided `id`. |
207 | `409 Conflict` | A funding method is already set for this session. Transition to a new session if you need to change it. |
208 | `410 Gone` | The session has expired. Start a new session with `POST /api/v7/orchestrate`. |