@finverse/sdk-typescript 0.0.373 → 0.0.374

package/README.md

@@ -1,293 +1,459 @@
-# Finverse API - Typescript SDK
-This SDK enables a basic end-to-end backend integration with the Finverse API, including API authentication, institution linking, and data retrieval.
+# Finverse API - TypeScript SDK
+
+This SDK enables end-to-end backend integration with the Finverse API, including API authentication, institution linking, data retrieval, and payment operations.
 
 ## Installation
+
 ```
 npm install @finverse/sdk-typescript
 ```
 
-## Getting started (Linking flow)
+## API Overview
+
+The SDK is organized into two main API categories:
+
+| API | Purpose |
+|-----|---------|
+| **Payment API** | Create payment links, mandates, payments, and manage payment accounts |
+| **Data API** | Retrieve accounts, transactions, statements, balance history, and identity data |
+
+Both APIs share authentication and linking flows via `PublicApi` and `LinkApi`.
+
+---
+
+## Payment API
+
+The Payment API enables you to create payment links for checkout, initiate payments, manage mandates, and handle payment-related operations.
+
+### Key Classes & Methods
+
+| Class | Key Methods |
+|-------|-------------|
+| `CustomerApi` | `createPayment`, `getPayment`, `createMandate`, `getMandate`, `authorizeMandate`, `createPaymentUser`, `createPaymentAccount`, `listPaymentAccounts` |
+| `DefaultApi` | `createPaymentLink`, `getPaymentLink`, `cancelPaymentLink`, `createScheduledPayout`, `getPayoutById`, `createPaymentMethod` |
+
+### Payment Flow (End-to-End)
+
+The payment link flow: **Create** → **Redirect** → **Callback** → **Poll** → **Result**.
+
+1. **Create** – Create payment link via API, get `url` and `payment_link_id`. Save both and `unique_reference_id`.
+2. **Redirect** – Redirect user to the payment link URL (use HTTP 303 so the redirect is followed with GET).
+3. **Callback** – Finverse redirects back with `payment_link_id` and `unique_reference_id` query params. Verify they match what you stored.
+4. **Poll** – Poll `GET /payment_links/{paymentLinkId}` every 2 seconds for up to 30 seconds until `session_status` is `"COMPLETE"`.
+5. **Result** – If `COMPLETE` → success; otherwise → error.
+
+> **Security:** `FINVERSE_CLIENT_ID` and `FINVERSE_CLIENT_SECRET` must **never** be committed to git or sent to the frontend. Use them only on the server (e.g. environment variables, secrets manager).
+
+#### 1. Authenticate: Obtain Customer Access Token
 
-### 1. Authenticate with Finverse API: Obtain Customer Access Token
 ```typescript
-// Obtain these from https://dashboard.finverse.com
-const apiHost = "https://api.sandbox.finverse.net"
-const clientId = process.env.FINVERSE_CLIENTID
-const clientSecret = process.env.FINVERSE_SECRET
-const redirectUri = process.env.REDIRECT_URI
+import { Configuration, PublicApi } from '@finverse/sdk-typescript';
+
+const apiHost = process.env.FINVERSE_BASE_URL ?? "https://api.prod.finverse.net";
+const clientId = process.env.FINVERSE_CLIENT_ID;
+const clientSecret = process.env.FINVERSE_CLIENT_SECRET;
 
 const configuration = new Configuration({ basePath: apiHost });
-// Obtain customer access token
 const customerTokenResp = await new PublicApi(configuration).generateCustomerAccessToken({
-	client_id: clientId,
-	client_secret: clientSecret,
-	grant_type: 'client_credentials',
+  client_id: clientId,
+  client_secret: clientSecret,
+  grant_type: 'client_credentials',
 });
 
-const customerAccessToken = customerTokenResp.access_token
+const customerAccessToken = customerTokenResp.data.access_token;
+// Cache the token; refresh before expiry (use expires_in minus 60s buffer)
 ```
 
