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