@flopay/node 1.9.18 → 1.9.19

package/README.md

@@ -45,6 +45,14 @@ To authorise an eligible one-time card cart without capturing it, pass `captureM
 
 Saved-card management is also not an `@flopay/node` credential surface. From trusted server code, use the authenticated REST API to list display-only payment methods, create a setup session, and delete an eligible method, then pass only the setup session's `sessionId` and `nonce` to `FloPayCardSetup` in `@flopay/react`. Replace a card setup-first, then delete, so a failed or cancelled setup leaves the existing card intact. See the [payment methods reference](https://flopay.com/docs/technical-reference/rest/payment-methods).
 
+Type the setup request body with `CreateCardSetupSessionRequest` from `@flopay/shared`. Alongside the required `userId` and the optional `successUrl` and `cancelUrl`, it accepts transaction context your server may already know, which the billing API routes card verification on. Each field is optional and independent of the others, and a request without any of them stays valid and unchanged:
+
+- `country`: the ISO 3166-1 alpha-2 country the card will be used in.
+- `currency`: the three-letter currency later payments will be charged in. A supplied `currency` becomes the setup session's currency.
+- `futureUse`: `'on_session'` or `'off_session'` (`CardSetupFutureUse`). Send `'on_session'` only when the card will be charged only while the customer is present. For cards charged without the customer present, including cards used both ways, leave it out or send `'off_session'`.
+
+The context needs billing API v1.9.48 or later. Older billing APIs silently ignore it and set the card up exactly as before. Send values as you hold them: the billing API trims and uppercases `country` and `currency`, validates all three fields, and rejects an invalid value with a `400`. The context describes the transaction and never selects a gateway; the billing API alone decides which gateway verifies the card.
+
 ### Stripe checkout sessions and customers
 
 `checkout.sessions.retrieve()`, `expire()`, and `listLineItems()` call Stripe directly and normalize the result. `customers.create()`, `retrieve()`, and `update()` manage Stripe customers and return a normalized `Customer`.
@@ -101,6 +109,30 @@ if (result.status === 201 && 'redirectUrl' in result) {
 }
 ```
 
+Type a card-setup request with optional transaction context, send it with the billing API client your server already authenticates, and return only the session handle for `FloPayCardSetup`:
+
+```ts
+import type { CreateCardSetupSessionRequest } from '@flopay/shared';
+
+// Your server's existing billing API client; it adds your merchant authentication.
+type AuthenticatedPost = (
+  path: string,
+  body: CreateCardSetupSessionRequest,
+) => Promise<{ data: { uuid: string; nonce: string } }>;
+
+export async function createCardSetupSession(post: AuthenticatedPost, userId: string) {
+  const request: CreateCardSetupSessionRequest = {
+    userId,
+    country: 'GB',
+    currency: 'GBP',
+    futureUse: 'off_session',
+  };
+  const { data } = await post('/v1/checkouts/sessions/setup', request);
+
+  return { sessionId: data.uuid, nonce: data.nonce };
+}
+```
+
 Verify a Stripe webhook in a plain Node.js HTTP server:
 
 ```ts
@@ -189,6 +221,8 @@ console.log(updated.email, session.status, session.amount);
 
 The parameter and result types (`CreateSessionParams`, `CheckoutSessionResult`, `CheckoutSession`, `Customer`, `LineItem`, `WebhookEvent`) are exported by `@flopay/shared`.
 
+`@flopay/node` has no card-setup method and holds no merchant credential. `CreateCardSetupSessionRequest` and `CardSetupFutureUse`, also exported by `@flopay/shared`, type the body your server sends to the authenticated `POST /v1/checkouts/sessions/setup` route with its own billing API client.
+
 ## Errors
 
 SDK validation and billing API failures are `FloPayError`s from `@flopay/shared`; branch on `type` and `code`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flopay/node",
-  "version": "1.9.18",
+  "version": "1.9.19",
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "stripe": "^22.2.1",
-    "@flopay/shared": "1.9.18"
+    "@flopay/shared": "1.9.19"
   },
   "devDependencies": {
     "tsup": "^8.3.0",