-### 2. Link new institution: Obtain Link Token and Link URL to launch Finverse Link UI
+#### 2. Create Payment Link
+
+**Payment mode** – For one-time payments. Requires `amount` (minor units, e.g. 10000 = 100.00 HKD), `currency`, `sender`, `payment_details`, and `link_customizations` with `redirect_uri`:
+
 ```typescript
-// generate a link token
-
-// reference back to your system userId, finverse does not use this
-const userId = "someUserId"     
-// this will be sent in the redirectUri callback, can be used to identify the state
-const state = "someUniqueState" 
-const configuration = new Configuration({ 
-	basePath: apiHost, 
-	accessToken: customerToken.access_token
+import { DefaultApi } from '@finverse/sdk-typescript';
+import crypto from 'crypto';
+
+const configuration = new Configuration({
+  basePath: apiHost,
+  accessToken: customerAccessToken,
 });
-const linkTokenResp = await new CustomerApi(configuration).generateLinkToken({
-	client_id:     clientId,
-        user_id:       userId,
-        redirect_uri:  redirectUri,
-        state:        state,
-        response_mode: "form_post",
-        response_type: "code",
-	grant_type:    "client_credentials",
+const defaultApi = new DefaultApi(configuration);
+
+const uniqueReferenceId = crypto.randomUUID();
+const callbackUrl = process.env.CALLBACK_URL; // e.g. https://yoursite.com/callback
+
+const createResp = await defaultApi.createPaymentLink({
+  mode: "PAYMENT",
+  amount: 10000,  // 100.00 HKD
+  currency: "HKD",
+  unique_reference_id: uniqueReferenceId,
+  sender: {
+    external_user_id: "your-internal-user-id",
+    name: "Customer Name",
+    email: "customer@example.com",
+  },
+  payment_details: {
+    description: "Order #12345",
+    external_transaction_reference: "order-12345",  // max 35 chars
+  },
+  link_customizations: {
+    ui_mode: "redirect",
+    redirect_uri: callbackUrl,
+  },
 });
 
-// The linkUrl can be used to initiate Finverse Link
-console.log("linkUrl: " + linkTokenResp.link_url)
+const paymentLinkId = createResp.data.payment_link_id;
+const paymentUrl = createResp.data.url;
+
+// Store paymentLinkId and uniqueReferenceId for callback verification
 ```
 
-### 3. Finalize linking: Exchange code for Login Identity Access Token
+**Setup mode** – For saving payment methods (e.g. Click to Pay). Do **not** pass `amount`:
+
 ```typescript
-// when Finverse Link UI is successful, obtain the code from Finverse Link
-// exchange it for a Login Identity Access Token
-const code = "obtainAfterLink"
-const configuration = new Configuration({ 
-	basePath: apiHost, 
-	accessToken: customerToken.access_token 
+const createResp = await defaultApi.createPaymentLink({
+  mode: "SETUP",
+  currency: "HKD",
+  unique_reference_id: uniqueReferenceId,
+  sender: {
+    external_user_id: "your-internal-user-id",
+    name: "Customer Name",
+    email: "customer@example.com",
+  },
+  payment_details: {
+    description: "Save payment method",
+    external_transaction_reference: "setup-12345",
+  },
+  link_customizations: {
+    ui_mode: "redirect",
+    redirect_uri: callbackUrl,
+  },
+  payment_setup_options: {
+    future_payments: "CLICK_TO_PAY",
+  },
 });
-const loginIdentityTokenResp = await new LinkApi(configuration).token(
-	"authorization_code",
-	code,
-	clientId,
-	redirectURI,
-);
-
-// The loginIdentityToken can be used to retrieve data
-const loginIdentityToken = loginIdentityTokenResp.access_token
 ```
 
-### 4. Retrieve data: Get data using Login Identity Access Token
-```typescript
-// get LoginIdentity
-const configuration = new Configuration({
-	basePath: apiHost,
-	accessToken: loginIdentityToken.access_token 
-});
-const loginIdentityResp = await new LoginIdentityApi(configuration).getLoginIdentity();
+#### 3. Redirect User to Payment URL
 
+Redirect the user to `paymentUrl`. **Use HTTP 303** so the browser follows with GET (Finverse expects GET):
 
-console.log("login identity: " + loginIdentityResp.login_identity)
-    
-// get other products (Accounts, Account Numbers, Transactions)
-```
 
+#### 4. Callback Handler: Poll for Completion
+
+When Finverse redirects back, read `payment_link_id` and `unique_reference_id` from query params. Verify they match your stored values, then poll until `session_status` is `COMPLETE`:
 
-### 5. Poll loginIdentityStatus until ready
 ```typescript
-enum FinalStatus {
-	ERROR = 'ERROR',
-	DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL = 'DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL',
-	DATA_RETRIEVAL_COMPLETE = 'DATA_RETRIEVAL_COMPLETE',
-}
+import { DefaultApi } from '@finverse/sdk-typescript';
+
+const paymentLinkId = req.query.payment_link_id as string;  // from callback URL
+const uniqueReferenceId = req.query.unique_reference_id as string;
+
+// Verify uniqueReferenceId matches what you stored
+// if (uniqueReferenceId !== storedUniqueReferenceId) { return error; }
 
 const configuration = new Configuration({
-	basePath: apiHost,
-	accessToken: loginIdentityToken.access_token 
+  basePath: apiHost,
+  accessToken: customerAccessToken,
 });
-let loginIdentity: AxiosResponse<GetLoginIdentityByIdResponse>;
-
-// Poll until loginIdentityStatus is ready
-for (let i = 0; i < 20; i++) {
-	loginIdentity = await new LoginIdentityApi(configuration).getLoginIdentity();
-	const loginIdentityStatus = loginIdentity.data.login_identity.status;
-	if ( 
-	  loginIdentityStatus === FinalStatus.ERROR ||
-	  loginIdentityStatus === FinalStatus.DATA_RETRIEVAL_COMPLETE ||
-	  loginIdentityStatus === FinalStatus.DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL
-	) { break; }
-	
-	await new Promise((resolve) => setTimeout(resolve, 3000));
-}
+const defaultApi = new DefaultApi(configuration);
 
-console.log("login identity: " + loginIdentityResp.login_identity)
-// get other products (Accounts, Account Numbers, Transactions)
-```
+const POLL_INTERVAL_MS = 2000;
+const POLL_TIMEOUT_MS = 30000;
+const startTime = Date.now();
 
-### 6. Get Accounts
-```typescript
-// Get Accounts
-const configuration = new Configuration({ basePath: apiHost, accessToken: loginIdentityToken.access_token });
-const accountsRsp = await new LoginIdentityApi(configuration).listAccounts();
+while (Date.now() - startTime < POLL_TIMEOUT_MS) {
+  const getResp = await defaultApi.getPaymentLink(paymentLinkId);
+  const sessionStatus = getResp.data.session_status;
 
-console.log("accounts: " + accountsResp.accounts)
-```
+  if (sessionStatus === "COMPLETE") {
+    // Success – redirect to success page
+    // Log getResp.data.payment for payment details
+    break;
+  }
 
-### 7. Get Transactions
-```typescript
-// Get Transactions with pagination using offset and limit
-let offset = 0
-while(true) {
-	const configuration = new Configuration({ basePath: apiHost, accessToken: loginIdentityToken.access_token });
-        const transactionsResp = await new LoginIdentityApi(configuration).listTransactionsByLoginIdentityId();
-
-	console.log(`total: ${transactionsResp.total_transactions}, transactions: ${transactionsResp.transactions}`)
-	offset += transactionsResp.transactions.length
-
-	if offset >= transactionsResp.total_transactions {
-			break
-	}
+  await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
 }
+
+// If loop ended without COMPLETE → timeout, show error page
 ```
 
-### 8. Get Statements
-```typescript
-// Get Statements metadata
-const configuration = new Configuration({ basePath: apiHost, accessToken: loginIdentityToken.access_token });
-const statements = await new LoginIdentityApi(configuration).getStatements();
+---
 
-console.log("statements: "  + statementsResp.statements)
+## Data API
 
-// Get link to statement
-// Assuming there is only one statement
-const statementId = statements.data.statements[0].id;
+The Data API enables you to retrieve financial data: accounts, transactions, statements, balance history, identity, and income estimates.
 
-// Can download statement from here 
-const statementResp = await new LoginIdentityApi(configuration).getStatement(statementId, true, {responseType: "arraybuffer"});
-writeFileSync("statement.pdf", Buffer.from(statementResp.data));
-```
+### Key Classes & Methods
+
+| Class | Key Methods |
+|-------|-------------|
+| `LoginIdentityApi` | `getLoginIdentity`, `listAccounts`, `getAccount`, `getAccountNumber`, `listTransactionsByLoginIdentityId`, `listTransactionsByAccountId`, `getStatements`, `getStatement`, `getBalanceHistory`, `getIdentity`, `getIncomeEstimateByLoginIdentityId`, `listCardDetails`, ` refreshLoginIdentity` |
+
+### Data Retrieval Flow (End-to-End)
 
-## Getting started (Payment flow)
+#### 1. Authenticate: Obtain Customer Access Token
 
-### 1. Authenticate with Finverse API: Obtain Customer Access Token
 ```typescript
-// Obtain these from https://dashboard.finverse.com
-const apiHost = "https://api.sandbox.finverse.net"
-const clientId = process.env.FINVERSE_CLIENTID
-const clientSecret = process.env.FINVERSE_SECRET
-const redirectUri = process.env.REDIRECT_URI
+import { Configuration, PublicApi } from '@finverse/sdk-typescript';
+
+const apiHost = "https://api.prod.finverse.net";
+const clientId = process.env.FINVERSE_CLIENTID;
+const clientSecret = process.env.FINVERSE_SECRET;
+const redirectUri = process.env.REDIRECT_URI;
 
 const configuration = new Configuration({ basePath: apiHost });
-// Obtain customer access token
 const customerTokenResp = await new PublicApi(configuration).generateCustomerAccessToken({
-	client_id: clientId,
-	client_secret: clientSecret,
-	grant_type: 'client_credentials',
+  client_id: clientId,
+  client_secret: clientSecret,
+  grant_type: 'client_credentials',
 });
 
-const customerAccessToken = customerTokenResp.access_token
+const customerAccessToken = customerTokenResp.data.access_token;
 ```
 
-### 2. Create payment instruction
-```typescript
-    const configuration = new Configuration({ basePath: config.apiHost, accessToken: customerToken.access_token });
-    const paymentInstruction: CustomerPaymentInstruction = {
-      type: "DEBIT_AUTHORIZATION",
-      user_id: "customer_user1",
-      frequency: "MONTHLY",
-      start_date: "2022-04-01",
-      end_date: "2022-12-01",
-      amount: 1000,
-      currency: "PHP",
-      recipient_name: "HOMECREDIT",
-      recipient_account_id: "Recipient Account Id",
-      sender_name: "Sender Name",
-      sender_account_id: "LOAN102345",
-      remarks: "HOME CREDIT REPAYMENT"
-    };
-    const createPaymentInstructionResponse = await new CustomerApi(configuration).createPaymentInstruction(paymentInstruction);
-
-    // createPaymentInstructionResponse.data.payment_instruction_id can be used to retrieve the status
-```
+#### 2. Link New Institution: Obtain Link Token and Link URL
 
-### 3. Link with payment instruction: Obtain Link Token and Link URL to launch Finverse Link UI
 ```typescript
-// generate a link token
-
-// reference back to your system userId, finverse does not use this
-const userId = "someUserId"     
-// this will be sent in the redirectUri callback, can be used to identify the state
-const state = "someUniqueState" 
-const configuration = new Configuration({ 
-  basePath: apiHost, 
-	accessToken: customerToken.access_token
+import { CustomerApi } from '@finverse/sdk-typescript';
+
+const userId = "someUserId";
+const state = "someUniqueState";
+const linkConfig = new Configuration({
+  basePath: apiHost,
+  accessToken: customerAccessToken,
 });
-const linkTokenResp = await new CustomerApi(configuration).generateLinkToken({
-	client_id:     clientId,
-  user_id:       userId,
-  redirect_uri:  redirectUri,
-  state:        state,
+const linkTokenResp = await new CustomerApi(linkConfig).generateLinkToken({
+  client_id: clientId,
+  user_id: userId,
+  redirect_uri: redirectUri,
+  state: state,
   response_mode: "form_post",
   response_type: "code",
-	grant_type:    "client_credentials",
-  payment_instruction_id: createPaymentInstructionResponse.data.payment_instruction_id,
-  products_requested: "PAYMENTS",
+  grant_type: "client_credentials",
 });
 
-// The linkUrl can be used to initiate Finverse Link
-console.log("linkUrl: " + linkTokenResp.link_url)
+console.log("linkUrl:", linkTokenResp.data.link_url);
 ```
 
-### 4. Finalize linking: Exchange code for Login Identity Access Token
+#### 3. Finalize Linking: Exchange Code for Login Identity Access Token
+
 ```typescript
-// when Finverse Link UI is successful, obtain the code from Finverse Link
-// exchange it for a Login Identity Access Token
-const code = "obtainAfterLink"
-const configuration = new Configuration({ 
-	basePath: apiHost, 
-	accessToken: customerToken.access_token 
-});
-const loginIdentityTokenResp = await new LinkApi(configuration).token(
-	"authorization_code",
-	code,
-	clientId,
-	redirectURI,
+import { LinkApi } from '@finverse/sdk-typescript';
+
+const code = "obtainAfterLink"; // from Finverse Link UI callback
+const loginIdentityTokenResp = await new LinkApi(linkConfig).token(
+  "authorization_code",
+  code,
+  clientId,
+  redirectUri,
 );
+const loginIdentityToken = loginIdentityTokenResp.data.access_token;
+```
+
+#### 4. Retrieve data: Get Login Identity
 
-// The loginIdentityToken can be used to retrieve data
-const loginIdentityToken = loginIdentityTokenResp.access_token
+```typescript
+import { LoginIdentityApi } from '@finverse/sdk-typescript';
+
+const dataConfig = new Configuration({
+  basePath: apiHost,
+  accessToken: loginIdentityToken,
+});
+const loginIdentityResp = await new LoginIdentityApi(dataConfig).getLoginIdentity();
+console.log("login identity:", loginIdentityResp.data.login_identity);
 ```
 
-### 5. Poll loginIdentityStatus until ready
-Alternatively you can use webhook to receive LoginIdentity event.
+#### 5. Poll Login Identity Status Until Ready
 
 ```typescript
+import type { AxiosResponse } from 'axios';
+import type { GetLoginIdentityByIdResponse } from '@finverse/sdk-typescript';
+
 enum FinalStatus {
-	ERROR = 'ERROR',
-	CONNECTION_COMPLETE= 'CONNECTION_COMPLETE',
+  ERROR = 'ERROR',
+  DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL = 'DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL',
+  DATA_RETRIEVAL_COMPLETE = 'DATA_RETRIEVAL_COMPLETE',
 }
 
-const configuration = new Configuration({
-	basePath: apiHost,
-	accessToken: loginIdentityToken.access_token 
-});
 let loginIdentity: AxiosResponse<GetLoginIdentityByIdResponse>;
-
-// Poll until loginIdentityStatus is ready
 for (let i = 0; i < 20; i++) {
-	loginIdentity = await new LoginIdentityApi(configuration).getLoginIdentity();
-	const loginIdentityStatus = loginIdentity.data.login_identity.status;
-	if ( 
-	  loginIdentityStatus === FinalStatus.ERROR ||
-	  loginIdentityStatus === FinalStatus.CONNECTION_COMPLETE
-	) { break; }
-	
-	await new Promise((resolve) => setTimeout(resolve, 3000));
+  loginIdentity = await new LoginIdentityApi(dataConfig).getLoginIdentity();
+  const status = loginIdentity.data.login_identity.status;
+  if (
+    status === FinalStatus.ERROR ||
+    status === FinalStatus.DATA_RETRIEVAL_COMPLETE ||
+    status === FinalStatus.DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL
+  ) {
+    break;
+  }
+  await new Promise((resolve) => setTimeout(resolve, 3000));
 }
+```
+
+#### 6. Get Accounts
 
-console.log("login identity: " + loginIdentityResp.login_identity)
+```typescript
+const accountsResp = await new LoginIdentityApi(dataConfig).listAccounts();
+console.log("accounts:", accountsResp.data.accounts);
 ```
 
-### 6. Get payment instruction status
+#### 7. Get Transactions (with pagination)
+
 ```typescript
-    const configuration = new Configuration({ basePath: config.apiHost, accessToken: customerToken.access_token });
-    const getPaymentInstructionResponse = await new CustomerApi(configuration).getPaymentInstruction(createPaymentInstructionResponse.data.payment_instruction_id);
+let offset = 0;
+while (true) {
+  const transactionsResp = await new LoginIdentityApi(dataConfig).listTransactionsByLoginIdentityId(
+    offset,
+    500  // limit: default 500, max 1000
+  );
+  const transactions = transactionsResp.data.transactions ?? [];
+  console.log(`total: ${transactionsResp.data.total_transactions}, transactions: ${transactions.length}`);
+  offset += transactions.length;
+  if (offset >= transactionsResp.data.total_transactions) {
+    break;
+  }
+}
+```
 
-    console.log("paymentInstruction status: " + getPaymentInstructionResponse.data.payment_instruction.status);
+#### 8. Get Statements
+
+```typescript
+import { writeFileSync } from 'fs';
+
+const statementsResp = await new LoginIdentityApi(dataConfig).getStatements();
+const statements = statementsResp.data.statements ?? [];
+console.log("statements:", statements);
+
+// Download a statement (assuming at least one exists)
+const statementId = statements[0].id;
+const statementResp = await new LoginIdentityApi(dataConfig).getStatement(
+  statementId,
+  true,
+  { responseType: "arraybuffer" }
+);
+writeFileSync("statement.pdf", Buffer.from(statementResp.data));
 ```
+
+---
+
+## Best Practices
+
+### Use async/await
+
+All SDK methods return Promises. Use `async/await` for cleaner, readable code and to avoid callback hell:
+
+```typescript
+async function fetchAccounts() {
+  const config = new Configuration({ basePath: apiHost, accessToken: token });
+  const response = await new LoginIdentityApi(config).listAccounts();
+  return response.data.accounts;
+}
+```
+
+### Handle API responses correctly
+
+API methods return Axios `AxiosResponse` objects. Access the payload via `.data`:
+
+```typescript
+const tokenResp = await new PublicApi(config).generateCustomerAccessToken({ ... });
+const accessToken = tokenResp.data.access_token;  // Correct: use .data
+
+const accountsResp = await new LoginIdentityApi(config).listAccounts();
+const accounts = accountsResp.data.accounts;  // Correct: use .data
+```
+
+### Use exported types and interfaces
+
+Leverage the SDK's exported types for type safety and better IDE support:
+
+```typescript
+import type {
+  Account,
+  CreatePaymentRequest,
+  GetLoginIdentityByIdResponse,
+} from '@finverse/sdk-typescript';
+
+const paymentRequest: CreatePaymentRequest = {
+  // ...
+};
+```
+
+### Handle errors with try/catch
+
+Wrap API calls in try/catch blocks. API errors are returned as HTTP error responses; the SDK may throw on network failures or validation errors:
+
+```typescript
+import axios from 'axios';
+
+try {
+  const response = await new LoginIdentityApi(config).listAccounts();
+  return response.data.accounts;
+} catch (error) {
+  if (axios.isAxiosError(error) && error.response) {
+    console.error("API error:", error.response.status, error.response.data);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Handle validation errors
+
+When required parameters are missing, the SDK throws errors. Wrap API calls in try/catch to handle validation and other failures gracefully.
+
+### Reuse Configuration instances
+
+Create a `Configuration` once per token/context and reuse it for multiple API calls:
+
+```typescript
+const config = new Configuration({
+  basePath: apiHost,
+  accessToken: customerAccessToken,
+});
+const customerApi = new CustomerApi(config);
+const linkTokenResp = await customerApi.generateLinkToken({ ... });
+const paymentResp = await customerApi.createPayment(paymentRequest);
+```
+
+### Client secret: never commit, server-side only
+
+**Never commit your client secret to version control.** The client secret must remain confidential and be used only on the server.
+
+- **Server-side only:** This SDK is designed for backend use. Never expose `client_secret` to the browser, mobile apps, or any client-side code.
+- **Use environment variables or a secrets manager:** Load credentials at runtime from secure storage.
+- **Add to `.gitignore`:** Ensure `.env` and any files containing secrets are never committed.
+
+```typescript
+// ✅ Correct: Load from environment (server-side only)
+const clientId = process.env.FINVERSE_CLIENTID;
+const clientSecret = process.env.FINVERSE_SECRET;  // Never log, never send to client
+const redirectUri = process.env.REDIRECT_URI;
+```
+
+### Payment idempotency
+
+For payment and mandate operations, use idempotency keys to safely retry requests without creating duplicate payments. If a request fails due to network issues, you can retry with the same key—the API will return the original result instead of creating a duplicate.
+
+**Methods that support idempotency keys:** `createPayment`, `createMandate`, `createMandateForExistingSender` (DefaultApi), `createScheduledPayout` (DefaultApi).
+
+```typescript
+import { CustomerApi } from '@finverse/sdk-typescript';
+import crypto from 'crypto';
+
+// Generate a unique key per logical operation (e.g., per checkout or mandate setup)
+const idempotencyKey = crypto.randomUUID();
+
+// Safe to retry—same key returns same result
+await new CustomerApi(config).createPayment(paymentRequest, idempotencyKey);
+await new CustomerApi(config).createMandate(mandateRequest, idempotencyKey);
+```
+
+**Best practices:**
+- Use one idempotency key per unique payment or mandate.
+- Store the key with your order/mandate record so you can retry with the same key if needed.
+
+---
+
+## Resources for AI Agents
+
+For AI agents implementing Finverse integrations, the [Finverse AI repository](https://github.com/finversetech/ai) contains skills, implementation guides, and reference documentation for payment flows, data retrieval, and other Finverse API patterns. Follow this link for detailed integration instructions: https://github.com/finversetech/ai